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

Unity oyunları, öğe yayınlamayı entegre ederken Addressables veya AssetBundles'ı kullanarak öğe paketlerine erişebilir. Addressables, Unity 2019.4 veya sonraki sürümlerle oluşturulan oyunlar için daha yeni ve önerilen öğe yayınlama çözümüdür. AssetBundles ise Unity 2017.4 ve 2018.4'te öğe paketleri için destek sağlar.

Unity Adreslenebilirler

Unity 2019.4 veya sonraki sürümlerle oluşturulan oyunlar, Android'de öğe yayınlamak için Addressables'ı kullanmalıdır. Unity, Addressables'ı kullanarak Android öğe paketlerini işlemek için bir Play Asset Delivery (PAD) API'si sağlar. Adreslenebilirleri kullanma hakkında bilgi edinmek için aşağıdakileri inceleyin:

AssetBundle dosyalarını kullanma

Unity 2017.4 ve 2018.4 ile oluşturulan oyunlar, Android'de öğe yayınlamak için AssetBundle dosyalarını kullanabilir. Unity AssetBundle dosyaları, uygulama çalışırken Unity motoru tarafından yüklenebilecek serileştirilmiş öğeler içerir. Bu dosyalar platforma özeldir (ör. Android için derlenmiştir) ve öğe paketleriyle birlikte kullanılabilir. Genellikle bir AssetBundle dosyası tek bir öğe paketine paketlenir. Paket, AssetBundle ile aynı adı kullanır. Öğe paketi oluştururken daha fazla esneklik istiyorsanız öğe paketini API'yi kullanarak yapılandırın.

Çalışma zamanında, bir öğe paketinde paketlenmiş AssetBundle'i almak için Unity için Play Asset Delivery sınıfını kullanın.

Ön koşullar

  1. Geliştirme ortamınızı ayarlayın:

OpenUPM-CLI

OpenUPM CLI yüklüyse OpenUPM kayıt defterini şu komutla yükleyebilirsiniz:

openupm add com.google.play.assetdelivery

OpenUPM

  1. Düzenle > Proje Ayarları > Paket Yöneticisi Unity menü seçeneğini belirleyerek paket yöneticisi ayarlarını açın.

  2. OpenUPM'yi Paket Yöneticisi penceresine kapsamlı bir kayıt defteri olarak ekleyin:

    Name: package.openupm.com
    URL: https://package.openupm.com
    Scopes: com.google.external-dependency-manager
      com.google.play.common
      com.google.play.core
      com.google.play.assetdelivery
      com.google.android.appbundle
    
  3. Unity menü seçeneği Pencere > Paket Yöneticisi'ni seçerek paket yöneticisi menüsünü açın.

  4. Yönetici kapsamı açılır menüsünden Kayıt Dairelerim'i seçin.

  5. Paket listesinden Unity için Google Play Integrity eklentisi paketini seçin ve Yükle'ye basın.

GitHub'dan içe aktarma

  1. GitHub'dan en son .unitypackage sürümünü indirin.

  2. Öğeler > Paket içe aktar > Özel Paket Unity menü seçeneğini belirleyip tüm öğeleri içe aktararak .unitypackage dosyasını içe aktarın.

  1. Unity'de AssetBundles oluşturma.

AssetBundles'ı kullanıcı arayüzünü kullanarak yapılandırma

  1. Öğe paketindeki her AssetBundle'ı yapılandırın:

    1. Google > Android App Bundle > Asset Delivery Settings'i (Öğe Yayınlama Ayarları) seçin.
    2. Doğrudan AssetBundle dosyaları içeren klasörleri seçmek için Klasör Ekle'yi tıklayın.

  2. Her paket için Yayın Modunu Yükleme Zamanı, Hızlı Takip veya İstediğiniz Zaman olarak değiştirin. Hataları veya bağımlılıkları giderip pencereyi kapatın.

  3. Uygulama paketini oluşturmak için Google > Android App Bundle'ı Oluştur'u seçin.

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

API'yi kullanarak öğe paketlerini yapılandırma

Öğe yayınlamayı, otomatik bir derleme sistemi kapsamında çalıştırılabilen düzenleyici komut dosyaları aracılığıyla yapılandırabilirsiniz.

Bir Android App Bundle derlemesine hangi öğelerin dahil edileceğini ve öğelerin yayınlama modunu tanımlamak için AssetPackConfig sınıfını kullanın. Bu öğe paketlerinin AssetBundle içermesi gerekmez.

public void ConfigureAssetPacks {
   // Creates an AssetPackConfig with a single asset pack, named
   // examplePackName, containing all the files in path/to/exampleFolder.
   var assetPackConfig = new AssetPackConfig();
   assetPackConfig.AddAssetsFolder("examplePackName",
                                   "path/to/exampleFolder",
                                   AssetPackDeliveryMode.OnDemand);

   // Configures the build system to use the newly created assetPackConfig when
   // calling Google > Build and Run or Google > Build Android App Bundle.
   AssetPackConfigSerializer.SaveConfig(assetPackConfig);

   // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script.
   BuildBundle(new buildPlayerOptions(), assetPackConfig);
}

