Unterstützung von In-App-Updates (Unreal Engine)

In diesem Leitfaden wird beschrieben, wie Sie In-App-Updates in Ihrer App mit der Unreal Engine unterstützen. Es gibt separate Leitfäden für Fälle, in denen Ihre Implementierung die Programmiersprache Kotlin oder Java verwendet, und für Fälle, in denen Ihre Implementierung nativen Code (C/C++) oder Unity verwendet.

Unreal Engine SDK – Übersicht

Die Play In-App Updates API ist Teil der Play Core SDK-Familie. Die API für Unreal Engine bietet eine UInAppUpdatesManager-Klasse, um die Kommunikation zwischen deiner App und der Play API zu verarbeiten. Nachdem eine Anfrage gestellt wurde, kann Ihre App den Status der Anfrage mit EAppUpdateErrorCode prüfen.

Unterstützte Unreal Engine-Versionen

Das Plug-in unterstützt die Unreal Engine 5.0 und alle nachfolgenden Versionen.

Entwicklungsumgebung einrichten

Hinweis: Wenn Sie die Plug-ins für In-App-Rezensionen oder In-App-Updates bereits in Unreal Engine verwendet haben, können Sie mit dem letzten Schritt fortfahren.

1. Laden Sie das Play Unreal Engine-Plug-in aus dem GitHub-Repository herunter.

2. Kopieren Sie den Ordner GooglePlay in den Ordner Plugins in Ihrem Unreal Engine-Projekt.

3. Öffnen Sie Ihr Unreal Engine-Projekt und klicken Sie auf Bearbeiten → Plug-ins.

4. Suchen Sie nach Google Play und setzen Sie ein Häkchen bei Aktiviert.

5. Starten Sie das Spielprojekt neu und lösen Sie einen Build aus.

6. Öffnen Sie die Build.cs-Datei Ihres Projekts und fügen Sie das PlayInAppUpdates-Modul zu PublicDependencyModuleNames hinzu:

   using UnrealBuildTool;
   
   public class MyGame : ModuleRules
   {
     public MyGame(ReadOnlyTargetRules Target) : base(Target)
     {
       // ...
   
       PublicDependencyModuleNames.Add("PlayInAppUpdates");
   
       // ...
     }
   }
   

Prüfen, ob ein Update verfügbar ist

Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre Anwendung verfügbar ist. Verwenden Sie UInAppUpdatesManager::RequestInfo, um nach einem Update zu suchen:

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

Die zurückgegebene UAppUpdateInfo-Instanz enthält den Status der Updateverfügbarkeit. Wenn bereits ein In-App-Update ausgeführt wird, meldet die Instanz auch den Status des laufenden Updates.

Aktualität von Updates prüfen

Zusätzlich zur Prüfung, ob ein Update verfügbar ist, solltest du auch prüfen, wie viel Zeit vergangen ist, seit der Nutzer zuletzt über den Google Play Store über ein Update benachrichtigt wurde. So kannst du besser entscheiden, ob du ein flexibles oder ein sofortiges Update initiieren solltest. Beispielsweise könntest du ein paar Tage warten, bevor du den Nutzer über ein flexibles Update benachrichtigst, und dann noch einmal ein paar Tage, bevor du ein sofortiges Update verlangst.

Mit UAppUpdateInfo:GetClientVersionStalenessDays können Sie die Anzahl der Tage prüfen, seit das Update im Google Play Store verfügbar ist:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Updatepriorität prüfen

Mit der Google Play Developer API können Sie die Priorität jedes Updates festlegen. So kann in Ihrer App entschieden werden, wie dringend ein Update empfohlen werden soll. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Updatepriorität:

• Kleinere Verbesserungen an der Benutzeroberfläche: Update mit niedriger Priorität; weder ein flexibles noch ein sofortiges Update anfordern.
• Leistungsverbesserungen: Update mit mittlerer Priorität; flexibles Update anfordern.
• Kritisches Sicherheitsupdate: Update mit hoher Priorität; sofortiges Update anfordern.

Zur Bestimmung der Priorität verwendet Google Play einen ganzzahligen Wert zwischen 0 und 5, wobei 0 der Standardwert und 5 die höchste Priorität ist. Wenn du die Priorität für ein Update festlegen möchtest, verwende das Feld inAppUpdatePriority unter Edits.tracks.releases in der Google Play Developer API. Alle neu hinzugefügten Versionen im Release haben dieselbe Priorität wie das Release. Die Priorität kann nur beim Roll-out eines neuen Release festgelegt und später nicht mehr geändert werden.

