Öğe yayınını entegre etme (yerel)

C ve C++ kodunuzdan uygulamanızın öğe paketlerine erişmek için bu kılavuzdaki adımları kullanın.

Örnek entegrasyon koduna GitHub'da ulaşabilirsiniz.

Yerel için geliştirme

Play Asset Delivery'yi projenizin Android App Bundle'ına eklemek için aşağıdaki adımları uygulayın. Bu adımları uygulamak için Android Studio'yu kullanmanız gerekmez.

1. Projenizin build.gradle dosyasındaki Android Gradle eklentisinin sürümünü 4.0.0 veya sonraki bir sürüme güncelleyin.

2. Projenizin en üst düzey dizininde, öğe paketi için bir dizin oluşturun. Bu dizin adı, öğe paketi adı olarak kullanılıyor. Öğe paketi adları harfle başlamalıdır ve yalnızca harf, sayı ve alt çizgi içerebilir.

3. Öğe paketi dizininde, bir build.gradle dosyası oluşturun ve aşağıdaki kodu ekleyin. Öğe paketinin adını ve yalnızca bir gönderim türünü belirttiğinizden emin olun:

   // 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. Projenin uygulamasındaki build.gradle dosyasına, projenizdeki her öğe paketinin adını aşağıda gösterildiği gibi ekleyin:

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

5. Projenin settings.gradle dosyasına, aşağıda gösterildiği gibi projenizdeki tüm öğe paketlerini ekleyin:

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

6. Öğe paketi dizininde aşağıdaki alt dizini oluşturun: src/main/assets.

7. Öğeleri src/main/assets dizinine yerleştirin. Burada da alt dizinler oluşturabilirsiniz. Uygulamanızın dizin yapısı aşağıdaki gibi görünecektir:

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

8. Gradle ile Android App Bundle'ı oluşturun. Oluşturulan uygulama paketinde, kök düzeyindeki dizin artık aşağıdakileri içerir:

   • asset-pack-name/manifest/AndroidManifest.xml: Öğe paketinin tanımlayıcısını ve yayınlama modunu yapılandırır
   • asset-pack-name/assets/your-asset-directories: Öğe paketinin bir parçası olarak yayınlanan tüm öğeleri içeren dizin

   Gradle, her öğe paketi için manifest oluşturur ve assets/ dizinini sizin için oluşturur.

9. (İsteğe bağlı) Uygulama paketinizi farklı doku sıkıştırma biçimlerini destekleyecek şekilde yapılandırın.

Play Asset Delivery Kitaplığı ile entegrasyon

Bu API'yi, erişmek istediğiniz öğe paketinin yayınlanma türüne göre uygularsınız. Bu adımlar aşağıdaki akış şemasında gösterilmektedir.

Şekil 1. Öğe paketlerine erişim için akış şeması

Play Core Yerel SDK'sı öğe paketi istemek, indirmeleri yönetmek ve öğelere erişmek için play/asset_pack.h C başlık dosyasını sağlar.

Play Core Yerel SDK'sı için geliştirme ortamınızı ayarlama

1. Aşağıdakilerden birini yapın:

   • Android Studio'nun 4.0 veya sonraki bir sürümünü yükleyin. Android SDK Platformu 10.0 (API düzeyi 29) sürümünü yüklemek için SDK Yöneticisi kullanıcı arayüzünü kullanın.
   • Android SDK komut satırı araçlarını yükleyin ve Android SDK Platform 10.0 (API düzeyi 29) sürümünü yüklemek için sdkmanager aracını kullanın.

2. En yeni CMake ve Android Yerel Geliştirme Kiti'ni (NDK) yüklemek için SDK Yöneticisi'ni kullanarak Android Studio'yu yerel geliştirmeye hazırlayın. Yerel projeler oluşturma veya içe aktarma hakkında daha fazla bilgi için NDK'yı Kullanmaya Başlama bölümüne bakın.

3. ZIP dosyasını indirin ve projenizle birlikte çıkarın.

   Bağlantıyı İndir	Boyut	SHA-256 Sağlaması
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

4. Uygulamanızın build.gradle dosyasını aşağıda gösterildiği gibi güncelleyin:

   Eski

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

5. Uygulamanızın CMakeLists.txt dosyalarını aşağıda gösterildiği gibi güncelleyin:

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

Veri Toplama

Play Core Yerel SDK'sı, Google'ın ürünü iyileştirmesini sağlamak için sürümle ilgili verileri toplayabilir. Buna şunlar dahildir:

• Uygulamanın paket adı
• Uygulamanın paket sürümü
• Play Core Yerel SDK sürümü

Bu veriler, uygulama paketinizi Play Console'a yüklediğinizde toplanır. Bu veri toplama işlemini devre dışı bırakmak için build.gradle dosyasındaki $playcoreDir/playcore-native-metadata.jar içe aktarma işlemini kaldırın.

Play Core Yerel SDK'yı kullanımınızla ve Google'ın toplanan verileri kullanımıyla ilgili bu veri toplama işleminin, uygulama paketinizi Play Console'a yüklediğinizde Google'ın Gradle'da beyan ettiği kitaplık bağımlılıkları toplamasından ayrı ve bağımsız olduğunu unutmayın.

Yükleme zamanında teslimat