BuildPlayerOptions ve AssetPackConfig sağlandığında, öğe paketleri içeren bir Android App Bundle oluşturmak için Bundletool sınıfındaki statik BuildBundle yöntemini de kullanabilirsiniz.

Rehberli eğitim için Unity oyunlarında Play Asset Delivery'i kullanma Codelab'ine bakın.

Play Asset Delivery Unity API ile entegrasyon

Play Asset Delivery Unity API, öğe paketleri isteme, indirmeleri yönetme ve öğelere erişme işlevlerini sağlar. Öncelikle projenize Unity eklentisini eklediğinizden emin olun.

API'de kullandığınız işlevler, öğe paketlerini nasıl oluşturduğunuza bağlıdır.

Eklenti kullanıcı arayüzünü kullanarak öğe paketleri oluşturduysanız Eklenti tarafından yapılandırılan öğe paketleri'ni seçin.

API'yi (veya eklenti kullanıcı arayüzünü) kullanarak öğe paketleri oluşturduysanız API tarafından yapılandırılan öğe paketleri'ni seçin.

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

API için öğe paketi akış diyagramı

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

Öğe paketi alma

Play Öğe Yayınlama kitaplığını aktarın ve paketin en son sürümü diskte mevcut değilse öğe paketini indirmek için RetrieveAssetPackAsync() yöntemini çağırın.

using Google.Play.AssetDelivery;

// After download, the assets and/or AssetBundles contained in the asset pack
// are not loaded into memory.
PlayAssetPackRequest request = PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

Yükleme sırasında yayınlama

install-time olarak yapılandırılan bir öğe paketi, uygulama başlatıldıktan hemen sonra kullanılabilir ancak öğelerini belleğe yüklemeniz gerekir. Öğeleri belleğe yükleme başlıklı makaleyi inceleyin.

Hızlı takip ve isteğe bağlı yayınlama

Bu bölümler fast-follow ve on-demand öğe paketleri için geçerlidir.

Durumu denetle

Her öğe paketi, uygulamanın dahili depolama alanında ayrı bir klasörde depolanır. Bir öğe paketinin indirilip indirilmediğini ve kullanılabilir olup olmadığını veya bir hata olup olmadığını belirlemek için isDone() yöntemini kullanın.

İndirme işlemini izleme

İsteğin durumunu izlemek için PlayAssetPackRequest nesnesini sorgulayın:

// Download progress of request, between 0.0f and 1.0f. The value will always be
// 1.0 for assets delivered as install-time.
// NOTE: A value of 1.0 does not mean that the request has completed, only that
// the DOWNLOADING stage is finished.
float progress = request.DownloadProgress;

// Returns the status of the retrieval request.
// If the request completed successfully, this value should be AssetDeliveryStatus.Available.
// If an error occurred, this value should be AssetDeliveryStatus.Failed.

AssetDelivery status = request.Status;
switch(status) {
    case AssetDeliveryStatus.Pending:
        // Asset pack download is pending - N/A for install-time assets.
    case AssetDeliveryStatus.Retrieving:
        // Asset pack is being downloaded and transferred to app storage.
        // N/A for install-time assets.
    case AssetDeliveryStatus.Available:
        // Asset pack is downloaded on disk but NOT loaded into memory.
        // For PlayAssetPackRequest(), this indicates that the request is complete.
    case AssetDeliveryStatus.Failed:
        // Asset pack retrieval failed.
    case AssetDeliveryStatus.WaitingForWifi:
        // Asset pack retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowConfirmationDialog dialog.
    case AssetDeliveryStatus.RequiresUserConfirmation:
        // Asset pack retrieval paused until the user accepts the
        // PlayAssetDelivery.ShowConfirmationDialog dialog.
    default:
        break;
}

// Returns true if status is AssetDeliveryStatus.Available or AssetDeliveryStatus.Failed.
bool done = request.IsDone;

// If AssetDeliveryStatus.Failed, find more info about the error.
AssetDeliveryErrorCode error = request.Error;

Büyük boyutlu indirmeler

200 MB'tan büyük öğe paketleri yalnızca cihaz kablosuz ağa bağlıysa otomatik olarak indirilebilir. Kullanıcı kablosuz ağda değilse PlayAssetPackRequest durumu AssetDeliveryStatus.WaitingForWifi olarak ayarlanır ve indirme duraklatılır. Bu durumda, cihazın kablosuz ağa bağlanmasını bekleyip indirme işlemini devam ettirin veya kullanıcıdan paketi hücresel bağlantı üzerinden indirmek için onay isteyin.

Kullanıcı onayı gerekli

Bir paketin durumu AssetDeliveryStatus.RequiresUserConfirmation ise kullanıcı PlayAssetDelivery.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 PlayAssetDelivery.ShowConfirmationDialog() çağrısının uygulamanın güncellenmesine neden olacağını unutmayın. Güncelleme yapıldıktan sonra öğeleri tekrar isteyin.

