یکپارچه سازی تحویل دارایی (بومی)

از مراحل این راهنما برای دسترسی به بسته‌های دارایی برنامه خود از کد C و C++ خود استفاده کنید.

نمونه کد یکپارچه سازی در GitHub موجود است.

ساخت برای بومی

از مراحل زیر برای ایجاد Play Asset Delivery در بسته نرم افزار Android پروژه خود استفاده کنید. برای انجام این مراحل نیازی به استفاده از اندروید استودیو نیست.

1. نسخه پلاگین Android Gradle را در فایل build.gradle پروژه خود به 4.0.0 یا بالاتر به روز کنید.

2. در دایرکتوری سطح بالای پروژه خود، یک دایرکتوری برای بسته دارایی ایجاد کنید. این نام دایرکتوری به عنوان نام بسته دارایی استفاده می شود. نام بسته دارایی باید با یک حرف شروع شود و فقط شامل حروف، اعداد و زیرخط باشد.

3. در پوشه asset pack یک فایل 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 ]"
       }
   }

4. در فایل build.gradle برنامه پروژه، نام هر بسته دارایی در پروژه خود را مانند شکل زیر اضافه کنید:

   // In the app build.gradle file:
   android {
       ...
       assetPacks = [":asset-pack-name", ":asset-pack2-name"]
   }

5. در فایل settings.gradle پروژه، تمام بسته‌های دارایی را مانند شکل زیر در پروژه خود قرار دهید:

   // In the settings.gradle file:
   include ':app'
   include ':asset-pack-name'
   include ':asset-pack2-name'

6. در دایرکتوری بسته دارایی، زیر شاخه زیر را ایجاد کنید: src/main/assets .

7. دارایی ها را در دایرکتوری src/main/assets قرار دهید. در اینجا نیز می توانید زیر شاخه ها را ایجاد کنید. ساختار دایرکتوری برنامه شما اکنون باید به شکل زیر باشد:

   • build.gradle
   • settings.gradle
   • app/
   • asset-pack-name /build.gradle
   • asset-pack-name /src/main/assets/ your-asset-directories

8. بسته نرم افزاری اندروید را با Gradle بسازید . در بسته نرم افزاری تولید شده، دایرکتوری سطح ریشه اکنون شامل موارد زیر است:

   • asset-pack-name /manifest/AndroidManifest.xml : شناسه بسته دارایی و حالت تحویل را پیکربندی می کند
   • asset-pack-name /assets/ your-asset-directories : فهرستی که شامل تمام دارایی های تحویل شده به عنوان بخشی از بسته دارایی است.

   Gradle مانیفست را برای هر بسته دارایی تولید می کند و فهرست assets/ را برای شما خروجی می دهد.

9. (اختیاری) بسته نرم افزاری خود را برای پشتیبانی از فرمت های مختلف فشرده سازی بافت پیکربندی کنید.

با کتابخانه تحویل دارایی Play یکپارچه شوید

شما این API را با توجه به نوع تحویل بسته دارایی که می خواهید به آن دسترسی داشته باشید پیاده سازی می کنید. این مراحل در فلوچارت زیر نشان داده شده است.

شکل 1. نمودار جریان برای دسترسی به بسته های دارایی

Play Core Native SDK فایل هدر C play/asset_pack.h برای درخواست بسته‌های دارایی، مدیریت دانلودها و دسترسی به دارایی‌ها فراهم می‌کند.

محیط توسعه خود را برای Play Core Native SDK تنظیم کنید

1. یکی از موارد زیر را انجام دهید:

   • Android Studio نسخه 4.0 یا بالاتر را نصب کنید. از رابط کاربری SDK Manager برای نصب Android SDK Platform نسخه 10.0 (سطح API 29) استفاده کنید.
   • ابزارهای خط فرمان Android SDK را نصب کنید و از sdkmanager برای نصب Android SDK Platform نسخه 10.0 (سطح API 29) استفاده کنید.

