تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

دمج عرض المواد (الأصلي)

اتّبِع الخطوات الواردة في هذا الدليل للوصول إلى حزم مواد العرض في تطبيقك من خلال رمزَي C وC++‎.

يتوفّر نموذج رمز الدمج على GitHub.

إنشاء إعلانات مدمجة مع المحتوى

اتّبِع الخطوات التالية لدمج ميزة "عرض المواد في Play" في مجموعة حزمات تطبيق Android الخاصة بمشروعك. ليس عليك استخدام Android Studio لتنفيذ هذه الخطوات.

يُرجى تعديل إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android في ملف build.gradle الخاص بمشروعك إلى الإصدار 4.0.0 أو إصدار أحدث.
في دليل المستوى الأعلى لمشروعك، أنشئ دليلاً لحزمة مواد العرض. ويُستخدَم اسم الدليل هذا كاسم لحزمة مواد العرض. يجب أن تبدأ أسماء حزم مواد العرض بحرف، ويمكن أن تحتوي على أحرف وأرقام وشرطات سفلية فقط.

في دليل حزمة مواد العرض، أنشئ ملف build.gradle وأضِف الرمز التالي. تأكَّد من تحديد اسم حزمة مواد العرض ونوع واحد فقط من أنواع التسليم:

// In the asset pack’s build.gradle file:
plugins {
    id 'com.android.asset-pack'
}

assetPack {
    packName = "asset-pack-name" // Directory name for the asset pack
    dynamicDelivery {
        deliveryType = "[ install-time | fast-follow | on-demand ]"
    }
}

في ملف build.gradle الخاص بتطبيق المشروع، أضِف اسم كل حزمة مواد عرض في مشروعك كما هو موضّح أدناه:
```
// In the app build.gradle file:
android {
    ...
    assetPacks = [":asset-pack-name", ":asset-pack2-name"]
}
```
في ملف settings.gradle الخاص بالمشروع، أدرِج جميع حزم مواد العرض في مشروعك كما هو موضّح أدناه:
```
// In the settings.gradle file:
include ':app'
include ':asset-pack-name'
include ':asset-pack2-name'
```
في دليل حزمة مواد العرض، أنشئ الدليل الفرعي التالي: src/main/assets.
ضَع مواد العرض في الدليل src/main/assets. يمكنك إنشاء أدلة فرعية هنا أيضًا. يجب أن تبدو بنية الدليل لتطبيقك الآن على النحو التالي:
- build.gradle
- settings.gradle
- app/
- asset-pack-name/build.gradle
- asset-pack-name/src/main/assets/your-asset-directories
إنشاء مجموعة حزمات تطبيق Android باستخدام Gradle في حزمة التطبيق التي تم إنشاؤها، يتضمّن الدليل على مستوى الجذر الآن ما يلي:
- asset-pack-name/manifest/AndroidManifest.xml: يضبط معرّف حزمة مواد العرض ووضع العرض
- ‫asset-pack-name/assets/your-asset-directories: المجلد الذي يحتوي على جميع مواد العرض التي يتم تسليمها كجزء من حزمة مواد العرض
ينشئ Gradle ملف البيان لكل حزمة مواد عرض ويُخرج الدليل assets/ لك.
(اختياري) يمكنك ضبط حِزمة تطبيقك لتتوافق مع تنسيقات ضغط الزخرفة المختلفة.

التكامل مع مكتبة "عرض المواد في Play"

يمكنك تنفيذ واجهة برمجة التطبيقات هذه وفقًا لنوع عرض حزمة مواد العرض التي تريد الوصول إليها. تظهر هذه الخطوات في المخطط الانسيابي التالي.

مخطّط بياني لتدفق حزمة مواد العرض للرموز البرمجية الأصلية

الشكل 1: مخطّط انسيابي للوصول إلى حزم مواد العرض

توفّر حزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية" ملف العنوان C‏ play/asset_pack.h لطلب حِزم مواد العرض وإدارة عمليات التنزيل والوصول إلى مواد العرض.

إعداد بيئة التطوير لحزمة تطوير البرامج (SDK) الأصلية في "مكتبة 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.

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

تنزيل Play Core Native SDK

play-core-native-sdk-1.16.0.zip

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

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

