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:

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-CLI

Wenn Sie die OpenUPM-Befehlszeile installiert haben, können Sie die OpenUPM-Registry mit dem folgenden Befehl installieren:

openupm add com.google.play.assetdelivery

OpenUPM

  1. Öffnen Sie die Einstellungen des Paketmanagers, indem Sie die Unity-Menüoption Bearbeiten > Projekteinstellungen > Paketmanager auswählen.

  2. Fügen Sie OpenUPM dem Fenster „Package Manager“ als eingeschränkte Registry hinzu:

    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. Öffnen Sie das Menü des Paketmanagers, indem Sie die Unity-Menüoption Fenster > Paketmanager auswählen.

  4. Wählen Sie im Drop-down-Menü „Verwaltungskonto“ die Option Meine Registrierungen aus.

  5. Wählen Sie in der Paketliste das Paket Google Play Integrity-Plug-in für Unity aus und klicken Sie auf Installieren.

Aus GitHub importieren

  1. Laden Sie die neueste .unitypackage-Version von GitHub herunter.

  2. Importiere die .unitypackage-Datei, indem du die Unity-Menüoption Assets > Import package > Custom Package auswählst und alle Elemente importierst.

  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.

Die API ist unabhängig vom Bereitstellungstyp des Asset-Pakets, auf das du zugreifen möchtest, ähnlich. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

Asset-Paket-Ablaufdiagramm für die API

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

Asset-Pack abrufen

Importiere die Play Asset Delivery-Bibliothek und rufe die Methode RetrieveAssetPackAsync() auf, um ein Asset-Paket herunterzuladen, falls die neueste Version des Pakets nicht bereits auf dem Laufwerk verfügbar ist.

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

Bereitstellung bei der Installation

Ein als install-time konfiguriertes Asset-Paket ist beim Starten der App sofort verfügbar, Sie müssen die Assets jedoch in den Arbeitsspeicher laden. Weitere Informationen finden Sie unter Assets in den Arbeitsspeicher laden.

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 isDone() kannst du feststellen, ob ein Asset-Paket bereits heruntergeladen und verfügbar ist oder ob ein Fehler aufgetreten ist.

Download beobachten

Rufe das PlayAssetPackRequest-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 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;

Große Downloads

Asset-Pakete, die größer als 200 MB sind, können automatisch heruntergeladen werden, aber nur, wenn das Gerät mit einem WLAN verbunden ist. Wenn der Nutzer kein WLAN nutzt, wird der PlayAssetPackRequest-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 du die Anfrage abbrechen möchtest, bevor die Asset-Packs heruntergeladen werden, rufe die Methode AttemptCancel() auf das PlayAssetPackRequest-Objekt auf:

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

Assets in den Arbeitsspeicher laden

Sobald die Anfrage abgeschlossen ist, kannst du mit einer der folgenden Funktionen Assets in den Arbeitsspeicher laden:

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

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

Weitere Play Core API-Methoden

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

Mehrere Asset-Packs abrufen

Wenn du mehrere Asset-Pakete gleichzeitig abrufen möchtest, verwende die folgende Funktion:

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

Sie können den Status jeder Anfrage prüfen, indem Sie die Dictionary-Status prüfen:

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

Downloadgröße prüfen

Sie können die Größe eines Asset-Pakets prüfen, indem Sie Google Play asynchron aufrufen 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

Du kannst Fast-Follow- und On-Demand-Asset-Packs entfernen, die derzeit nicht im 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.