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

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

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

حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play الأساسية هي جزء من مكتبات Google Play الأساسية. تتضمّن حزمة تطوير البرامج (SDK) الأصلية من "مكتبة Play الأساسية" ملفًا رأسيًا بتنسيق 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 من منصّة حزمة تطوير البرامج (SDK) لنظام التشغيل Android (المستوى 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.2.2'
           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.2.2")
       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
           ...)
   

جمع البيانات

قد تجمع حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play الأساسية بيانات ذات صلة بالإصدار للسماح لشركة Google بمحاولة تحسين المنتج، بما في ذلك:

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

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

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

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

تضمين review.h

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

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

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();

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

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