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

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

Örnek entegrasyon kodu GitHub'da mevcuttur.

Doğal reklamlar için oluşturma

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 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ı bir harfle başlamalı ve yalnızca harf, rakam ve alt çizgi içermelidir.

  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ü 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 öğ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ında, projenizdeki tüm öğe paketlerini aşağıda gösterildiği gibi 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 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 oluşturur ve assets/ dizinini 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ığı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österilmiştir.

Yerel kod için öğe paketi akış diyagramı

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

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

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

İndir Play Core Native SDK

İndirmeden önce aşağıdaki hüküm ve koşulları kabul etmeniz gerekir.

Hükümler ve Koşullar

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 indirin

play-core-native-sdk-1.16.0.zip

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

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

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

  3. ZIP dosyasını indirin ve projenizle birlikte ayıklayın.

    İndirme Bağlantısı Boyut SHA-256 denetim toplamı
    54,8 MiB 008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

  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.1.0'
        implementation 'com.google.android.play:asset-delivery:2.3.0'
        implementation 'com.google.android.play:integrity:1.6.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.6.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 Native SDK, Google'ın ürünü iyileştirmesine olanak tanımak için sürümle ilgili verileri toplayabilir. Bu veriler arasında şunlar yer alır:

  • 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ürecinin kapsamı dışında kalmayı seçmek için build.gradle dosyasındaki $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'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'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 ilk kullanıma hazırlanacağı, indirmeden ö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 lansmanı

Başka bir işlevi ç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 sınıfının onPause() ve onResume() yöntemlerinde aşağıdaki işlevleri çağırdığınızdan emin olun:

Öğe paketleriyle ilgili indirme bilgilerini alma

Uygulamaların, öğe paketini getirmeden önce indirme boyutunu açıklaması gerekir. İndirme boyutunu ve paketin indirilmeye başlanıp başlanmadığını öğrenmek üzere asenkron istek başlatmak için AssetPackManager_requestInfo() işlevini kullanın. Ardından, indirme durumunu sorgulamak 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). 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 türü AssetPackDownloadState 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() yöntemini 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ü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 boyutu 200 MB'tan büyükse ve kullanıcı kablosuz ağa bağlı değilse indirme işlemi, kullanıcı mobil veri bağlantısı kullanarak indirme işlemine devam etmek için açıkça izin verene kadar başlamaz. Benzer şekilde, indirme işlemi büyükse ve kullanıcının kablosuz bağlantısı kesilirse indirme işlemi duraklatılır ve mobil veri bağlantısı kullanılarak devam etmek için açık izin gerekir. Duraklatılmış bir paketin durumu WAITING_FOR_WIFI olur. Kullanıcıdan izin istemek üzere kullanıcı arayüzü akışını tetiklemek için aşağıdakileri kullanın:

Kullanıcı onayı gereklidir

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. Uygulama, Google Play tarafından tanınmıyorsa bu durum ortaya çıkabilir. Bu durumda AssetPackManager_showConfirmationDialog() yöntemini çağırmak uygulamanın güncellenmesine neden olur. 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 öğe paketine erişebilirsiniz. Her öğe paketi, uygulamanın dahili depolama alanında ayrı bir dizinde depolanır. Belirtilen öğe paketi için AssetPackLocation almak üzere AssetPackManager_getAssetPackLocation() yöntemini 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 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() yöntemini kullanın. Öğeler indirilmemişse 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() kullanın. Bu isteğin, en iyi çaba ilkesine göre 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.