Asset Delivery integrieren (Unity)

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

Ansprechbare Einheit

Bei Spielen, die mit Unity 2019.4 oder höher erstellt wurden, sollten Sie Addressables für die Asset Delivery unter Android verwenden. Unity bietet eine Play Asset Delivery (PAD) API für die Verarbeitung von Android-Asset-Packs mit Addressables. Informationen zur Verwendung von Addressables finden Sie hier:

AssetBundle-Dateien verwenden

Bei Spielen, die mit Unity 2017.4 und 2018.4 erstellt wurden, können AssetBundle-Dateien für die Asset-Bereitstellung unter Android verwendet werden. Unity-AssetBundle-Dateien enthalten serielle Assets, die von der Unity-Engine geladen werden können, während die Anwendung ausgeführt wird. Diese Dateien sind plattformspezifisch (z. B. für Android erstellt) und können in Kombination mit Asset-Packs verwendet werden. Meistens wird eine AssetBundle-Datei in einem einzelnen Asset-Pack verpackt, wobei das Paket denselben Namen wie das AssetBundle hat. Wenn Sie ein Asset-Pack flexibler erstellen möchten, können Sie es mithilfe der API konfigurieren.

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

Voraussetzungen

  1. Laden Sie die neueste Version des Play Asset Delivery Unity-Plug-ins aus den Google-Paketen für Unity herunter.

  2. Erstellen Sie AssetBundles in Unity.

AssetBundles über die UI konfigurieren

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

    1. Wählen Sie Google > Android App Bundle > Asset Delivery Settings aus.
    2. Um Ordner auszuwählen, die direkt AssetBundle-Dateien enthalten, klicken Sie auf Ordner hinzufügen.

  2. Ändern Sie für jedes Bundle den Übermittlungsmodus in Installationszeit, Fast Follow 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 es verschiedene Formate für die Texturkomprimierung unterstützt.

Asset-Packs mit der API konfigurieren

Sie können die Asset-Bereitstellung mithilfe von Editor-Skripts konfigurieren, die als Teil eines automatisierten Build-Systems ausgeführt werden können.

Mit der Klasse AssetPackConfig kannst du definieren, welche Assets in einen Android App Bundle-Build aufgenommen werden sollen, und den Übermittlungsmodus der Assets festlegen. Diese Asset-Packs 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);
}

Du kannst auch die statische Methode BuildBundle in der Klasse Bundletool verwenden, um ein Android App Bundle mit Asset-Packs unter Angabe von BuildPlayerOptions und AssetPackConfig zu generieren.

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

In die Play Asset Delivery Unity API einbinden

Die Play Asset Delivery Unity API bietet die Möglichkeit, Asset-Packs anzufordern, Downloads zu verwalten und auf Assets zuzugreifen. Fügen Sie Ihrem Projekt zuerst das Unity-Plug-in hinzu.

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

Wenn Sie Asset-Packs über die Plug-in-UI erstellt haben, wählen Sie Plug-in-konfigurierte Asset-Packs aus.

Wenn Sie Asset-Packs über die API (oder Plug-in-UI) erstellt haben, wählen Sie API-konfigurierte Asset-Packs aus.

Die API ist ähnlich, unabhängig vom Übermittlungstyp des Asset-Packs, auf das Sie zugreifen möchten. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

Asset-Pack-Flussdiagramm für die API

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

Asset-Pack abrufen

Importieren Sie die Play Asset Delivery-Bibliothek und rufen Sie die Methode RetrieveAssetPackAsync() auf, um ein Asset-Pack herunterzuladen, wenn die neueste Version des Pakets noch nicht auf der Festplatte 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);

Installationszeitpunkt-Lieferung

Ein als install-time konfiguriertes Asset-Pack ist sofort beim Start der App verfügbar, Sie müssen jedoch die Assets in den Arbeitsspeicher laden. Siehe Assets in den Speicher laden.

Schnelle Lieferung und On-Demand-Bereitstellung

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

Status prüfen

Jedes Asset-Pack wird in einem separaten Ordner im internen Speicher der App gespeichert. Verwenden Sie die Methode isDone(), um festzustellen, ob ein Asset-Pack bereits heruntergeladen wurde und verfügbar ist oder ob ein Fehler aufgetreten ist.

Download überwachen

Fragen Sie das Objekt PlayAssetPackRequest ab, um den Status der Anfrage zu beobachten:

// 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-Packs, die größer als 200 MB sind, können automatisch heruntergeladen werden, allerdings nur, wenn das Gerät mit einem WLAN verbunden ist. Wenn der Nutzer nicht mit einem WLAN verbunden ist, wird der Status PlayAssetPackRequest auf AssetDeliveryStatus.WaitingForWifi gesetzt und der Download angehalten. In diesem Fall musst du entweder warten, bis das Gerät mit dem WLAN verbunden ist, den Download fortsetzen oder den Nutzer um seine Zustimmung bitten, 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 mit PlayAssetDelivery.ShowConfirmationDialog() angezeigte Dialogfeld akzeptiert hat. Dieser Status kann auftreten, wenn die App von Play nicht erkannt wird. Wenn Sie PlayAssetDelivery.ShowConfirmationDialog() aufrufen, wird in diesem Fall die Anwendung aktualisiert. Fordern Sie die Assets nach der Aktualisierung noch einmal an.

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üssen, bevor die Asset-Packs heruntergeladen wurden, rufen Sie die Methode AttemptCancel() für 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, können Sie Assets mit einer der folgenden Funktionen in den Arbeitsspeicher laden:

Asset-Packs asynchron anfordern

In den meisten Fällen sollten Sie Coroutinen verwenden, um Asset-Packs asynchron anzufordern und den Fortschritt zu beobachten:

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 zum Beheben von Fehlern finden Sie in der Liste der Fehlercodes.

Andere Play Core API-Methoden

Nachfolgend finden Sie einige zusätzliche API-Methoden, die Sie in Ihrer App verwenden können.

Mehrere Asset-Packs abrufen

Verwende die folgende Funktion, um mehrere Asset-Packs gleichzeitig abzurufen:

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

Prüfen Sie die Status der einzelnen Anfragen, indem Sie die Dictionary der 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

Überprüfen Sie die Größe eines Asset-Packs, indem Sie einen asynchronen Aufruf an Google Play senden und eine Callback-Methode 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();
    }
}

Asset-Bundles entfernen

Sie können Fast-Follow- und On-Demand-Asset-Packs entfernen, die derzeit nicht in den Arbeitsspeicher geladen sind. Führen Sie den folgenden asynchronen Aufruf aus und legen Sie eine Callback-Methode 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

Teste die Asset-Bereitstellung lokal und über Google Play.