Öğ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 reklamlar için tasarım yapma

Play Asset Delivery'yi projenizin Android App Bundle'ına 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ındaki Android Gradle eklentisinin sürümünü 4.0.0 veya üzeri 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ır. Öğ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 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ğıda gösterildiği gibi ekleyin:

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

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

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

6. Öğe paketi dizininde şu 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. Android App Bundle'ı Gradle ile oluşturun. Oluşturulan uygulama paketinde, kök düzeyindeki dizin artık aşağıdakileri içermektedir:

   • 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 sizin için assets/ dizinini oluşturur.

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

Play Öğe Yayınlama Kitaplığı ile entegrasyon

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

Şekil 1. Öğe paketlerine erişime ilişkin akış diyagramı

Play Core Yerel SDK'sı öğe paketleri istemek, indirmeleri yönetmek ve öğelere erişmek için C üst bilgi 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 (API düzeyi 29) sürümünü yüklemek için SDK Manager kullanıcı arayüzünü kullanın.
   • Android SDK komut satırı araçlarını yükleyin ve sdkmanager kullanarak Android SDK Platform sürüm 10.0 (API düzeyi 29) yükleyin.

2. SDK Yöneticisi'ni kullanarak en yeni CMake ve Android Yerel Geliştirme Kiti'ni (NDK) yükleyerek Android Studio'yu yerel geliştirme için 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 çıkartın.

   İndirme Bağlantısı	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:

   Modern

       // 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.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // 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.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // 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. Bu veriler şunları içerir:

• Uygulamanın paket adı
• Uygulamanın paket sürümü
• Play Core Yerel SDK'sı 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 aktarmayı kaldırın.

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

Yükleme sırasında teslim

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'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ı teslimat

Aşağıdaki bölümlerde API'nin nasıl başlatılacağı, öğe paketleri indirilmeden önce nasıl öğrenileceği, 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 ilk kullanıma hazırlamak için her zaman AssetPackManager_init() yöntemini ç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() öğelerinde aşağıdaki işlevleri çağırdığınızdan emin olun:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Öğe paketleri hakkında indirme bilgilerini alın

Uygulamalar, öğe paketini getirmeden önce indirme boyutunu açıklamak zorundadır. İndirme boyutu ve paketin zaten indirilip indirilmediğiyle ilgili eşzamansız bir istek başlatmak için AssetPackManager_requestInfo() işlevini kullanın. Ardından, indirme durumunu yoklamak için AssetPackManager_getDownloadState() kullanın (örneğin, bu işlevi oyun döngünüzdeki 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 AssetPackDownloadState opak türünü döndürür. Bu işaretçiyi aşağıdaki işlevleri çağırmak için 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 tamamlanmasını istemek için AssetPackManager_requestDownload() aracını kullanın:

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

AssetPackManager_getDownloadState() işlevi, AssetPackDownloadState opak türünü 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 indirmeler

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

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Kullanıcı onayı gerekli

Paket, REQUIRES_USER_CONFIRMATION durumuna sahipse indirme işlemi, kullanıcı AssetPackManager_showConfirmationDialog() ile gösterilen iletişim kutusunu kabul edene kadar ilerlemez. Uygulama, Play tarafından tanınmazsa bu durum ortaya çıkabilir. Bu durumda AssetPackManager_showConfirmationDialog() çağrısının, uygulamanın güncellenmesine neden olduğunu unutmayın. Güncellemeden sonra öğeler için tekrar istekte bulunun.

Öğ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 paketiyle ilgili bir AssetPackLocation almak için AssetPackManager_getAssetPackLocation() kullanın. Depolama yöntemini belirlemek için ilgili konumda AssetPackLocation_getStorageMethod() kullanın:

• ASSET_PACK_STORAGE_APK: Öğe paketi bir 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 dizine bir dosya yolu almak için AssetPackLocation_getAssetsPath() kullanın veya öğeler indirilmediyse null değerini kullanın. İ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

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() aracını kullanın. Bu isteğin, yapılabilecek en iyi işlem olduğunu unutmayın.

Kaldırma talebinde bulun

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

Sonraki adımlar

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