رابط التنزيل	الحجم	المجموع الاختباري لخوارزمية SHA-256
	‫54.8 ميغابايت	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

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

جمع البيانات

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

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

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

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

العرض في وقت التثبيت

تتوفّر حزم مواد العرض التي تم ضبطها على install-time فور تشغيل التطبيق. استخدِم واجهة برمجة التطبيقات NDK AAssetManager للوصول إلى مواد العرض التي يتم عرضها في هذا الوضع:

#include <android/asset_manager.h>
#include <android_native_app_glue.h>
...
AAssetManager* assetManager = app->activity->assetManager;
AAsset* asset = AAssetManager_open(assetManager, "asset-name", AASSET_MODE_BUFFER);
size_t assetLength = AAsset_getLength(asset);
char* buffer = (char*) malloc(assetLength + 1);
AAsset_read(asset, buffer, assetLength);

المتابعة السريعة والتسليم عند الطلب

توضّح الأقسام التالية كيفية إعداد واجهة برمجة التطبيقات، وكيفية الحصول على معلومات حول حزم مواد العرض قبل تنزيلها، وكيفية استدعاء واجهة برمجة التطبيقات لبدء عملية التنزيل، وكيفية الوصول إلى الحزم التي تم تنزيلها. تنطبق هذه الأقسام على حزم مواد العرض من النوع fast-follow وon-demand.

إطلاق التطبيق

يجب دائمًا استدعاء الدالة AssetPackManager_init() لإعداد واجهة برمجة التطبيقات الخاصة بحزمة مواد العرض قبل استدعاء أي دالة أخرى. تحقَّق من أي رموز خطأ في حزمة مواد العرض.

#include "play/asset_pack.h"
...
AssetPackErrorCode AssetPackManager_init(JavaVM* jvm, jobject android_context);

تأكَّد أيضًا من استدعاء الدوال التالية في onPause() وonResume() من ANativeActivityCallbacks:

الحصول على معلومات تنزيل حِزم مواد العرض

يجب أن تفصح التطبيقات عن حجم التنزيل قبل جلب حزمة مواد العرض. استخدِم الدالة AssetPackManager_requestInfo() لبدء طلب غير متزامن لمعرفة حجم عملية التنزيل وما إذا كان يتم تنزيل الحزمة حاليًا. بعد ذلك، استخدِم AssetPackManager_getDownloadState() للاستعلام عن حالة التنزيل (على سبيل المثال، يمكنك استدعاء هذه الدالة مرة واحدة لكل لقطة في حلقة الألعاب). إذا تعذّر تنفيذ طلب، يُرجى الاطّلاع على رموز أخطاء حزمة مواد العرض.

AssetPackErrorCode AssetPackManager_requestInfo();      // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

تعرض الدالة AssetPackManager_getDownloadState() النوع غير الشفاف AssetPackDownloadState كمؤشر ناتج. استخدِم هذا المؤشر لاستدعاء الدوال التالية:

AssetPackDownloadState* state;
AssetPackErrorCode error_code = AssetPackManager_getDownloadState(asset-pack-name, &state);
AssetPackDownloadStatus status = AssetPackDownloadState_getStatus(state);
uint64_t downloadedBytes = AssetPackDownloadState_getBytesDownloaded(state);
uint64_t totalBytes = AssetPackDownloadState_getTotalBytesToDownload(state));
AssetPackDownloadState_destroy(state);

تثبيت

استخدِم AssetPackManager_requestDownload() لبدء تنزيل حزمة مواد عرض لأول مرة أو لطلب إكمال تحديث حزمة مواد عرض:

AssetPackErrorCode AssetPackManager_requestDownload();  // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

تعرض الدالة AssetPackManager_getDownloadState() النوع المبهم AssetPackDownloadState. للحصول على معلومات حول كيفية استخدام هذا النوع، يُرجى الاطّلاع على الحصول على معلومات التنزيل.

عمليات تنزيل كبيرة

