يوضّح هذا الدليل طريقة إتاحة التحديثات داخل التطبيق في تطبيقك باستخدام رموز برمجية أصلية (C أو C++ ). وهناك أدلة منفصلة للحالات التي يستخدم فيها التنفيذ لغة برمجة Kotlin أو لغة برمجة Java والحالات التي يستخدم فيها تطبيقك Unity.
نظرة عامة على حزمة تطوير البرامج (SDK) الأصلية
إنّ حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play Core هي جزء من مجموعة حزمة تطوير البرامج
(SDK) الأساسية من Play. تتضمّن حزمة SDK الأصلية ملف العنوان app_update.h
، والذي يلتف
AppUpdateManager
من مكتبة التحديثات داخل التطبيق في Java Play. يتيح ملف العنوان هذا لتطبيقك استدعاء واجهة برمجة التطبيقات
للحصول على التحديثات داخل التطبيق مباشرةً من الرمز الأصلي.
إعداد بيئة التطوير
تنزيل 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.
عليك القيام بأي مما يلي:
- ثبِّت الإصدار 4.0 من استوديو Android أو إصدارًا أحدث. استخدِم واجهة مستخدم "مدير حزمة تطوير البرامج" (SDK) لتثبيت الإصدار 10.0 من "منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android" (مستوى واجهة برمجة التطبيقات 29).
- ثبِّت أدوات سطر الأوامر لحزمة تطوير البرامج (SDK) لنظام التشغيل Android
واستخدِم
sdkmanager
لتثبيت الإصدار 10.0 من "منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android" (المستوى 29 من واجهة برمجة التطبيقات).
يمكنك إعداد "استوديو Android" لتطوير البرامج الأصلية باستخدام مدير SDK لتثبيت أحدث إصدار من CMake وAndroid Native Development Kit (NDK). لمزيد من المعلومات حول إنشاء مشاريع أصلية أو استيرادها، راجع بدء استخدام NDK.
يمكنك تنزيل ملف ZIP واستخراجه بجانب مشروعك.
رابط التنزيل حجم الملف المجموع الاختباري لخوارزمية SHA-256 36 ميبيبايت 782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e عدِّل ملف
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.3.0' implementation 'com.google.android.play:review:2.0.1' // 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.3.0") implementation("com.google.android.play:review:2.0.1") // 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 ...)
جمع البيانات
قد تجمع حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play الأساسية البيانات ذات الصلة بالإصدار للسماح لشركة Google بتحسين المنتج، بما في ذلك:
- اسم حزمة التطبيق
- إصدار حزمة التطبيق
- إصدار Play Core Native SDK
سيتم جمع هذه البيانات عند تحميل حزمة تطبيقك
على Play Console. لإيقاف عملية جمع البيانات هذه، عليك إزالة
عملية استيراد $playcoreDir/playcore-native-metadata.jar
في ملف Build.gradle.
يُرجى العلم أنّ عملية جمع البيانات هذه المتعلّقة باستخدام حزمة تطوير البرامج (SDK) الأصلية لـ Play Core واستخدام Google للبيانات التي يتم جمعها هي عملية منفصلة ومستقلة عن مجموعة Google من العناصر التابعة للمكتبات والمعلَن عنها في أداة Gradle عند تحميل حزمة التطبيق إلى Play Console.
بعد دمج حزمة تطوير البرامج (SDK) الأصلية لمكتبة Play الأساسية في مشروعك، يمكنك تضمين السطر التالي في الملفات التي تحتوي على طلبات البيانات من واجهة برمجة التطبيقات:
#include "play/app_update.h"
إعداد واجهة برمجة تطبيقات التحديث داخل التطبيق
عندما تستخدم واجهة برمجة التطبيقات In-app Update API، عليك إعدادها أولاً من خلال استدعاء الوظيفة
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
خيارات عملية التحديث داخل التطبيق، بما في ذلك ما إذا كان يجب أن يكون التحديث
مرنًا أو فوريًا.
في ما يلي مثال على إنشاء كائن 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()
لطلب مسار التحديث بشكل غير متزامن، مع ضبط نشاط Android jobject
للمَعلمة النهائية.
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
يشير إلى أنّ نوع التحديث مسموح به قبل بدء عملية التحديث.
الخطوات التالية
اختبر تحديثات تطبيقك داخل التطبيق للتحقق من سير عملية الدمج بشكل صحيح.