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

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

Ce guide explique comment prendre en charge les mises à jour dans l'application dans votre application à l'aide d'Unreal Engine. Il existe des guides distincts pour les cas où votre implémentation utilise le langage de programmation Kotlin ou Java, et pour les cas où votre implémentation utilise le code natif (C/C++) ou Unity.

Présentation du SDK Unreal Engine

L'API Play de mise à jour dans les applications fait partie de la famille du SDK Play Core. L'API Unreal Engine propose une classe UInAppUpdatesManager pour gérer la communication entre votre application et l'API Play. Une fois la requête envoyée, votre application peut vérifier l'état de la requête à l'aide de EAppUpdateErrorCode.

Versions d'Unreal Engine compatibles

Le plug-in est compatible avec Unreal Engine 5.0 et toutes les versions ultérieures.

Configurer l'environnement de développement

Téléchargez le plug-in Play Unreal Engine à partir du dépôt GitHub.
Copiez le dossier GooglePlay dans le dossier Plugins de votre projet Unreal Engine.
Ouvrez votre projet Unreal Engine, puis cliquez sur Edit → Plugins (Modifier → Plugins).
Recherchez Google Play, puis cochez la case Activé.
Redémarrez le projet de jeu et déclenchez une compilation.

Ouvrez le fichier Build.cs de votre projet et ajoutez le module PlayInAppUpdates à PublicDependencyModuleNames:

using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

Vérifier si une mise à jour est disponible

Avant de demander une mise à jour, vérifiez si une mise à jour est disponible pour votre application. Utilisez UInAppUpdatesManager::RequestInfo pour rechercher une mise à jour:

MyClass.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

MyClass.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

L'instance UAppUpdateInfo 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 indique également l'état de la mise à jour en cours.

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 UAppUpdateInfo:GetClientVersionStalenessDays pour vérifier le nombre de jours écoulés depuis la mise à jour disponible sur le Play Store:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

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 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 UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Commencer une mise à jour

Après avoir vérifié qu'une mise à jour est disponible, vous pouvez la demander à l'aide de UInAppUpdatesManager::StartUpdate. Avant de demander une mise à jour, assurez-vous de disposer d'un objet UAppUpdateInfo à jour. Vous devez également créer un objet UAppUpdateOptions pour configurer le flux de mise à jour.

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

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

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

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

L'objet UAppUpdateOptions contient également une fonction IsAssetPackDeletionAllowed qui indique 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 le définir sur true à l'aide de UAppUpdateOptions::SetAssetPackDeletionAllowed:

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

Les étapes suivantes dépendent de la demande de mise à jour flexible ou de mise à jour immédiate.

Gérer une mise à jour flexible

Une fois que vous disposez d'un objet UAppUpdateInfo à jour et d'un objet UAppUpdateOptions correctement configuré, vous pouvez appeler UInAppUpdatesManager::StartUpdate pour demander un flux de mise à jour.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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 InAppUpdatesManager::CompleteUpdate, comme indiqué dans l'exemple suivant:

MyClass.h

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Gérer une mise à jour immédiate

Une fois que vous disposez d'un objet UAppUpdateInfo à jour et d'un objet UAppUpdateOptions correctement configuré, vous pouvez appeler InAppUpdatesManager::StartUpdate pour demander un flux de mise à jour.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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 UInAppUpdatesManager::StartUpdate renvoie une erreur AppUpdate_INVALID_REQUEST, cela signifie que UAppUpdateInfo n'est pas valide. Assurez-vous que l'objet UAppUpdateInfo renvoyé à partir de UInAppUpdatesManager::RequestInfo n'est pas nul avant de lancer le flux de mise à jour.
Si UInAppUpdatesManager::StartUpdate renvoie l'erreur AppUpdate_NOT_ALLOWED, cela signifie que l'objet UAppUpdateOptions indique un type de mise à jour non autorisé. Vérifiez si l'objet UAppUpdateInfo 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 l'application de votre application pour vérifier que votre intégration fonctionne correctement.