Asset Delivery integrieren (Unity)

Bei der Asset Delivery-Integration können Unity-Spiele mithilfe von Addressables oder AssetBundles auf Asset-Packs zugreifen. Addressables sind die neuere und empfohlene Lösung für die Asset-Auslieferung für Spiele, die mit Unity 2019.4 oder höher erstellt wurden. AssetBundles unterstützen Asset-Packs in Unity 2017.4 und 2018.4.

Unity Addressables

Für Spiele, die mit Unity 2019.4 oder höher erstellt wurden, sollten Addressables für die Asset-Bereitstellung unter Android verwendet werden. Unity bietet eine Play Asset Delivery API (PAD) für die Verarbeitung von Android-Asset-Packs mithilfe von Addressables. Weitere Informationen zur Verwendung von Addressables finden Sie hier:

• Addressables für Android-Paket
• PAD-Leitfaden für Unity
• Referenzdokumentation zur PAD API für Unity

AssetBundle-Dateien verwenden

Spiele, die mit Unity 2017.4 und 2018.4 erstellt wurden, können AssetBundle-Dateien für die Asset-Auslieferung unter Android verwenden. Unity-AssetBundle-Dateien enthalten serialisierte Assets, die von der Unity-Engine geladen werden können, während die App ausgeführt wird. Diese Dateien sind plattformspezifisch (z. B. für Android erstellt) und können in Kombination mit Asset-Packs verwendet werden. In den meisten Fällen wird eine AssetBundle-Datei in einem einzelnen Asset-Paket verpackt, das denselben Namen wie das AssetBundle hat. Wenn Sie beim Erstellen eines Asset-Pakets mehr Flexibilität wünschen, können Sie es mithilfe der API konfigurieren.

Verwenden Sie zur Laufzeit die Klasse Play Asset Delivery for Unity, um ein AssetBundle abzurufen, das in einem Asset-Pack verpackt ist.

Voraussetzungen

1. Entwicklungsumgebung einrichten:

openupm add com.google.play.assetdelivery

1. AssetBundles in Unity erstellen

AssetBundles über die Benutzeroberfläche konfigurieren

1. Konfigurieren Sie jedes AssetBundle in einem Asset-Paket:

   1. Wählen Sie Google > Android App-Bundle > Asset Delivery Settings (Asset Delivery Settings) aus.
   2. Wenn Sie Ordner auswählen möchten, die direkt AssetBundle-Dateien enthalten, klicken Sie auf Ordner hinzufügen.

   

2. Ändern Sie für jedes Paket den Auslieferungsmodus in Installationszeit, Schnelles Folgen oder On-Demand. Beheben Sie alle Fehler oder Abhängigkeiten und schließen Sie das Fenster.

   

3. Wählen Sie Google > Android App-Bundle erstellen aus, um das App-Bundle zu erstellen.

4. Optional: Konfigurieren Sie Ihr App-Bundle so, dass verschiedene Texturkomprimierungsformate unterstützt werden.

Asset-Pakete mit der API konfigurieren

Sie können die Asset-Übermittlung über Editor-Scripts konfigurieren, die als Teil eines automatisierten Build-Systems ausgeführt werden können.

Verwenden Sie die Klasse AssetPackConfig, um zu definieren, welche Assets in ein Android App Bundle-Build aufgenommen werden sollen, und den Bereitstellungsmodus der Assets. Diese Asset-Pakete müssen kein AssetBundle enthalten.

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

Sie können auch die statische Methode BuildBundle in der Klasse Bundletool verwenden, um ein Android-App-Bundle mit Asset-Packs zu generieren, sofern BuildPlayerOptions und AssetPackConfig angegeben sind.

Eine Anleitung finden Sie im Codelab zur Verwendung von Play Asset Delivery in Unity-Spielen.

Play Asset Delivery Unity API einbinden

Die Play Asset Delivery Unity API bietet Funktionen zum Anfordern von Asset-Packs, zum Verwalten von Downloads und zum Zugriff auf die Assets. Fügen Sie zuerst das Unity-Plug-in zu Ihrem Projekt hinzu.

Welche Funktionen Sie in der API verwenden, hängt davon ab, wie Sie die Asset-Pakete erstellt haben.

Wenn Sie Asset-Pakete über die Plug-in-Benutzeroberfläche erstellt haben, wählen Sie Über Plug-in konfigurierte Asset-Pakete aus.

