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

C ve C++ kodunuzdan uygulamanızın öğe paketlerine erişmek için bu kılavuzda yer alan adımları uygulayın.

Örnek entegrasyon kodunu GitHub'da bulabilirsiniz.

Yerel reklamlar için içerik oluşturma

Play Asset Delivery'i projenizin Android uygulama paketine eklemek için aşağıdaki adımları uygulayın. Bu adımları gerçekleştirmek için Android Studio'yu kullanmanız gerekmez.

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

2. Projenizin üst düzey dizininde öğe 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 yayınlama 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ına, projenizdeki her öğ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ına, projenizdeki tüm öğe paketlerini aşağıdaki gibi ekleyin:

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

6. Öğe paketi dizininde aşağıdaki alt dizin 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ı şu şekilde görünmelidir:

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

8. Android App Bundle'ı Gradle ile derleyin. 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ı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 dosyasını 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ığıyla entegrasyon

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

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

Play Core Yerel SDK'sı, öğe paketleri istemek, indirmeleri yönetmek ve öğelere erişmek için C başlık 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:

   • 4.0 veya sonraki bir sürüm olan Android Studio'yu 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 Android SDK Platform 10.0 sürümünü (API düzeyi 29) yüklemek için sdkmanager kullanın.

2. En son CMake ve Android Native Development Kit'i (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'yi kullanmaya başlama başlıklı makaleyi inceleyin.

3. ZIP dosyasını indirip projenizle birlikte ayıklayın.

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

4. Uygulamanızın build.gradle dosyasını aşağıdaki 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.2.2'
           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.2.2")
       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ğıdaki 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. Buna aşağıdakiler dahildir:

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

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

Play Core Native SDK'yı 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'de 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ılmış öğe paketleri, uygulama başlatıldıktan hemen sonra kullanılabilir. Bu modda sunulan öğelere erişmek için NDK AAssetManager API'yi 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ınlama

Aşağıdaki bölümlerde, API'nin nasıl başlatılacağı, öğe paketleri indirilmeden önce öğe paketleri hakkında 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

Diğer işlevleri çağırmadan önce öğe paketi API'sini ilk kullanıma hazırlamak 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 öğesinin onPause() ve onResume() bölümünde 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 belirtmesi gerekir. İndirme boyutu ve paketin indirilip indirilmediği hakkında asenkron bir istek başlatmak için AssetPackManager_requestInfo() işlevini kullanın. Ardından, indirme durumunu kontrol etmek için AssetPackManager_getDownloadState() işlevini kullanın (örneğin, bu işlevi oyun döngüsünüzde her karede bir ç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, opak türünü AssetPackDownloadState çıkış 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 bir öğe paketi güncellemesinin tamamlanmasını istemek için 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ünü AssetPackDownloadState döndürür. Bu türün nasıl kullanılacağı hakkında bilgi edinmek için İndirme bilgileri alma başlıklı makaleyi inceleyin.

Büyük boyutlu indirmeler

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

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Kullanıcı onayı gerekli

Bir paketin durumu REQUIRES_USER_CONFIRMATION ise kullanıcı AssetPackManager_showConfirmationDialog() ile 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üncelleme yapıldıktan 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 AssetPackManager_getAssetPackLocation() kullanarak AssetPackLocation alın. Depolama yöntemini belirlemek için söz konusu konumda AssetPackLocation_getStorageMethod() seçeneğini kullanın:

• ASSET_PACK_STORAGE_APK: Öğe paketi APK olarak yüklenir. Bu öğelere erişmek için Yükleme sırasında yayınlama bölümüne bakın.
• ASSET_PACK_STORAGE_FILES: Öğeleri içeren dizinin dosya yolunu almak için AssetPackLocation_getAssetsPath() değerini kullanın. Öğeler indirilmediyse null değerini kullanın. Bu dosya yolundaki 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 bir öğe paketi isteğini iptal etmek için AssetPackManager_cancelDownload() simgesini kullanın. Bu isteğin mümkün olan en iyi şekilde işlendiğini unutmayın.

Kaldırma talebinde bulun

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

Sonraki adımlar

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