Lorsque vous intégrez Asset Delivery, les jeux Unity peuvent accéder aux packs d'éléments à l'aide des Addressables ou AssetBundles. Les Addressables sont la solution de distribution d'éléments la plus récente et recommandée pour les jeux créés avec Unity 2019.4 ou version ultérieure. Les AssetBundles sont quant à eux compatibles avec les packs d'éléments dans Unity 2017.4 et 2018.4.
Addressables Unity
Les jeux créés avec Unity 2019.4 ou version ultérieure doivent utiliser des Addressables pour la distribution d'éléments sur Android. Unity fournit une API Play Asset Delivery (PAD) pour gérer les packs d'éléments Android à l'aide d'Addressables. Pour en savoir plus sur l'utilisation des Addressables, consultez les pages suivantes :
- Adressables pour le package Android
- Guide PAD pour Unity
- Documentation de référence sur l'API PAD pour Unity
Utiliser des fichiers AssetBundle
Les jeux créés avec Unity 2017.4 et 2018.4 peuvent utiliser des fichiers AssetBundle pour distribuer des éléments sur Android. Les fichiers AssetBundle d'Unity contiennent des éléments sérialisés qui peuvent être chargés par le moteur Unity pendant l'exécution de l'application. Ces fichiers sont spécifiques à une plate-forme (par exemple, conçus pour Android) et peuvent être utilisés avec des packs d'éléments. Le plus souvent, un fichier AssetBundle est présenté dans un pack d'éléments unique, portant le même nom que l'élément AssetBundle. Si vous souhaitez plus de flexibilité dans la création d'un pack d'éléments, configurez-le à l'aide de l'API.
Au moment de l'exécution, utilisez la classe Play Asset Delivery pour Unity pour récupérer un AssetBundle contenu dans un pack d'éléments.
Prérequis
- Configurez votre environnement de développement:
OpenUPM-CLI
Si la CLI OpenUPM est installée, vous pouvez installer le Registre OpenUPM à l'aide de la commande suivante:
openupm add com.google.play.assetdelivery
OpenUPM
Ouvrez les paramètres du gestionnaire de paquets en sélectionnant l'option de menu Unity Edit > Project Settings > Package Manager (Modifier > Paramètres du projet > Gestionnaire de paquets).
Ajoutez OpenUPM en tant que registre à portée à la fenêtre du Gestionnaire de paquets:
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.appbundleOuvrez le menu du gestionnaire de paquets en sélectionnant l'option de menu Unity Window > Package Manager (Fenêtre > Gestionnaire de paquets).
Dans le menu déroulant de l'étendue du gestionnaire, sélectionnez Mes registres.
Sélectionnez le package Google Play Integrity plug-in for Unity (Plug-in Google Play Integrity pour Unity) dans la liste des packages, puis appuyez sur Install (Installer).
Importer depuis GitHub
Téléchargez la dernière version de
.unitypackagesur GitHub.Importez le fichier
.unitypackageen sélectionnant l'option de menu Unity Assets > Import package > Custom Package (Éléments > Importer un package > Package personnalisé) et en important tous les éléments.
Configurer des AssetBundles à l'aide de l'UI
Configurez chaque AssetBundle dans un pack d'éléments :
- Sélectionnez Google > Android App Bundle > Paramètres Asset Delivery.
- Pour sélectionner des dossiers contenant directement des fichiers AssetBundle, cliquez sur Ajouter un dossier.
Pour chaque bundle, définissez le Mode d'envoi sur Heure d'installation, Distribution rapide ou À la demande. Résolvez les erreurs ou les dépendances, puis fermez la fenêtre.
Sélectionnez Google > Créer un fichier Android App Bundle pour créer l'app bundle.
(Facultatif) Configurez votre app bundle pour qu'il soit compatible avec différents formats de compression de texture.
Configurer des packs d'éléments à l'aide de l'API
Vous pouvez configurer Asset Delivery via des scripts d'éditeur pouvant être exécutés dans un système de compilation automatisé.
Utilisez la classe AssetPackConfig pour définir les éléments à inclure dans un build Android App Bundle, ainsi que le mode d'envoi des éléments. Ces packs d'éléments n'ont pas besoin de contenir d'élément AssetBundle.
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);
}
Vous pouvez également utiliser la méthode statique BuildBundle dans la classe Bundletool pour générer un Android App Bundle avec des packs d'éléments, pour BuildPlayerOptions et AssetPackConfig.
Pour suivre un tutoriel guidé, consultez l'atelier de programmation Utilisation de Play Asset Delivery dans les jeux Unity.
Intégrer à l'API Play Asset Delivery d'Unity
L'API Play Asset Delivery d'Unity permet de demander des packs d'éléments, de gérer les téléchargements et d'accéder aux éléments. Veillez d'abord à ajouter le plug-in Unity à votre projet.
Les fonctions que vous utilisez dans l'API dépendent de la manière dont vous avez créé les packs d'éléments.
Si vous avez créé des packs d'éléments à l'aide de l'interface utilisateur du plug-in, sélectionnez Packs d'éléments configurés par plug-in.
Si vous avez créé des packs d'éléments à l'aide de l'API (ou de l'interface utilisateur du plug-in), sélectionnez Packs d'éléments configurés par API.
Implémentez l'API en fonction du type de distribution du pack d'éléments auquel vous souhaitez accéder. Ces étapes sont présentées dans l'organigramme suivant.
Figure 1. Organigramme illustrant l'accès aux packs d'éléments
Récupérer les AssetBundles
Importez la bibliothèque Play Asset Delivery et appelez la méthode RetrieveAssetBundleAsync() pour récupérer un AssetBundle.
using Google.Play.AssetDelivery; // Loads the AssetBundle from disk, downloading the asset pack containing it if necessary. PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);
Distribution au moment de l'installation
Les packs d'éléments configurés en tant que install-time sont disponibles immédiatement au lancement de l'application. Vous pouvez utiliser la commande suivante pour charger une scène depuis l'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]);
Distribution rapide et à la demande
Ces sections s'appliquent aux packs d'éléments fast-follow et on-demand.
Vérifier l'état
Chaque pack d'éléments est stocké dans un dossier distinct de la mémoire de stockage interne de l'application.
Utilisez la méthode isDownloaded() pour déterminer si un pack d'éléments a déjà été téléchargé.
Surveiller le téléchargement
Interrogez l'objet PlayAssetBundleRequest pour surveiller l'état de la requête :
// 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;
}
Téléchargements volumineux
Les packs d'éléments de plus de 200 Mo peuvent être téléchargés automatiquement, mais uniquement via le Wi-Fi. Si l'utilisateur n'est pas connecté au Wi-Fi, l'état de la PlayAssetBundleRequest est défini sur AssetDeliveryStatus.WaitingForWifi et le téléchargement est temporairement suspendu. Dans ce cas, attendez que l'appareil se connecte au Wi-Fi, puis relancez le téléchargement ou demandez à l'utilisateur d'approuver le téléchargement du paquet via une connexion au réseau mobile.
Confirmation de l'utilisateur requise
Si un package affiche l'état AssetDeliveryStatus.RequiresUserConfirmation, le téléchargement ne se poursuit pas tant que l'utilisateur n'a pas accepté la boîte de dialogue affichée avec PlayAssetDelivery.ShowConfirmationDialog(). Cet état peut se produire si l'application n'est pas reconnue par Play. Notez que l'appel de PlayAssetDelivery.ShowConfirmationDialog() dans ce cas entraîne la mise à jour de l'application. Une fois la mise à jour effectuée, demandez à nouveau les composants.
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;
}
}
Annuler une requête (à la demande uniquement)
Si vous devez annuler la requête avant que les AssetBundles ne soient chargés en mémoire, appelez la méthode AttemptCancel() sur l'objet PlayAssetBundleRequest :
// 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.
}
Demander des packs d'éléments de manière asynchrone
Dans la plupart des cas, vous devez utiliser des coroutines pour demander des packs d'éléments de manière asynchrone et surveiller la progression, comme indiqué ci-dessous :
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;
Pour en savoir plus sur la gestion des erreurs, consultez la liste de AssetDeliveryErrorCodes.
Autres méthodes de l'API Play Core
Voici quelques méthodes d'API supplémentaires que vous pouvez utiliser dans votre application.
Vérifier la taille du téléchargement
Vérifiez la taille d'un AssetBundle en effectuant un appel asynchrone vers Google Play et en définissant une méthode de rappel pour la fin de l'opération :
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();
}
}
Supprimer les AssetBundles
Vous pouvez supprimer les AssetBundles à distribution rapide et à la demande qui ne sont actuellement pas chargés dans la mémoire. Effectuez l'appel asynchrone suivant et définissez une méthode de rappel pour la fin de l'opération :
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.
}
};
Étapes suivantes
Testez Asset Delivery en local et à partir de Google Play.