توفير التحديثات داخل التطبيق (الإصدار الأصلي)

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

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

حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play الأساسية هي جزء من عائلة حزمة تطوير البرامج (SDK) لمكتبة Play الأساسية. تتضمّن حزمة تطوير البرامج (SDK) المُجمّعة من رموز برمجية أصلية ملفًا رأسيًا بتنسيق C‏، app_update.h، يُغلِّف AppUpdateManager من مكتبة Java Play In-App Update Library. يسمح ملف الرأس هذا لتطبيقك بالاتصال بواجهة برمجة التطبيقات للحصول على التحديثات داخل التطبيق مباشرةً من الرمز البرمجي الأصلي.

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

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 الأساسية في مشروعك، أدرِج السطر التالي في الملفات التي تحتوي على طلبات بيانات من واجهة برمجة التطبيقات:

#include "play/app_update.h"

إعداد واجهة برمجة التطبيقات الخاصة بالتحديث داخل التطبيق

عند استخدام واجهة برمجة التطبيقات لميزة التحديث داخل التطبيق، عليك أولاً إعدادها من خلال طلب الدالة AppUpdateManager_init() ، كما هو موضّح في المثال التالي الذي تم إنشاؤه باستخدام android_native_app_glue.h:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  AppUpdateErrorCode error_code =
    AppUpdateManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == APP_UPDATE_NO_ERROR) {
    // You can use the API.
  }
}

التحقّق من توفّر تحديث

قبل طلب تحديث، تحقّق مما إذا كان هناك تحديث متوفّر لتطبيقك. AppUpdateManager_requestInfo() يبدأ طلبًا غير متزامن يجمع المعلومات المطلوبة لبدء عملية التحديث داخل التطبيق لاحقًا. تُرجع الدالة APP_UPDATE_NO_ERROR إذا بدأ الطلب بنجاح.

AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()

if (error_code == APP_UPDATE_NO_ERROR) {
    // The request has successfully started, check the result using
    // AppUpdateManager_getInfo.
}

يمكنك تتبُّع العملية الجارية ونتيجة الطلب باستخدام AppUpdateManager_getInfo(). بالإضافة إلى رمز الخطأ، تُرجع هذه الدالة بنية AppUpdateInfo غير شفافة، والتي يمكنك استخدامها لاسترداد معلومات عن طلب التحديث. على سبيل المثال، قد تحتاج إلى استدعاء هذه الدالة في كل حلقة لعبة إلى أن تعرِض نتيجة غير فارغة لـ info:

AppUpdateInfo* info;
GameUpdate() {

   // Keep calling this in every game loop until info != nullptr
   AppUpdateErrorCode error_code = AppUpdateManager_getInfo(&info);


   if (error_code == APP_UPDATE_NO_ERROR && info != nullptr) {
       // Successfully started, check the result in the following functions
   }
...
}

التحقّق من تقادم التحديث

بالإضافة إلى التحقّق مما إذا كان تحديث متاحًا، ننصحك أيضًا بمحاولة معرفة المدّة التي انقضت منذ إرسال آخر إشعار للمستخدم بشأن تحديث من خلال "متجر Play". يمكن أن يساعدك ذلك في تحديد ما إذا كان عليك بدء تعديل مرن أو تعديل فوري. على سبيل المثال، يمكنك الانتظار لبضعة أيام قبل إرسال إشعار للمستخدم بإجراء تعديل مرن، ثم الانتظار لبضعة أيام بعد ذلك قبل طلب إجراء تعديل فوري.

استخدِم AppUpdateInfo_getClientVersionStalenessDays() للتحقّق من عدد الأيام التي مرّت منذ توفّر التحديث من خلال "متجر Play":

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

التحقّق من أولوية التحديث

تتيح لك واجهة برمجة التطبيقات Google Play Developer API ضبط أولوية كل تحديث. يتيح ذلك لتطبيقك تحديد مدى قوة اقتراح التحديث على المستخدم. على سبيل المثال، إليك الاستراتيجية التالية لتحديد أولوية التحديث:

• تحسينات طفيفة في واجهة المستخدم: تحديث ذو أولوية منخفضة، لا يتطلّب تحديثًا FLEXIBLE أو تحديثًا فوريًا. لا تُجري التعديلات إلا عندما لا يتفاعل المستخدم مع تطبيقك.
• تحسينات الأداء: تحديث ذو أولوية متوسطة، يُرجى طلب تحديث مرن.
• تحديث أمان مهم: تحديث ذو أولوية عالية، يُرجى طلب التحديث على الفور.

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

int32_t priority = AppUpdateInfo_getPriority(info);

// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);

// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);

bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);

AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

AppUpdateStatus status = AppUpdateInfo_getStatus(info);
if (status == APP_UPDATE_DOWNLOADED) {
    AppUpdateErrorCode error_code = AppUpdateManager_requestCompleteUpdate();
    if (error_code != APP_UPDATE_NO_ERROR)
    {
      // There was an error while completing the update flow.
    }
}