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

از مراحل این راهنما برای دسترسی به بسته‌های دارایی برنامه خود از کد 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 تنظیم کنید

دانلود کنید Play Core Native SDK

قبل از دانلود، باید با شرایط و ضوابط زیر موافقت کنید.

شرایط و ضوابط

Last modified: September 24, 2020
  1. 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.
  2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
  3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
  4. 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.
  5. 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.14.0.zip

  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
    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 فراخوانی کنید:

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

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

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

اگر بسته ای دارای وضعیت 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 آزمایش کنید .