Legen Sie die Priorität mithilfe der Google Play Developer API fest, wie in der Dokumentation zur Play Developer API beschrieben. Die Priorität des In-App-Updates sollte in der Ressource Edit.tracks angegeben werden, die in der Methode Edit.tracks: update übergeben wird. Im folgenden Beispiel wird gezeigt, wie eine App mit dem Versionscode 88 und dem inAppUpdatePriority 5 veröffentlicht wird:

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

Im Code Ihrer App können Sie die Prioritätsstufe für ein bestimmtes Update mit UAppUpdateInfo::UpdatePriority prüfen:

int32 Priority = UpdateInfo->GetPriority();

Update starten

Nachdem Sie bestätigt haben, dass ein Update verfügbar ist, können Sie mit UInAppUpdatesManager::StartUpdate ein Update anfordern. Bevor Sie eine Aktualisierung anfordern, müssen Sie ein aktuelles UAppUpdateInfo-Objekt haben. Sie müssen auch ein UAppUpdateOptions-Objekt erstellen, um den Aktualisierungsablauf zu konfigurieren.

Im folgenden Beispiel wird ein UAppUpdateOptions-Objekt für einen sofortigen Update-Flow erstellt:

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

Im folgenden Beispiel wird ein UAppUpdateOptions-Objekt für einen flexiblen Update-Ablauf erstellt:

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

Das UAppUpdateOptions-Objekt enthält auch eine IsAssetPackDeletionAllowed-Funktion, die zurückgibt, ob das Update bei begrenztem Gerätespeicher Asset-Packs löschen darf. Dieses Feld ist standardmäßig auf false gesetzt. Sie können es aber mit UAppUpdateOptions::SetAssetPackDeletionAllowed auf true setzen:

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

Hinweis: Verwenden Sie die API-Option AllowAssetPackDeletion mit Bedacht, um ein versehentliches Löschen von Assets zu vermeiden. Bevor Sie diese Option auf true setzen, sollten Sie UAppUpdateInfo::IsUpdateTypeAllowed mit der Option AllowAssetPackDeletion auf false prüfen.

Die nächsten Schritte hängen davon ab, ob du ein flexibles Update oder ein Sofortupdate anforderst.

Flexibles Update verarbeiten

Sobald Sie ein aktuelles UAppUpdateInfo-Objekt und ein richtig konfiguriertes UAppUpdateOptions-Objekt haben, können Sie UInAppUpdatesManager::StartUpdate aufrufen, um einen Aktualisierungsablauf anzufordern.

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

Für einen flexiblen Update-Ablauf müssen Sie die Installation des App-Updates nach dem erfolgreichen Download auslösen. Rufen Sie dazu InAppUpdatesManager::CompleteUpdate auf, wie im folgenden Beispiel gezeigt:

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

Sofortiges Update verarbeiten

Sobald Sie ein aktuelles UAppUpdateInfo-Objekt und ein richtig konfiguriertes UAppUpdateOptions-Objekt haben, können Sie InAppUpdatesManager::StartUpdate aufrufen, um einen Aktualisierungsablauf anzufordern.

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

Bei einem sofortigen Update zeigt Google Play ein Bestätigungsdialogfeld für den Nutzer an. Wenn der Nutzer die Anfrage akzeptiert, wird das Update automatisch von Google Play heruntergeladen und installiert. Nach erfolgreicher Installation wird die App in der aktualisierten Version neu gestartet.

Fehlerbehandlung

In diesem Abschnitt werden Lösungen für häufige Fehler beschrieben.

• Wenn UInAppUpdatesManager::StartUpdate den Fehler AppUpdate_INVALID_REQUEST zurückgibt, ist UAppUpdateInfo ungültig. Prüfe, ob das von UInAppUpdatesManager::RequestInfo zurückgegebene UAppUpdateInfo-Objekt nicht null ist, bevor du den Aktualisierungsvorgang startest.
• Wenn UInAppUpdatesManager::StartUpdate den Fehler AppUpdate_NOT_ALLOWED zurückgibt, bedeutet dies, dass das Objekt UAppUpdateOptions einen Aktualisierungstyp angibt, der für die verfügbare Aktualisierung nicht zulässig ist. Prüfe, ob das Objekt UAppUpdateInfo angibt, dass der ausgewählte Updatetyp zulässig ist, bevor du den Updatevorgang startest.

Nächste Schritte

Teste die In-App-Updates deiner App, um zu prüfen, ob die Integration ordnungsgemäß funktioniert.