إذا كان حجم الملف الذي يتم تنزيله أكبر من 200 ميغابايت ولم يكن المستخدم متصلاً بشبكة Wi-Fi، لن يبدأ التنزيل إلا بعد أن يمنح المستخدم موافقته الصريحة على المتابعة باستخدام اتصال بيانات الجوّال. وبالمثل، إذا كان حجم التنزيل كبيرًا وانقطع اتصال المستخدم بشبكة Wi-Fi، يتم إيقاف التنزيل مؤقتًا ويجب الحصول على موافقة صريحة للمتابعة باستخدام اتصال بيانات الجوّال. تكون حالة الحزمة المتوقفة مؤقتًا WAITING_FOR_WIFI. لتشغيل مسار واجهة المستخدم من أجل مطالبة المستخدم بالموافقة، استخدِم ما يلي:

تأكيد المستخدم مطلوب

إذا كانت الحزمة بالحالة REQUIRES_USER_CONFIRMATION، لن تتم عملية التنزيل إلى أن يقبل المستخدم مربّع الحوار الذي يظهر مع AssetPackManager_showConfirmationDialog(). يمكن أن تظهر هذه الحالة إذا لم يتعرّف Google Play على التطبيق. يُرجى العِلم أنّ استدعاء AssetPackManager_showConfirmationDialog() في هذه الحالة يؤدي إلى تحديث التطبيق. بعد التحديث، اطلب مواد العرض مرة أخرى.

الوصول إلى حِزم مواد العرض

يمكنك الوصول إلى حزمة مواد عرض باستخدام طلبات نظام الملفات بعد أن يصل طلب التنزيل إلى الحالة COMPLETED. يتم تخزين كل حزمة مواد عرض في دليل منفصل في وحدة التخزين الداخلية للتطبيق. استخدِم AssetPackManager_getAssetPackLocation() للحصول على AssetPackLocation لحزمة مواد العرض المحدّدة. استخدِم AssetPackLocation_getStorageMethod() في هذا الموقع الجغرافي لتحديد طريقة التخزين:

‫ASSET_PACK_STORAGE_APK: يتم تثبيت حزمة مواد العرض كملف APK. يُرجى الاطّلاع على التسليم عند التثبيت للوصول إلى مواد العرض هذه.
‫ASSET_PACK_STORAGE_FILES: استخدِم AssetPackLocation_getAssetsPath() للحصول على مسار ملف إلى الدليل الذي يحتوي على مواد العرض، أو قيمة فارغة إذا لم يتم تنزيل مواد العرض. لا تعدّل الملفات التي تم تنزيلها في مسار الملف هذا.

AssetPackLocation* location;

AssetPackErrorCode error_code = AssetPackManager_getAssetPackLocation(asset-pack-name, &location);

if (error_code == ASSET_PACK_NO_ERROR) {
    AssetPackStorageMethod storage_method = AssetPackLocation_getStorageMethod(location);
    const char* assets_path = AssetPackLocation_getAssetsPath(location);
    AssetPackLocation_destroy(location);
}

بعد العثور على مواد العرض، استخدِم دوال مثل fopen أو ifstream للوصول إلى الملفات.

طُرق أخرى في مكتبة Play الأساسية

في ما يلي بعض الطرق الإضافية لواجهة برمجة التطبيقات التي قد تحتاج إلى استخدامها في تطبيقك.

إلغاء الطلب

استخدِم AssetPackManager_cancelDownload() لإلغاء طلب حزمة مواد عرض نشط. يُرجى العِلم أنّ هذا الطلب هو عملية تعتمد على بذل أقصى جهد.

طلب إزالة

استخدِم AssetPackManager_requestRemoval() لجدولة إزالة حزمة مواد عرض.

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

اختبِر ميزة "عرض المواد في Play" محليًا ومن Google Play.

دمج عرض المواد (الأصلي) تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إنشاء إعلانات مدمجة مع المحتوى

التكامل مع مكتبة "عرض المواد في Play"

إعداد بيئة التطوير لحزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية"

تنزيل Play Core Native SDK

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

أنيق

Kotlin

جمع البيانات

العرض في وقت التثبيت

المتابعة السريعة والتسليم عند الطلب

إطلاق التطبيق

الحصول على معلومات تنزيل حِزم مواد العرض

تثبيت

عمليات تنزيل كبيرة

تأكيد المستخدم مطلوب

الوصول إلى حِزم مواد العرض

طُرق أخرى في مكتبة Play الأساسية

إلغاء الطلب

طلب إزالة

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

دمج عرض المواد (الأصلي)