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

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

نظرة عامة على حِزم SDK الأصلية

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

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

تعرض كلّ من دالتي الطلب والتشغيل القيمة REVIEW_NO_ERROR في حال نجاح الدالة.

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

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

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

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

3. نزِّل ملف ZIP واستخرِجه بجانب مشروعك.

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

4. عدِّل ملف build.gradle الخاص بتطبيقك كما هو موضّح أدناه:

   Groovy

       // 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
           ...)
   

جمع البيانات

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

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

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

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

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

تضمين review.h

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

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

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

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