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

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

Örnek entegrasyon kodu GitHub'da mevcuttur.

Yerel için geliştirme

Play Asset Delivery'yi projenizin Android App Bundle'ına entegre etmek 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, varlık paketi için bir dizin oluşturun. Bu dizin adı, öğe paketi adı olarak kullanılır. Öğe paketi adları harfle başlamalıdır ve yalnızca harf, rakam 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 teslimat 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 uygulama build.gradle dosyasında, projenizdeki her bir öğe paketinin adını aşağıdaki gibi ekleyin:

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

5. Projenin settings.gradle dosyasında, aşağıdaki örnekte 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 alt dizinler de oluşturabilirsiniz. Uygulamanızın dizin yapısı artık aşağıdaki gibi görünmelidir:

   • 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 şunları içerir:

   • asset-pack-name/manifest/AndroidManifest.xml: Öğe paketinin tanımlayıcısını ve yayın modunu yapılandırır.
   • asset-pack-name/assets/your-asset-directories: Öğe paketi kapsamında sunulan tüm öğeleri içeren dizin

   Gradle, her bir öğe paketi için manifest oluşturur ve assets/ dizini sizin için çıkarır.

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ın türüne göre uygularsınız. Bu adımlar aşağıdaki akış şemasında gösterilmektedir.

1.şekil Öğe paketlerine erişim akış diyagramı

Play Core Native SDK, öğe paketleri istemek, indirmeleri yönetmek ve öğelere erişmek için C üstbilgi dosyasını play/asset_pack.h sağlar.

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

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

   • Android Studio 4.0 veya sonraki bir sürümünü yükleyin. Android SDK Platform 10.0 sürümünü (API düzeyi 29) 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 sdkmanager komutunu kullanarak Android SDK Platform 10.0 sürümünü (API düzeyi 29) yükleyin.

2. En yeni CMake ve Android Native Development Kit'i (NDK) yüklemek için SDK Manager'ı 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 başlıklı makaleyi inceleyin.

3. ZIP dosyasını indirip projenizin yanına çıkarın.

   İndirme Bağlantısı	Boyut	SHA-256 Sağlaması
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

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

   Groovy

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

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ştirmesine olanak tanımak için sürümle ilgili veriler toplayabilir. Örneğin:

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

Bu veriler, Play Console'a uygulama paketinizi yüklediğinizde toplanır. Bu veri toplama sürecini 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 Native SDK kullanımınızla ilgili bu veri toplama işleminin ve Google'ın toplanan verileri kullanımının, uygulama paketinizi Play Console'a yüklediğinizde Gradle'da beyan edilen kitaplık bağımlılıklarının Google tarafından toplanmasından ayrı ve bağımsız olduğunu unutmayın.

Yükleme sırasında yayınlama

install-time olarak yapılandırılan öğe paketleri, uygulama başlatıldığında hemen 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ı yayın

Aşağıdaki bölümlerde API'nin nasıl başlatılacağı, indirmeden önce öğe paketleri hakkında nasıl bilgi alınacağı, indirmeyi 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 öğe paketi API'sini başlatmak için her zaman AssetPackManager_init() işlevini çağırın. Öğe paketi hata kodları olup olmadığını kontrol edin.

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

Ayrıca ANativeActivityCallbacks onPause() ve onResume() bölümlerinde aşağıdaki işlevleri çağırdığınızdan emin olun:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Öğe paketleri hakkında indirme bilgilerini alma

Uygulamalar, öğe paketini getirmeden önce indirme boyutunu belirtmelidir. İndirme boyutunu ve paketin indirilip indirilmediğini belirlemek için AssetPackManager_requestInfo() işlevini kullanarak eşzamansız bir istek başlatın. Ardından, indirme durumunu yoklamak için AssetPackManager_getDownloadState() işlevini kullanın (örneğin, oyun döngünüzde bu işlevi kare başına bir kez çağırın). İstek 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, opak türü AssetPackDownloadState çıktı işaretçisi olarak 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 aşağıdaki işlemleri tamamlamak için öğe paketi güncellemesi istemek üzere AssetPackManager_requestDownload() simgesini 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ü AssetPackDownloadState döndürür. Bu türü kullanma hakkında bilgi edinmek için İndirme bilgilerini alma başlıklı makaleyi inceleyin.

Büyük boyutlu indirmeler

İndirme boyutu 200 MB'tan büyükse ve kullanıcı kablosuz bağlantıya bağlı değilse indirme işlemi, kullanıcının mobil veri bağlantısı kullanarak indirme işlemine devam etme izni açıkça verilene kadar başlamaz. Benzer şekilde, indirme işlemi büyükse ve kullanıcı kablosuz bağlantısını kaybederse indirme işlemi duraklatılır ve mobil veri bağlantısı kullanılarak devam etmek için açık rıza gerekir. Duraklatılmış bir paketin durumu WAITING_FOR_WIFI olur. Kullanıcıdan izin istemek için kullanıcı arayüzü akışını tetiklemek üzere aşağıdakileri kullanın:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Kullanıcı onayı gerekiyor

Bir paketin durumu REQUIRES_USER_CONFIRMATION ise kullanıcı, REQUIRES_USER_CONFIRMATION ile gösterilen iletişim kutusunu kabul edene kadar indirme işlemi devam etmez.AssetPackManager_showConfirmationDialog() Bu durum, uygulama Play tarafından tanınmadığında ortaya çıkabilir. Bu durumda AssetPackManager_showConfirmationDialog() işlevinin çağrılması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 saklanır. Belirtilen öğe paketi için AssetPackManager_getAssetPackLocation() kullanarak AssetPackLocation alın. Depolama yöntemini belirlemek için ilgili konumda AssetPackLocation_getStorageMethod() simgesini kullanın:

• ASSET_PACK_STORAGE_APK: Varlık paketi, APK olarak yüklenir. Bu öğelere erişmek için Yükleme zamanında teslim bölümüne bakın.
• ASSET_PACK_STORAGE_FILES: Öğeleri içeren dizinin dosya yolunu almak için AssetPackLocation_getAssetsPath() işlevini kullanın. Öğeler indirilmemişse null değerini döndürür. İndirilen dosyaları bu dosya yolunda 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

Uygulamanızda kullanmak isteyebileceğiniz bazı ek API yöntemlerini aşağıda bulabilirsiniz.

İsteği iptal et

Etkin bir öğe paketi isteğini iptal etmek için AssetPackManager_cancelDownload() simgesini kullanın. Bu isteğin, mümkün olan en iyi şekilde gerçekleştirilen bir işlem olduğunu unutmayın.

Kaldırma talebinde bulun

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

Sonraki adımlar

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