ادغام کردن مرورهای درون‌برنامه (بومی)

این راهنما نحوه ادغام مرورهای درون‌برنامه را در برنامه‌تان بااستفاده از کد بومی (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 را برمی‌گردانند.

راه‌اندازی محیط توسعه نرم‌افزار

1. یکی از کارهای زیر را انجام دهید:

   • Android Studio نسخه ۴.۰ یا بالاتر را نصب کنید. از میانای کاربر «مدیر کیت توسعه نرم‌افزار» برای نصب نسخه ۱۰.۰ پلاتفرم کیت توسعه نرم‌افزار Android (سطح میانای برنامه‌سازی کاربردی ۲۹) استفاده کنید.
   • ابزارهای خط فرمان کیت توسعه نرم‌افزار Android را نصب کنید و از sdkmanager برای نصب نسخه ۱۰.۰ پلاتفرم کیت توسعه نرم‌افزار Android (سطح میانای برنامه‌سازی کاربردی ۲۹) استفاده کنید.

2. بااستفاده از مدیر SDK، «استودیو Android» را برای توسعه بومی آماده کنید تا جدیدترین نسخه‌های CMake و «کیت توسعه بومی Android»‏ (NDK) را نصب کنید. برای اطلاعات بیشتر درباره ایجاد یا وارد کردن پروژه‌های بومی، به شروع به کار با NDK مراجعه کنید.

3. فایل zip را بارگیری کنید و آن را در کنار پروژه‌تان از حالت فشرده خارج کنید.

   بارگیری پیوند	اندازه	جمع‌آزمای SHA-256
   play-core-native-sdk-1.16.0.zip	‫۵۴٫۸ مبی‌بایت	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. فایل 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"))
       ...
   }

5. فایل‌های 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();

مراحل بعدی

جریان مرور درون‌برنامه‌ای برنامه‌تان را آزمایش کنید تا مطمئن شوید ادغام شما به‌درستی کار می‌کند.