Cette page a été traduite par l'API Cloud Translation.

Prise en charge des mises à jour dans l'application (Unity)

Ce guide explique comment intégrer les mises à jour dans l'application à l'aide d'Unity. Il existe des guides distincts selon que votre implémentation utilise le langage de programmation Kotlin ou Java, ou bien du code natif (C/C++).

Configurer l'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.appupdate

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.appupdate

Ouvrez 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 .unitypackage sur GitHub.
Importez le fichier .unitypackage en 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.

Présentation du SDK Unity

L'API Play de mise à jour dans les applications fait partie de la famille du SDK Play Core. Le plug-in Unity propose une classe AppUpdateManager pour gérer la communication entre votre application et l'API Play. Vous devez instancier cette classe avant de pouvoir l'utiliser pour gérer les mises à jour dans l'application :

AppUpdateManager appUpdateManager = new AppUpdateManager();

Vérifier si une mise à jour est disponible

Avant de demander une mise à jour, vérifiez si l'une d'entre elles est disponible pour votre application. Utilisez AppUpdateManager pour rechercher une mise à jour dans une coroutine :

IEnumerator CheckForUpdate()
{
  PlayAsyncOperation<AppUpdateInfo, AppUpdateErrorCode> appUpdateInfoOperation =
    appUpdateManager.GetAppUpdateInfo();

  // Wait until the asynchronous operation completes.
  yield return appUpdateInfoOperation;

  if (appUpdateInfoOperation.IsSuccessful)
  {
    var appUpdateInfoResult = appUpdateInfoOperation.GetResult();
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

L'instance AppUpdateInfo renvoyée contient l'état de disponibilité de la mise à jour. Si une mise à jour dans l'application est déjà en cours, l'instance signale également son statut.

Vérifier l'obsolescence des mises à jour

En plus de vérifier si une mise à jour est disponible, vous pouvez aussi consulter le temps écoulé depuis la dernière notification de mise à jour reçue par l'utilisateur via le Play Store. Cela peut vous aider à décider si vous devez lancer une mise à jour flexible ou immédiate. Par exemple, vous pouvez attendre quelques jours avant d'informer l'utilisateur d'une mise à jour flexible, puis quelques jours encore avant de demander une mise à jour immédiate.

Utilisez ClientVersionStalenessDays pour vérifier le nombre de jours écoulés depuis la mise à jour via le Play Store :

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Vérifier la priorité des mises à jour

L'API Google Play Developer vous permet de définir la priorité de chaque mise à jour. Votre application peut ainsi déterminer le degré de recommandation d'une mise à jour auprès de l'utilisateur. Prenons la stratégie suivante pour exemple :

Améliorations mineures de l'interface utilisateur : mise à jour de faible priorité ; ne demandez ni une mise à jour flexible, ni une mise à jour immédiate.
Améliorations des performances : mise à jour de priorité moyenne ; demandez une mise à jour flexible.
Mise à jour de sécurité critique : mise à jour de priorité élevée ; demandez une mise à jour immédiate.

Pour déterminer la priorité, Google Play utilise un nombre entier compris entre 0 et 5, 0 étant la valeur par défaut et 5 étant la priorité la plus élevée. Pour définir la priorité d'une mise à jour, utilisez le champ inAppUpdatePriority sous Edits.tracks.releases dans l'API Google Play Developer. Toutes les nouvelles versions ajoutées sont considérées comme ayant la même priorité que la release. La priorité ne peut être définie que lors du déploiement d'une nouvelle release. Elle ne peut pas être modifiée ultérieurement.

Définissez la priorité à l'aide de l'API Google Play Developer, comme décrit dans la documentation de l'API Play Developer. La priorité de mise à jour dans l'application doit être spécifiée dans la ressource Edit.tracks qui est transmise via la méthode Edit.tracks: update. L'exemple suivant montre comment publier une application avec le code de version 88 et une inAppUpdatePriority de 5 :

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

Dans le code de votre application, vous pouvez vérifier le niveau de priorité d'une mise à jour donnée à l'aide de UpdatePriority :

var priority = appUpdateInfoOperation.UpdatePriority;

Commencer une mise à jour

Après vous être assuré qu'une mise à jour est disponible, vous pouvez la demander via AppUpdateManager.StartUpdate(). Avant cela, assurez-vous que vous disposez d'un objet AppUpdateInfo à jour. Vous devez également créer un objet AppUpdateOptions pour configurer le flux de mise à jour.

L'exemple suivant crée un objet AppUpdateOptions pour un flux de mise à jour immédiat :

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

L'exemple suivant crée un objet AppUpdateOptions pour un flux de mise à jour flexible :

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

L'objet AppUpdateOptions contient également un champ AllowAssetPackDeletion qui définit si la mise à jour est autorisée à effacer les packs d'éléments en cas d'espace de stockage limité sur l'appareil. Ce champ est défini sur false par défaut, mais vous pouvez transmettre l'argument facultatif allowAssetPackDeletion à ImmediateAppUpdateOptions() ou FlexibleAppUpdateOptions() pour le définir sur true :

// Creates an AppUpdateOptions for an immediate flow that allows
// asset pack deletion.
var appUpdateOptions =
  AppUpdateOptions.ImmediateAppUpdateOptions(allowAssetPackDeletion: true);

// Creates an AppUpdateOptions for a flexible flow that allows asset
// pack deletion.
var appUpdateOptions =
  AppUpdateOptions.FlexibleAppUpdateOptions(allowAssetPackDeletion: true);

Les étapes suivantes varient selon que vous demandez une mise à jour flexible ou immédiate.

Gérer une mise à jour flexible

Une fois que vous disposez d'un objet AppUpdateInfo à jour et d'un objet AppUpdateOptions correctement configuré, vous pouvez appeler AppUpdateManager.StartUpdate() pour demander un flux de mise à jour de manière asynchrone.

IEnumerator StartFlexibleUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);

  while (!startUpdateRequest.IsDone)
  {
  // For flexible flow,the user can continue to use the app while
  // the update downloads in the background. You can implement a
  // progress bar showing the download status during this time.
  yield return null;
  }

}

