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

Unity oyunları, öğe teslimini entegre ederken Adreslenebilirler veya AssetBundles kullanarak öğe paketlerine erişebilir. Adreslenebilir reklamlar, Unity 2019.4 veya sonraki sürümlerle oluşturulan oyunlar için daha yeni ve önerilen öğe teslim çözümüdür. AssetBundles, Unity 2017.4 ve 2018.4 sürümlerindeki öğe paketlerini destekler.

Unity Adreslenebilirleri

Unity 2019.4 veya sonraki sürümler ile oluşturulan oyunlarda, Android'de öğe teslimi için Adreslenebilirler kullanılmalıdır. Unity, Adreslenebilirler'i kullanarak Android öğe paketlerini işlemek için bir Play Asset Delivery (PAD) API'si sağlar. Adreslenebilirler'i kullanma hakkında bilgi için aşağıdakilere bakın:

AssetBundle dosyalarını kullanma

Unity 2017.4 ve 2018.4 ile oluşturulan oyunlar, Android'de öğe teslimi 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 (örneğin, Android için tasarlanmıştır) ve öğe paketleriyle birlikte kullanılabilir. En yaygın şekilde, bir AssetBundle dosyası, AssetBundle ile aynı adı kullanan tek bir öğe paketi halinde paketlenir. Öğe paketi oluşturma konusunda daha fazla esneklik istiyorsanız API'yi kullanarak öğe paketini yapılandırın.

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

Ön koşullar

  1. Unity için Google paketlerinden Play Asset Delivery Unity Eklentisi'nin son sürümünü indirin.

  2. Unity'de AssetBundles oluşturma.

Kullanıcı arayüzünü kullanarak AssetBundles yapılandırma

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

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

  2. Her paket için İletim Modu'nu Yükleme Süresi, Hızlı Takip veya İsteğe Bağlı olarak değiştirin. Tüm hataları veya bağımlılıkları giderin ve 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 teslimini, otomatik derleme sisteminin parçası olarak çalıştırılabilen düzenleyici komut dosyaları aracılığıyla yapılandırabilirsiniz.

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 bir 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);
}

Ayrıca, BuildPlayerOptions ve AssetPackConfig adlı öğe paketlerine sahip 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ı Codelab'de Play Asset Delivery'yi kullanma bölümüne bakın.

Play Asset Delivery Unity API ile entegrasyon

Play Asset Delivery Unity API, öğe paketlerini isteme, indirme işlemlerini yönetme ve öğelere erişme işlevlerini sunar. Önce 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ılmış öğe paketleri'ni seçin.

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

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

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

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

AssetBundles alma

Play Asset Delivery kitaplığını içe aktarın ve bir AssetBundle almak için RetrieveAssetBundleAsync() yöntemini çağırın.

using Google.Play.AssetDelivery;

// Loads the AssetBundle from disk, downloading the asset pack containing it if necessary.
PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);

Yükleme zamanında teslim

install-time olarak yapılandırılan öğe paketleri, uygulama başlatıldığında hemen kullanılabilir. AssetBundle'dan bir sahne yüklemek için aşağıdakileri kullanabilirsiniz:

AssetBundle assetBundle = bundleRequest.AssetBundle;

// You may choose to load scenes from the AssetBundle. For example:
string[] scenePaths = assetBundle.GetAllScenePaths();
SceneManager.LoadScene(scenePaths[path-index]);

Hızlı takip ve isteğe bağlı teslimat

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

Durumu denetle

Her öğe paketi, uygulamanın dahili depolamasında ayrı bir klasörde depolanır. Bir öğe paketinin daha önce indirilip indirilmediğini belirlemek için isDownloaded() yöntemini kullanın.

İndirme işlemini izleme

İsteğin durumunu izlemek için PlayAssetBundleRequest 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 will only signify the download is complete. It will still need to be loaded.
float progress = bundleRequest.DownloadProgress;

// Returns true if:
//   * it had either completed the download, installing, and loading of the AssetBundle,
//   * OR if it has encountered an error.
bool done = bundleRequest.IsDone;

// Returns status of retrieval request.
AssetDeliveryStatus status = bundleRequest.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.Loading:
        // Asset pack is being loaded.
    case AssetDeliveryStatus.Loaded:
        // Asset pack has finished loading, assets can now be loaded.
        // For PlayAssetBundleRequest(), this indicates that the request is complete.
    case AssetDeliveryStatus.Failed:
        // Asset pack retrieval has failed.
    case AssetDeliveryStatus.WaitingForWifi:
        // Asset pack retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowCellularDataConfirmation dialog.
    default:
        break;
}

Büyük boyutlu indirmeler

150 MB'tan büyük öğe paketleri yalnızca kablosuz bağlantı üzerinden otomatik olarak indirilebilir. Kullanıcı kablosuz ağa bağlı değilse PlayAssetBundleRequest durumu AssetDeliveryStatus.WaitingForWifi olarak ayarlanır ve indirme işlemi duraklatılır. Bu durumda, cihazın kablosuz ağa bağlanmasını ve indirme işleminin devam etmesini bekleyin ya da kullanıcıdan paketi hücresel bağlantı üzerinden indirmesi için onay isteyin.

if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) {
    var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();
    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. In this case, we recommend
            // developers wait for Wi-Fi before attempting to download again.
            // You can get more info by calling GetError() on the operation.
        case ConfirmationDialogResult.Accepted:
            // User accepted the confirmation dialog - download will start
            // automatically (no action needed).
        case ConfirmationDialogResult.Declined:
            // User canceled or declined the dialog. Await Wi-Fi connection, or
            // re-prompt the user.
        default:
            break;
    }
}

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

AssetBundles belleğe yüklenmeden önce isteği iptal etmeniz gerekirse PlayAssetBundleRequest 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.
bundleRequest.AttemptCancel();

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

Öğe paketlerini eşzamansız olarak isteme

Çoğu durumda, öğe paketlerini eşzamansız olarak istemek ve ilerleme durumunu izlemek için aşağıdaki gibi Kriterler kullanmanız gerekir:

private IEnumerator LoadAssetBundleCoroutine(string assetBundleName) {

    PlayAssetBundleRequest bundleRequest =
        PlayAssetDelivery.RetrieveAssetBundleAsync(assetBundleName);

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

            // 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(() => bundleRequest.Status != AssetDeliveryStatus.WaitingForWifi);
        }

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

        yield return null;
    }

    if (bundleRequest.Error != AssetDeliveryErrorCode.NoError) {
        // There was an error retrieving the bundle. 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. Retrieve AssetBundle from request.AssetBundle.
    AssetBundle assetBundle = bundleRequest.AssetBundle;

Hataların ele alınması hakkında daha fazla bilgi için AssetDeliveryErrorCodes 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.

İndirme boyutunu kontrol edin

Google Play'e eşzamansız bir çağrı yaparak ve işlemin tamamlandığı zaman için bir geri çağırma yöntemi ayarlayarak AssetBundle'ın 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ı AssetBundles öğelerini kaldırabilirsiniz. Aşağıdaki eşzamansız çağrıyı yapın ve tamamlandığında bir 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ım

Yerel olarak ve Google Play'den öğe teslimini test edin.