این راهنما نحوه ادغام مرورهای درون‌برنامه را در برنامه‌تان بااستفاده از کد بومی (C یا C++) شرح می‌دهد. اگر از Kotlin یا Java، Unity، یا Unreal Engine استفاده می‌کنید، راهنماهای ادغام جداگانه‌ای وجود دارد.
نمای کلی کیت توسعه نرم‌افزار بومی
«کیت توسعه نرم‌افزار بومی هسته Play» بخشی از خانواده کتابخانه‌های هسته Google Play است. کیت توسعه نرم‌افزار Play Core Native شامل یک فایل سرایند C، review.h، است که
ReviewManager را از کتابخانه‌های Java Play In-App Review می‌پوشاند. این فایل سرایند به برنامه شما اجازه می‌دهد API را مستقیماً از کد بومی‌تان فراخوانی کند. برای
نمای کلی عملکردهای عمومی دردسترس، به اسناد ماژول بومی
Play Review مراجعه کنید.
ReviewManager_requestReviewFlow درخواستی را شروع می‌کند که اطلاعات لازم برای راه‌اندازی جریان مرور درون‌برنامه را در آینده جمع‌آوری می‌کند. می‌توانید
نتیجه درخواست را بااستفاده از ReviewManager_getReviewStatus پیگیری کنید. برای
اطلاعات بیشتر درباره همه وضعیت‌هایی که ReviewManager_getReviewStatus می‌تواند
برگرداند، ReviewErrorCode را ببینید.
اگر تابع موفق شود، هر دو تابع درخواست و راه‌اندازی REVIEW_NO_ERROR را برمی‌گردانند.
راه‌اندازی محیط توسعه نرم‌افزار
دانلود کنید Play Core Native SDK
قبل از دانلود، باید با شرایط و ضوابط زیر موافقت کنید.
شرایط و ضوابط
Last modified: September 24, 2020- By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
- For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
- “Redistributable Code” means Google-provided object code or header files that call the APIs.
- Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
- Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.
یکی از کارهای زیر را انجام دهید:
- Android Studio نسخه ۴.۰ یا بالاتر را نصب کنید. از میانای کاربر «مدیر کیت توسعه نرم‌افزار» برای نصب نسخه ۱۰.۰ پلاتفرم کیت توسعه نرم‌افزار Android (سطح میانای برنامه‌سازی کاربردی ۲۹) استفاده کنید.
- ابزارهای خط فرمان کیت توسعه نرم‌افزار Android را نصب کنید
و از
sdkmanagerبرای نصب نسخه ۱۰.۰ پلاتفرم کیت توسعه نرم‌افزار Android (سطح میانای برنامه‌سازی کاربردی ۲۹) استفاده کنید.
بااستفاده از مدیر SDK، «استودیو Android» را برای توسعه بومی آماده کنید تا جدیدترین نسخه‌های CMake و «کیت توسعه بومی Android» (NDK) را نصب کنید. برای اطلاعات بیشتر درباره ایجاد یا وارد کردن پروژه‌های بومی، به شروع به کار با NDK مراجعه کنید.
فایل zip را بارگیری کنید و آن را در کنار پروژه‌تان از حالت فشرده خارج کنید.
بارگیری پیوند اندازه جمع‌آزمای SHA-256 ۵۴٫۸ مبی‌بایت 008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0 فایل
build.gradleبرنامه‌تان را به‌صورت زیر به‌روز کنید:شیک
// App build.gradle plugins { id 'com.android.application' } // Define a path to the extracted Play Core SDK files. // If using a relative path, wrap it with file() since CMake requires absolute paths. def playcoreDir = file('../path/to/playcore-native-sdk') android { defaultConfig { ... externalNativeBuild { cmake { // Define the PLAYCORE_LOCATION directive. arguments "-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir" } } ndk { // Skip deprecated ABIs. Only required when using NDK 16 or earlier. abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64' } } buildTypes { release { // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI. proguardFile '$playcoreDir/proguard/common.pgcfg' proguardFile '$playcoreDir/proguard/gms_task.pgcfg' proguardFile '$playcoreDir/proguard/per-feature-proguard-files' ... } debug { ... } } externalNativeBuild { cmake { path 'src/main/CMakeLists.txt' } } } dependencies { // Import these feature-specific AARs for each Google Play Core library. implementation 'com.google.android.play:app-update:2.1.0' implementation 'com.google.android.play:asset-delivery:2.3.0' implementation 'com.google.android.play:integrity:1.6.0' implementation 'com.google.android.play:review:2.0.2' // Import these common dependencies. implementation 'com.google.android.gms:play-services-tasks:18.0.2' implementation files("$playcoreDir/playcore-native-metadata.jar") ... }
کاتلین
// App build.gradle plugins { id("com.android.application") } // Define a path to the extracted Play Core SDK files. // If using a relative path, wrap it with file() since CMake requires absolute paths. val playcoreDir = file("../path/to/playcore-native-sdk") android { defaultConfig { ... externalNativeBuild { cmake { // Define the PLAYCORE_LOCATION directive. arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir") } } ndk { // Skip deprecated ABIs. Only required when using NDK 16 or earlier. abiFilters.clear() abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64") } } buildTypes { release { // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI. proguardFile("$playcoreDir/proguard/common.pgcfg") proguardFile("$playcoreDir/proguard/gms_task.pgcfg") proguardFile("$playcoreDir/proguard/per-feature-proguard-files") ... } debug { ... } } externalNativeBuild { cmake { path = "src/main/CMakeLists.txt" } } } dependencies { // Import these feature-specific AARs for each Google Play Core library. implementation("com.google.android.play:app-update:2.1.0") implementation("com.google.android.play:asset-delivery:2.3.0") implementation("com.google.android.play:integrity:1.6.0") implementation("com.google.android.play:review:2.0.2") // Import these common dependencies. implementation("com.google.android.gms:play-services-tasks:18.0.2") implementation(files("$playcoreDir/playcore-native-metadata.jar")) ... }
فایل‌های
CMakeLists.txtبرنامه‌تان را همان‌طور که در زیر نشان داده شده است به‌روز کنید:cmake_minimum_required(VERSION 3.6) ... # Add a static library called “playcore” built with the c++_static STL. include(${PLAYCORE_LOCATION}/playcore.cmake) add_playcore_static_library() // In this example “main” is your native code library, i.e. libmain.so. add_library(main SHARED ...) target_include_directories(main PRIVATE ${PLAYCORE_LOCATION}/include ...) target_link_libraries(main android playcore ...)
گردآوری داده‌ها
«کیت توسعه نرم‌افزار Play Core Native» ممکن است داده‌های مربوط به نسخه را جمع‌آوری کند تا به Google اجازه دهد محصول را بهبود بخشد، ازجمله:
- نام بسته برنامه
- نسخه بسته برنامه
- نسخه Play Core Native SDK
این داده‌ها هنگام بارگذاری بسته برنامه‌تان در «کنسول Play» جمع‌آوری می‌شود. برای انصراف از این فرایند جمع‌آوری داده،
$playcoreDir/playcore-native-metadata.jar را از فایل build.gradle بردارید.
توجه داشته باشید که این جمع‌آوری داده مربوط به استفاده شما از Play Core Native SDK و استفاده Google از داده‌های جمع‌آوری‌شده جدا و مستقل از جمع‌آوری وابستگی‌های کتابخانه توسط Google است که در Gradle هنگام بارگذاری بسته برنامه‌تان در «کنسول Play» اعلام شده است.
پس‌از ادغام Play Core Native SDK در پروژه‌تان، خط زیر را در فایل‌هایی که حاوی فراخوانی‌های API هستند اضافه کنید:
Include review.h
پس‌از ادغام Play Core Native SDK در پروژه‌تان، خط زیر را در فایل‌هایی که حاوی فراخوانی‌های API هستند اضافه کنید:
#include "play/review.h"
مقداردهی اولیه Review API
هرزمان که می‌خواهید از API استفاده کنید، ابتدا باید آن را با فراخوانی تابع
ReviewManager_init مقداردهی اولیه کنید، همان‌طور که در مثال زیر که با
android_native_app_glue.h ساخته شده است نشان داده شده است:
void android_main(android_app* app) {
app->onInputEvent = HandleInputEvent;
ReviewErrorCode error_code = ReviewManager_init(app->activity->vm, app->activity->clazz);
if (error_code == REVIEW_NO_ERROR) {
// You can use the API.
}
}
درخواست جریان مرور درون‌برنامه‌ای
راهنمایی‌های مربوط به زمان درخواست مرورهای درون‌برنامه را دنبال کنید تا نقاط مناسب در جریان کاربر برنامه‌تان را برای درخواست مرور از کاربر تعیین کنید (برای مثال، پس‌از اینکه کاربر صفحه خلاصه را در پایان یک سطح در بازی رد می‌کند). وقتی
برنامه‌تان به یکی از این نقاط نزدیک می‌شود،
ReviewManager_requestReviewFlow را فراخوانی کنید تا به‌طور ناهمگام اطلاعاتی را که برنامه‌تان برای راه‌اندازی جریان مرور درون‌برنامه نیاز دارد درخواست کند. پیشرفت عملیات
ReviewManager_requestReviewFlow را با فراخوانی
ReviewManager_getReviewStatus، برای مثال یک‌بار در هر فریم، پایش کنید. این کار ممکن است چند ثانیه طول بکشد، بنابراین باید این فرایند را قبل‌از اینکه برنامه‌تان به نقطه‌ای برسد که می‌خواهید جریان مرور درون‌برنامه را نشان دهید شروع کنید.
ReviewErrorCode error_code = ReviewManager_requestReviewFlow();
if (error_code == REVIEW_NO_ERROR) {
// The request has successfully started, check the status using
// ReviewManager_getReviewStatus.
} else {
// Error such as REVIEW_PLAY_STORE_NOT_FOUND indicating that the in-app
// review isn't currently possible.
}
مدیریت وضعیت‌ها و راه‌اندازی جریان مرور درون‌برنامه
هرزمان که درخواستی شروع شد یا جریان مرور درون‌برنامه راه‌اندازی شد، می‌توانید
وضعیت را بااستفاده از ReviewManager_getReviewStatus بررسی کنید. این کار به شما امکان می‌دهد
منطق را بسته به وضعیت میانای برنامه‌سازی کاربردی تعریف کنید. یک راه برای انجام این کار این است که
وضعیت را به‌عنوان متغیر سراسری نگه دارید و بررسی کنید که آیا وضعیت
REVIEW_REQUEST_FLOW_COMPLETED است وقتی کاربر کنش خاصی را انجام می‌دهد (برای
مثال، تک‌ضرب زدن روی دکمه «مرحله بعدی» در بازی)، همان‌طور که در مثال زیر
نشان داده شده است:
ReviewStatus status;
ReviewErrorCode error_code = ReviewManager_getReviewStatus(&status);
if (error_code != REVIEW_NO_ERROR) {
// There was an error with the most recent operation.
return;
}
switch (status) {
case REVIEW_REQUEST_FLOW_PENDING:
// Request is ongoing. The flow can't be launched yet.
break;
case REVIEW_REQUEST_FLOW_COMPLETED:
// Request completed. The flow can be launched now.
break;
case REVIEW_LAUNCH_FLOW_PENDING:
// The review flow is ongoing, meaning the dialog might be displayed.
break;
case REVIEW_LAUNCH_FLOW_COMPLETED:
// The review flow has finished. Continue with your app flow (for
// example, move to the next screen).
break;
default:
// Unknown status.
break;
}
وقتی وضعیت REVIEW_REQUEST_FLOW_COMPLETED است و برنامه‌تان آماده است،
جریان مرور درون‌برنامه را راه‌اندازی کنید:
// This call uses android_native_app_glue.h. ReviewErrorCode error_code = ReviewManager_launchReviewFlow(app->activity->clazz); if (error_code != REVIEW_NO_ERROR) { // There was an error while launching the flow. return; }
پس‌از راه‌اندازی جریان مرور درون‌برنامه، وضعیت را برای تکمیل بررسی کنید و جریان برنامه‌تان را ادامه دهید. یک روش رایج برای مدیریت این موضوع، دنبال کردن الگوی حلقه بازی است.
منابع رایگان
فراموش نکنید که پس‌از اتمام استفاده برنامه‌تان از API (برای مثال، پس‌از تکمیل جریان مرور درون‌برنامه)، با فراخوانی تابع ReviewManager_destroy منابع را آزاد کنید.
void ReviewManager_destroy();
مراحل بعدی
جریان مرور درون‌برنامه‌ای برنامه‌تان را آزمایش کنید تا مطمئن شوید ادغام شما به‌درستی کار می‌کند.