Pour un flux de mise à jour flexible, vous devez déclencher l'installation de la mise à jour de l'application une fois le téléchargement terminé. Pour ce faire, appelez AppUpdateManager.CompleteUpdate(), comme indiqué dans l'exemple suivant :

IEnumerator CompleteFlexibleUpdate()
{
  var result = appUpdateManager.CompleteUpdate();
  yield return result;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (e.g. by
  // logging result.Error or by displaying a message to the user).
}

Gérer une mise à jour immédiate

IEnumerator StartImmediateUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);
  yield return startUpdateRequest;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (for
  // example, by logging result.Error or by displaying a message to the user).
}

Pour afficher immédiatement le flux de mise à jour, Google Play ouvre une boîte de dialogue de confirmation de l'utilisateur. Lorsque l'utilisateur accepte la requête, Google Play télécharge et installe automatiquement la mise à jour, puis redémarre l'application vers la version mise à jour si l'installation aboutit.

Traitement des erreurs

Cette section décrit les solutions aux erreurs courantes.

Si StartUpdate() génère une erreur ArgumentNullException, cela signifie que AppUpdateInfo est nul. Assurez-vous que l'objet AppUpdateInfo renvoyé par GetAppUpdateInfo() n'est pas nul avant de lancer le flux de mise à jour.
Si PlayAsyncOperation renvoie le code d'erreur ErrorUpdateUnavailable, assurez-vous qu'une version mise à jour de l'application est disponible avec le même ID d'application et la même clé de signature.
Si PlayAsyncOperation renvoie le code d'erreur ErrorUpdateNotAllowed, cela signifie que l'objet AppUpdateOptions indique un type de mise à jour non autorisé. Vérifiez si l'objet AppUpdateInfo indique que le type de mise à jour sélectionné est autorisé avant de lancer le flux de mise à jour.

Étapes suivantes

Testez les mises à jour dans votre application pour vérifier le bon fonctionnement de l'intégration.