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

In diesem Leitfaden wird beschrieben, wie Sie mit Unreal Engine In-App-Updates in Ihrer App unterstützen. Es gibt separate Anleitungen für den Fall, dass in Ihrer Implementierung die Programmiersprache Kotlin oder die Programmiersprache Java verwendet wird, und für den Fall, dass in Ihrer Implementierung nativer Code (C/C++) oder Unity verwendet wird.

Unreal Engine SDK – Übersicht

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

Unterstützte Unreal Engine-Versionen

Das Plug-in unterstützt 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 der Unreal Engine verwendet haben, können Sie mit dem letzten Schritt fortfahren.

1. Lade 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 klicken Sie das Kästchen Aktiviert an.

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 PublicDependencyModuleNames das PlayInAppUpdates-Modul hinzu:

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

Verfügbarkeit von Updates prüfen

Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre App verfügbar ist. So können Sie mit UInAppUpdatesManager::RequestInfo nach einem Update 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 Verfügbarkeit des Updates. Wenn bereits ein In-App-Update ausgeführt wird, gibt die Instanz auch den Status des laufenden Updates an.

Aktualität von Updates prüfen

Sie sollten nicht nur prüfen, ob ein Update verfügbar ist, sondern auch, wie viel Zeit vergangen ist, seit der Nutzer zuletzt über den Play Store über ein Update informiert wurde. So können Sie leichter entscheiden, ob Sie ein flexibles Update oder ein sofortiges Update starten sollten. Sie können beispielsweise einige Tage warten, bevor Sie den Nutzer über ein flexibles Update informieren, und einige Tage danach, bevor Sie ein sofortiges Update verlangen.

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

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Priorität des Updates prüfen

Mit der Google Play Developer API können Sie die Priorität jedes Updates festlegen. So kann Ihre App entscheiden, wie dringend ein Update für den Nutzer 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: Aktualisierung mit mittlerer Priorität; flexible Aktualisierung anfordern.
• Kritisches Sicherheitsupdate: Update mit hoher Priorität; sofortiges Update anfordern.

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

Legen Sie die Priorität mit der Google Play Developer API wie in der Dokumentation zur Google Play Developer API beschrieben fest. Die Priorität für In-App-Updates sollte in der Edit.tracks-Ressource angegeben werden, die in der Methode Edit.tracks: update übergeben wird. Im folgenden Beispiel wird die Veröffentlichung einer App mit dem Versionscode 88 und inAppUpdatePriority 5 veranschaulicht:

{
  "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 es mit UInAppUpdatesManager::StartUpdate anfordern. Bevor Sie ein Update anfordern, müssen Sie ein aktuelles UAppUpdateInfo-Objekt haben. Außerdem müssen Sie ein UAppUpdateOptions-Objekt erstellen, um den Aktualisierungsablauf zu konfigurieren.

Im folgenden Beispiel wird ein UAppUpdateOptions-Objekt für einen sofortigen Aktualisierungsablauf 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 Aktualisierungsablauf 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 außerdem eine IsAssetPackDeletionAllowed-Funktion, die zurückgibt, ob das Update Asset-Pakete löschen darf, wenn der Gerätespeicher begrenzt ist. Dieses Feld ist standardmäßig auf false gesetzt. Sie können es aber auch mit UAppUpdateOptions::SetAssetPackDeletionAllowed auf true setzen:

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

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

Die nächsten Schritte hängen davon ab, ob Sie eine flexible Aktualisierung oder eine sofortige Aktualisierung anfordern.

Flexibles Update verarbeiten

Sobald du ein aktuelles UAppUpdateInfo-Objekt und ein richtig konfiguriertes UAppUpdateOptions-Objekt hast, kannst du 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 Updateablauf müssen Sie die Installation des App-Updates auslösen, nachdem der Download erfolgreich abgeschlossen wurde. 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);
}

Sofortige Aktualisierung verarbeiten

Sobald du ein aktuelles UAppUpdateInfo-Objekt und ein richtig konfiguriertes UAppUpdateOptions-Objekt hast, kannst du 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 wird bei Google Play ein Bestätigungsdialogfeld für Nutzer angezeigt. Wenn der Nutzer die Anfrage akzeptiert, wird das Update automatisch von Google Play heruntergeladen und installiert. Anschließend wird die App mit der aktualisierten Version neu gestartet, sofern die Installation erfolgreich war.

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. Achte darauf, dass 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, gibt das UAppUpdateOptions-Objekt einen Updatetyp an, der für das verfügbare Update nicht zulässig ist. Prüfen Sie, ob im UAppUpdateInfo-Objekt angegeben ist, dass der ausgewählte Updatetyp zulässig ist, bevor Sie den Updatevorgang starten.

Nächste Schritte

Testen Sie die In-App-Updates Ihrer App, um zu prüfen, ob die Integration ordnungsgemäß funktioniert.