if(request.Status == AssetDeliveryStatus.RequiresUserConfirmation
   || request.Status == AssetDeliveryStatus.WaitingForWifi) {
    var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog();
    yield return userConfirmationOperation;

    switch(userConfirmationOperation.GetResult()) {
        case ConfirmationDialogResult.Unknown:
            // userConfirmationOperation finished with an error. Something went
            // wrong when displaying the prompt to the user, and they weren't
            // able to interact with the dialog.
        case ConfirmationDialogResult.Accepted:
            // User accepted the confirmation dialog--an update will start.
        case ConfirmationDialogResult.Declined:
            // User canceled or declined the dialog. It can be shown again.
        default:
            break;
    }
}

İsteği iptal etme (yalnızca isteğe bağlı)

Öğe paketleri indirilmeden önce isteği iptal etmeniz gerekiyorsa PlayAssetPackRequest nesnesinde AttemptCancel() yöntemini çağırın:

// Will only attempt if the status is Pending, Retrieving, or Available; otherwise
// it will be a no-op.
request.AttemptCancel();

// Check to see if the request was successful by checking if the error code is Canceled.
if(request.Error == AssetDeliveryErrorCode.Canceled) {
    // Request was successfully canceled.
}

Öğeleri belleğe yükleme

İstek tamamlandıktan sonra öğeleri belleğe yüklemek için aşağıdaki işlevlerden birini kullanın:

Öğe paketlerini asenkron olarak isteme

Çoğu durumda, öğe paketlerini asynkron olarak istemek ve ilerlemeyi izlemek için koşullu yan rutinleri kullanmanız gerekir. Aşağıda bu durum gösterilmektedir:

private IEnumerator LoadAssetPackCoroutine(string assetPackName) {

    PlayAssetPackRequest request =
        PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

    while (!request.IsDone) {
        if(request.Status == AssetDeliveryStatus.WaitingForWifi) {
            var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog();

            // Wait for confirmation dialog action.
            yield return userConfirmationOperation;

            if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) ||
               (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) {
                // The user did not accept the confirmation. Handle as needed.
            }

            // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on.
            yield return new WaitUntil(() => request.Status != AssetDeliveryStatus.WaitingForWifi);
        }

        // Use request.DownloadProgress to track download progress.
        // Use request.Status to track the status of request.

        yield return null;
    }

    if (request.Error != AssetDeliveryErrorCode.NoError) {
        // There was an error retrieving the pack. For error codes NetworkError
        // and InsufficientStorage, you may prompt the user to check their
        // connection settings or check their storage space, respectively, then
        // try again.
        yield return null;
    }

    // Request was successful. Load the asset pack into memory.
    AssetBundleCreateRequest assetBundleCreateRequest = request.LoadAssetBundleAsync(path/to/exampleBundle);
    yield return assetBundleCreateRequest;
    AssetBundle assetBundle = assetBundleCreateRequest.assetBundle;

Hataları ele alma hakkında daha fazla bilgi için hata kodları listesine bakın.

Diğer Play Core API yöntemleri

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

Birden fazla öğe paketi alma

Birden fazla öğe paketini aynı anda almak için aşağıdaki işlevi kullanın:

// assetPackNames is an array of strings corresponding to asset packs.
PlayAssetPackBatchRequest batchRequest = PlayAssetDelivery.RetrieveAssetPackBatchAsync(<IListstring> assetPackNames);

Durumların Dictionary'ünü inceleyerek her isteğin durumunu izleyin:

// Dictionary of AssetPackStates, with the asset pack name as the key.
Dictionary<string, PlayAssetPackRequest> requests = batchRequest.Requests;

// Returns true if all requests are complete.
bool requestComplete = batchRequest.IsDone;

İndirme boyutunu kontrol etme

Google Play'e asynkron çağrı yaparak ve işlem tamamlandığında geri çağırma yöntemi ayarlayarak bir öğe paketinin boyutunu kontrol edin:

public IEnumerator GetDownloadSize() {
   PlayAsyncOperation<long> getSizeOperation =
   PlayAssetDelivery.GetDownloadSize(assetPackName);

   yield return getSizeOperation;
   if(operation.Error != AssetDeliveryErrorCode.NoError) {
       // Error while retrieving download size.
    } else {
        // Download size is given in bytes.
        long downloadSize = operation.GetResult();
    }
}

AssetBundles'ı kaldırma

Şu anda belleğe yüklenmemiş olan hızlı takip ve isteğe bağlı öğe paketlerini kaldırabilirsiniz. Aşağıdaki ayarsız çağrıyı yapın ve tamamlandığında geri çağırma yöntemi ayarlayın:

PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName);

removeOperation.Completed += (operation) =>
            {
                if(operation.Error != AssetDeliveryErrorCode.NoError) {
                    // Error while attempting to remove AssetBundles.
                } else {
                    // Files were deleted OR files did not exist to begin with.
                }
            };

Sonraki adımlar

Yerel olarak ve Google Play'den öğe yayınlamayı test edin.