دمج المراجعات داخل التطبيق (أصلية)

يوضّح هذا الدليل كيفية دمج المراجعات داخل التطبيق باستخدام رمز برمجي أصلي (C أو C++). تتوفّر أدلة دمج منفصلة إذا كنت تستخدم Kotlin أو Java أو Unity أو Unreal Engine.

نظرة عامة على حِزم تطوير البرامج (SDK) الأصلية

تشكّل حزمة تطوير البرامج (SDK) لـ Play Core Native جزءًا من عائلة مكتبات Google Play Core. تتضمّن مكتبة SDK الأصلية لـ Play Core ملفًا رأسيًا بتنسيق C‏، review.h، يُغلِّف ReviewManager من مكتبات Java Play In-App Review. يسمح ملف الرأس هذا لتطبيقك باستدعاء واجهة برمجة التطبيقات مباشرةً من الرمز البرمجي الأصلي. للحصول على نظرة عامة على الدوال العامة المتاحة، يُرجى الاطّلاع على مستندات الوحدة الأساسية لمراجعة التطبيقات على Play.

يبدأ ReviewManager_requestReviewFlow طلبًا يجمع المعلومات المطلوبة لبدء عملية المراجعة داخل التطبيق لاحقًا. يمكنك متابعة نتيجة الطلب باستخدام ReviewManager_getReviewStatus. للحصول على مزيد من المعلومات عن جميع الحالات التي يمكن أن يعرضها ReviewManager_getReviewStatus ، اطّلِع على ReviewErrorCode.

تعرض كلّ من الدالتَين request وlaunch القيمة REVIEW_NO_ERROR في حال نجاح الدالة.

إعداد بيئة التطوير

1. عليك القيام بأي مما يلي:

   • ثبِّت الإصدار 4.0 من Android Studio أو إصدار أحدث. استخدِم واجهة مستخدم "مدير حزمة SDK" لتثبيت الإصدار 10.0 من نظام Android SDK (المستوى 29 من واجهة برمجة التطبيقات).
   • ثبِّت أدوات سطر الأوامر في حزمة تطوير البرامج (SDK) لنظام التشغيل Android واستخدِم sdkmanager لتثبيت الإصدار 10.0 من نظام Android الأساسي لحزمة تطوير البرامج (SDK) (المستوى 29 لواجهة برمجة التطبيقات).

2. حضِّر "استوديو Android" للتطوير الأصلي باستخدام مدير حِزم SDK لتثبيت أحدث إصدار من CMake ومجموعة تطوير البرامج الأصلية لنظام التشغيل Android ‏ (NDK). لمزيد من المعلومات حول إنشاء مشاريع أصلية أو استيرادها، يُرجى الاطّلاع على مقالة البدء في استخدام حزمة NDK.

3. نزِّل ملف zip واحفظه بجانب مشروعك.

   رابط التنزيل	الحجم	المجموع الاختباري لخوارزمية SHA-256
   play-core-native-sdk-1.15.3.zip	‫37.8 ميغابايت	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

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.4.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")
           ...
       }
       

   Kotlin

   // 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.4.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 SDK بيانات ذات صلة بالإصدار للسماح لشركة Google بمحاولة تحسين المنتج، بما في ذلك:

• اسم حزمة التطبيق
• إصدار حزمة التطبيق
• إصدار حزمة تطوير البرامج (SDK) الأصلية من Play Core

سيتم جمع هذه البيانات عند تحميل حِزمة تطبيقك إلى Play Console. لإيقاف عملية جمع البيانات هذه، عليك إزالة العبارة $playcoreDir/playcore-native-metadata.jar import في ملف build.gradle.

يُرجى العِلم أنّ عملية جمع البيانات هذه المتعلّقة باستخدامك لحزمة تطوير البرامج (SDK) الأصلية من Play Core واستخدام Google للبيانات التي تم جمعها منفصلة ومستقلة عن عملية جمع Google لمستلزمات المكتبة المُعلَن عنها في Gradle عند تحميل حزمة تطبيقك إلى Play Console.

بعد دمج حزمة SDK لتطبيقات Play Core الأصلية في مشروعك، أدرِج السطر التالي في الملفات التي تحتوي على طلبات بيانات من واجهة برمجة التطبيقات:

تضمين review.h

بعد دمج حزمة تطوير البرامج (SDK) Play Core Native في مشروعك، أدرِج السطر التالي في الملفات التي ستتضمّن طلبات بيانات من واجهة برمجة التطبيقات:

#include "play/review.h"

إعداد واجهة برمجة التطبيقات Review 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، مثلاً مرة واحدة في كل لقطة. قد يستغرق ذلك up to a couple of seconds، لذا عليك بدء هذه العملية قبل أن يصل تطبيقك إلى النقطة التي تريد فيها عرض مسار المراجعة داخل التطبيق.

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;
}

بعد بدء عملية المراجعة داخل التطبيق، يُرجى التحقّق من حالة اكتمالها ومواصلة مسار التطبيق. من الطرق الشائعة معالجة ذلك هو اتّباع نمط حلقة اللعب.

المراجع المجانية

لا تنسَ تحرير الموارد من خلال طلب الدالة ReviewManager_destroy بعد انتهاء تطبيقك من استخدام واجهة برمجة التطبيقات (على سبيل المثال، بعد اكتمال تدفق المراجعة داخل التطبيق).

void ReviewManager_destroy();

الخطوات التالية

اختبِر مسار المراجعة داخل تطبيقك للتأكّد من أنّ عملية الدمج تعمل بشكلٍ سليم.