install-time olarak yapılandırılan öğe paketleri, uygulama kullanıma sunulduğu anda kullanılabilir. Bu modda sunulan öğelere erişmek için NDK AAssetManager API'sini kullanın:

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

Hızlı takip ve isteğe bağlı teslimat

Aşağıdaki bölümlerde API'yi nasıl başlatacağınız, öğe paketleriyle indirmeden önce nasıl bilgi alınacağı, indirme işlemini başlatmak için API'nin nasıl çağrılacağı ve indirilen paketlere nasıl erişileceği gösterilmektedir. Bu bölümler fast-follow ve on-demand öğe paketleri için geçerlidir.

Uygulama başlatma

Başka bir işlevi çağırmadan önce asset pack API'yi başlatmak için her zaman AssetPackManager_init() çağrısı yapın. Öğe paketi hata kodlarını kontrol edin.

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

Ayrıca ANativeActivityCallbacks öğesinin onPause() ve onResume() içinde aşağıdaki işlevleri çağırdığınızdan emin olun:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Öğe paketleriyle ilgili indirme bilgilerini alma

Uygulamaların, öğe paketini getirmeden önce indirme boyutunu bildirmesi gerekir. İndirme boyutu ve paketin zaten indirilip indirilmediği konusunda eşzamansız bir istek başlatmak için AssetPackManager_requestInfo() işlevini kullanın. Ardından, indirme durumunu yoklamak için AssetPackManager_getDownloadState() işlevini kullanın (örneğin, bu işlevi oyun döngünüzde her kare için bir kez çağırın). Bir istek başarısız olursa öğe paketi hata kodlarını kontrol edin.

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

AssetPackManager_getDownloadState() işlevi, çıkış işaretçisi olarak opak AssetPackDownloadState türünü döndürür. Aşağıdaki işlevleri çağırmak için bu işaretçiyi kullanın:

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

Yükle

Bir öğe paketini ilk kez indirmeye başlamak veya bir öğe paketinin güncellenmesini istemek için AssetPackManager_requestDownload()'ı kullanın:

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

AssetPackManager_getDownloadState() işlevi, opak türünü (AssetPackDownloadState) döndürür. Bu türün nasıl kullanılacağı hakkında bilgi için İndirme bilgilerini alma bölümüne bakın.

Büyük boyutlu indirme işlemleri

İndirme 200 MB'tan büyükse ve kullanıcı kablosuz ağa bağlı değilse indirme işlemi, kullanıcı bir mobil veri bağlantısı kullanarak indirme işlemine devam etmek için açıkça izin verene kadar başlamaz. Benzer şekilde, indirme boyutu büyükse ve kullanıcı kablosuz ağı kaybederse indirme işlemi duraklatılır ve mobil veri bağlantısı kullanarak devam etmek için açık bir izin gerekir. Duraklatılmış bir paket WAITING_FOR_WIFI durumunda. Kullanıcı arayüzü akışını tetikleyerek kullanıcıdan izin istemesini sağlamak için şunu kullanın:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Zorunlu kullanıcı onayı

Bir paket REQUIRES_USER_CONFIRMATION durumundaysa kullanıcı, AssetPackManager_showConfirmationDialog() ile birlikte gösterilen iletişim kutusunu kabul edene kadar indirme işlemi devam etmez. Bu durum, uygulama Play tarafından tanınmıyorsa ortaya çıkabilir. Bu durumda AssetPackManager_showConfirmationDialog() çağrısının, uygulamanın güncellenmesine neden olduğunu unutmayın. Güncellemeden sonra öğeleri tekrar isteyin.

Öğe paketlerine erişme

İndirme isteği COMPLETED durumuna ulaştıktan sonra dosya sistemi çağrılarını kullanarak bir öğe paketine erişebilirsiniz. Her öğe paketi, uygulamanın dahili depolama alanında ayrı bir dizinde depolanır. Belirtilen öğe paketi için bir AssetPackLocation almak isterseniz AssetPackManager_getAssetPackLocation() kullanın. Depolama yöntemini belirlemek için bu konumda AssetPackLocation_getStorageMethod() kullanın:

• ASSET_PACK_STORAGE_APK: Öğe paketi APK olarak yüklenir. Bu öğelere erişmek için Yükleme zamanında yayınlama bölümüne bakın.
• ASSET_PACK_STORAGE_FILES: Öğeleri içeren dizine giden dosya yolunu almak için AssetPackLocation_getAssetsPath(), öğeler indirilmediyse null değerini kullanın. Bu dosya yolunda indirilen dosyaları değiştirmeyin.

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

Öğeleri bulduktan sonra, dosyalara erişmek için fopen veya ifstream gibi işlevleri kullanın.

Diğer Play Core API yöntemleri

Aşağıda, uygulamanızda kullanmak isteyebileceğiniz bazı ek API yöntemleri verilmiştir.

İsteği iptal et

Etkin durumdaki bir öğe paketi isteğini iptal etmek için AssetPackManager_cancelDownload() kodunu kullanın. Bu isteğin en iyi çaba işlemi olduğunu unutmayın.

Kaldırma talebinde bulun

Bir öğe paketinin kaldırılmasını planlamak için AssetPackManager_requestRemoval() aracını kullanın.

Sonraki adımlar

Yerel olarak ve Google Play'den Play Asset Delivery'yi test edin.