Wenn du Asset-Packs mit der API (oder der Plugin-Benutzeroberfläche) erstellt hast, wähle API-konfigurierte Asset-Packs aus.

Sie implementieren die API entsprechend dem Bereitstellungstyp des Asset-Pakets, auf das Sie zugreifen möchten. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

Abbildung 1. Flussdiagramm für den Zugriff auf Asset-Pakete

AssetBundles abrufen

Importieren Sie die Play Asset Delivery-Bibliothek und rufen Sie die Methode RetrieveAssetBundleAsync() auf, um ein AssetBundle abzurufen.

using Google.Play.AssetDelivery;

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

Bereitstellung bei der Installation

Asset-Pakete, die als install-time konfiguriert sind, sind beim Starten der App sofort verfügbar. So laden Sie eine Szene aus dem AssetBundle:

AssetBundle assetBundle = bundleRequest.AssetBundle;

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

Fast-Follow- und On-Demand-Auslieferung

Diese Abschnitte gelten für fast-follow- und on-demand-Asset-Packs.

Status prüfen

Jedes Asset-Paket wird in einem separaten Ordner im internen Speicher der App gespeichert. Mit der Methode isDownloaded() kannst du feststellen, ob ein Asset-Paket bereits heruntergeladen wurde.

Download beobachten

Rufen Sie das PlayAssetBundleRequest-Objekt ab, um den Status der Anfrage zu verfolgen:

// 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.ShowConfirmationDialog dialog.
    case AssetDeliveryStatus.RequiresUserConfirmation:
        // Asset pack retrieval paused until the user accepts the
        // PlayAssetDelivery.ShowConfirmationDialog dialog.
    default:
        break;
}

Große Downloads

Asset-Packs, die größer als 200 MB sind, können automatisch heruntergeladen werden, aber nur über WLAN. Wenn der Nutzer kein WLAN nutzt, wird der PlayAssetBundleRequest-Status auf AssetDeliveryStatus.WaitingForWifi gesetzt und der Download wird pausiert. Warten Sie in diesem Fall, bis das Gerät eine WLAN-Verbindung herstellt, und fahren Sie dann mit dem Download fort oder bitten Sie den Nutzer um Erlaubnis, das Paket über eine Mobilfunkverbindung herunterzuladen.

Erforderliche Nutzerbestätigung

Wenn ein Paket den Status AssetDeliveryStatus.RequiresUserConfirmation hat, wird der Download erst fortgesetzt, wenn der Nutzer das Dialogfeld mit PlayAssetDelivery.ShowConfirmationDialog() akzeptiert. Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird. Hinweis: Wenn Sie in diesem Fall PlayAssetDelivery.ShowConfirmationDialog() aufrufen, wird die App aktualisiert. Bitten Sie nach dem Update noch einmal um die Assets.

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

Anfrage abbrechen (nur On-Demand)

Wenn Sie die Anfrage abbrechen möchten, bevor die AssetBundles in den Arbeitsspeicher geladen werden, rufen Sie die Methode AttemptCancel() auf dem Objekt PlayAssetBundleRequest auf:

// 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.
}

Asset-Packs asynchron anfordern

In den meisten Fällen sollten Sie Coroutinen verwenden, um Asset-Pakete asynchron anzufordern und den Fortschritt zu überwachen, wie im Folgenden dargestellt:

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;

Weitere Informationen zur Fehlerbehandlung finden Sie in der Liste der AssetDeliveryErrorCodes.

Weitere Play Core API-Methoden

Im Folgenden finden Sie einige weitere API-Methoden, die Sie in Ihrer App verwenden können.

Downloadgröße prüfen

Sie können die Größe eines AssetBundles prüfen, indem Sie einen asynchronen Aufruf an Google Play senden und eine Rückrufmethode für den Abschluss des Vorgangs festlegen:

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 entfernen

Sie können Fast-Follow- und On-Demand-AssetBundles entfernen, die derzeit nicht in den Arbeitsspeicher geladen sind. Führen Sie den folgenden asynchronen Aufruf aus und legen Sie eine Rückrufmethode für den Abschluss fest:

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.
                }
            };

Nächste Schritte

Testen Sie die Asset-Übermittlung lokal und über Google Play.