تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

تنزيل Play Core Native SDK

قبل تنزيل التطبيق، عليك الموافقة على الأحكام والشروط التالية.

الأحكام والشروط

Last modified: September 24, 2020

By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
“Redistributable Code” means Google-provided object code or header files that call the APIs.
Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.

لقد قرأتُ الأحكام والشروط أعلاه وأوافق عليها.

تنزيل Play Core Native SDK

play-core-native-sdk-1.15.3.zip

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

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

رابط التنزيل	الحجم	المجموع الاختباري لخوارزمية SHA-256
	‫37.8 ميغابايت	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

عدِّل ملف 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"))
    ...
}

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

#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 ضبط أولوية كل تحديث. ويتيح ذلك لتطبيقك تحديد مدى قوة اقتراح التحديث على المستخدم. على سبيل المثال، يمكنك اتّباع الاستراتيجية التالية لتحديد أولوية التحديث:

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

لتحديد الأولوية، يستخدم Google Play قيمة عددية تتراوح بين 0 و5، وتكون القيمة 0 هي القيمة التلقائية والقيمة 5 هي أعلى قيمة. لتحديد الأولوية لأحد التحديثات، استخدِم الحقل inAppUpdatePriority ضمن Edits.tracks.releases في Google Play Developer API. تُعتبَر جميع الإصدارات المُضافة حديثًا في الإصدار ذات الأولوية نفسها التي يحظى بها الإصدار. لا يمكن ضبط الأولوية إلا عند طرح إصدار جديد، ولا يمكن تغييرها لاحقًا.

اضبط الأولوية باستخدام Google Play Developer API، كما هو موضّح في مستندات Play Developer API. حدِّد أولوية التحديث داخل التطبيق في مادة العرض Edit.tracks التي تم تمريرها في طريقة Edit.tracks: update. يوضّح المثال التالي عملية طرح تطبيق برمز الإصدار 88 وinAppUpdatePriority 5:

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

في رمز تطبيقك، يمكنك التحقّق من مستوى الأولوية لتحديث معيّن باستخدام رمز AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

بدء تحديث

بعد تأكيد توفّر تحديث، يمكنك طلب تحديث باستخدام AppUpdateManager_requestStartUpdate(). قبل طلب إجراء تحديث، احصل على عنصر AppUpdateInfo محدّث وأنشئ عنصر AppUpdateOptions لضبط عملية التحديث. يحدِّد عنصر AppUpdateOptions options لخطوات التحديث داخل التطبيق، بما في ذلك ما إذا كان التحديث يجب أن يكون مرنًا أو فوريًا.

ينشئ المثال التالي عنصر AppUpdateOptions لعملية تعديل مرنة:

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

ينشئ المثال التالي عنصر AppUpdateOptions لتدفّق تعديل فوري:

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

يحتوي عنصر AppUpdateOptions أيضًا على حقل AllowAssetPackDeletion الذي يحدِّد ما إذا كان يُسمح للتحديث بمحو حِزم مواد العرض في حال كانت مساحة التخزين على الجهاز محدودة. يتم ضبط هذا الحقل على false تلقائيًا، ولكن يمكنك استخدام طريقة AppUpdateOptions_setAssetPackDeletionAllowed() لضبطه على true بدلاً من ذلك:

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

بعد الحصول على عنصر AppUpdateInfo محدّث وAppUpdateOptions تم ضبطه بشكل صحيح، يمكنك استدعاء AppUpdateManager_requestStartUpdate() لطلب تدفق تعديل بشكل غير متزامن، مع إدخال jobject نشاط Android للمَعلمة النهائية.

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

لإخلاء الموارد، يمكنك إلغاء حجز مثيّلات AppUpdateInfo و AppUpdateOptions التي لم تعُد بحاجة إليها من خلال استدعاء AppUpdateInfo_destroy() وAppUpdateOptions_destroy()، على التوالي.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

لبدء عملية التحديث الفوري، يعرض Google Play صفحة تأكيد للمستخدم. عندما يقبل المستخدم الطلب، ينزِّل Google Play التحديث تلقائيًا ويمثِّله في المقدّمة، ثم يعيد تشغيل التطبيق بالإصدار المعدَّل في حال نجاح التثبيت.

للحصول على عملية تحديث مرنة، يمكنك مواصلة طلب عناصر AppUpdateInfo محدَّثة لتتبُّع حالة التحديث الحالية بينما يواصل المستخدم التفاعل مع التطبيق. بعد انتهاء عملية التنزيل بنجاح، يجب بدء إكمال التحديث من خلال استدعاء AppUpdateManager_requestCompleteUpdate()، كما هو موضّح في المثال التالي:

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

يمكنك تحرير الموارد من خلال استدعاء الدالة AppUpdateManager_destroy() بعد انتهاء تطبيقك من استخدام واجهة برمجة التطبيقات.

معالجة الأخطاء

يوضّح هذا القسم حلول الأخطاء الشائعة التي تشير إليها قيم AppUpdateErrorCode معيّنة:

يشير رمز الخطأ -110, APP_UPDATE_INITIALIZATION_NEEDED إلى أنّه لم يتم إعداد واجهة برمجة التطبيقات بنجاح. استدعاء AppUpdateManager_init() لبدء واجهة برمجة التطبيقات
يشير رمز الخطأ -4, APP_UPDATE_INVALID_REQUEST إلى أنّ تنسيق بعض المَعلمات في طلب عملية التعديل غير صحيح. تأكَّد من أنّ عنصرَي AppUpdateInfo وAppUpdateOptions ليسا فارغَين وأنّهما منسَّقان بشكل صحيح.
يشير رمز الخطأ -5, APP_UPDATE_UNAVAILABLE إلى عدم توفّر تحديث ينطبق على جهازك. تأكَّد من أنّ الإصدار المستهدَف يتضمّن اسم الحزمة ومعرّف التطبيق ومفتاح التوقيع نفسه. إذا كان هناك تحديث متاح، يمكنك محو ذاكرة التخزين المؤقت للتطبيق والاتصال برقم AppUpdateManager_requestAppUpdateInfo() مرة أخرى لإعادة تحميل AppUpdateInfo.
يشير رمز الخطأ -6, APP_UPDATE_NOT_ALLOWED إلى أنّ نوع التعديل الذي يشير إليه العنصر AppUpdateOption غير مسموح به. تحقّق مما إذا كان عنصر AppUpdateInfo يشير إلى أنّ نوع التعديل مسموح به قبل بدء عملية التعديل.

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

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