2. Android Studio را برای توسعه بومی با استفاده از مدیر SDK برای نصب جدیدترین کیت توسعه CMake و Android Native (NDK) آماده کنید. برای اطلاعات بیشتر در مورد ایجاد یا وارد کردن پروژه های بومی، به شروع با NDK مراجعه کنید.

3. فایل فشرده را دانلود کرده و در کنار پروژه خود استخراج کنید.

   لینک دانلود	اندازه	SHA-256 Checksum
   play-core-native-sdk-1.14.0.zip	36 مگابایت	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

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.1'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   کاتلین

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

جمع آوری داده ها

Play Core Native SDK ممکن است داده‌های مربوط به نسخه را جمع‌آوری کند تا به Google اجازه دهد محصول را بهبود بخشد، از جمله:

• نام بسته برنامه
• نسخه بسته برنامه
• نسخه Core Native SDK را بازی کنید

وقتی بسته برنامه خود را در Play Console آپلود می کنید، این داده ها جمع آوری می شود. برای انصراف از این فرآیند جمع‌آوری داده، وارد کردن $playcoreDir/playcore-native-metadata.jar در فایل build.gradle حذف کنید.

توجه داشته باشید، این مجموعه داده‌های مربوط به استفاده شما از Play Core Native SDK و استفاده Google از داده‌های جمع‌آوری‌شده مجزا و مستقل از مجموعه وابستگی‌های کتابخانه Google است که در Gradle هنگام آپلود بسته برنامه خود در Play Console اعلام شده است.

تحویل در زمان نصب

بسته‌های دارایی که به‌عنوان install-time پیکربندی شده‌اند، بلافاصله با راه‌اندازی برنامه در دسترس هستند. از NDK AAssetManager API برای دسترسی به دارایی های ارائه شده در این حالت استفاده کنید:

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

تحویل سریع و درخواستی

بخش‌های زیر نحوه تنظیم اولیه API، نحوه دریافت اطلاعات در مورد بسته‌های دارایی قبل از دانلود، نحوه تماس با API برای شروع دانلود و نحوه دسترسی به بسته‌های دانلود شده را نشان می‌دهد. این بخش‌ها برای بسته‌های دارایی fast-follow و on-demand اعمال می‌شود.

راه اندازی برنامه

همیشه AssetPackManager_init() را فراخوانی کنید تا API بسته دارایی را قبل از فراخوانی هر تابع دیگری مقداردهی کنید. کدهای خطای بسته دارایی را بررسی کنید.

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

همچنین حتماً توابع زیر را در onPause() و onResume() ANativeActivityCallbacks فراخوانی کنید:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

دریافت اطلاعات دانلود در مورد بسته های دارایی

برنامه‌ها باید قبل از واکشی بسته دارایی، اندازه دانلود را فاش کنند. از تابع 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 است. برای فعال کردن جریان UI برای درخواست رضایت از کاربر، از موارد زیر استفاده کنید:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

تایید کاربر مورد نیاز است

اگر بسته ای دارای وضعیت REQUIRES_USER_CONFIRMATION باشد، دانلود ادامه نمی یابد تا زمانی که کاربر گفتگوی نشان داده شده با AssetPackManager_showConfirmationDialog() نپذیرد. اگر برنامه توسط 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 Core API

در زیر چند روش API اضافی وجود دارد که ممکن است بخواهید در برنامه خود استفاده کنید.

لغو درخواست

از AssetPackManager_cancelDownload() برای لغو درخواست بسته دارایی فعال استفاده کنید. توجه داشته باشید که این درخواست بهترین عملیات است.

درخواست حذف

از AssetPackManager_requestRemoval() برای برنامه ریزی حذف بسته دارایی استفاده کنید.

مراحل بعدی

تحویل دارایی Play را به صورت محلی و از Google Play آزمایش کنید .