Unterstützung von In-App-Updates (Unity)

In diesem Leitfaden wird beschrieben, wie Sie mit Unity 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++) verwendet wird.

Entwicklungsumgebung einrichten

openupm add com.google.play.appupdate

Unity SDK – Übersicht

Die Play In-App-Update API ist Teil der Play Core SDK-Familie. Das Unity-Plug-in bietet eine AppUpdateManager-Klasse, die die Kommunikation zwischen Ihrer App und der Play API verwaltet. Sie müssen diese Klasse instanziieren, bevor Sie sie zum Verwalten von In-App-Aktualisierungen verwenden können:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Verfügbarkeit von Updates prüfen

Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre App verfügbar ist. Mit AppUpdateManager können Sie in einer Coroutine nach einem Update suchen:

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

Die zurückgegebene AppUpdateInfo-Instanz enthält den Status der Verfügbarkeit des Updates. Wenn bereits ein In-App-Update ausgeführt wird, wird in der Instanz auch der Status des laufenden Updates angegeben.

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 ClientVersionStalenessDays können Sie die Anzahl der Tage seit der Verfügbarkeit des Updates im Play Store prüfen:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Updatepriorität prüfen

Mit der Google Play Developer API können Sie die Priorität jeder Aktualisierung 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.

Google Play verwendet zur Bestimmung der Priorität 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 fest, wie in der Google Play Developer API-Dokumentation beschrieben. Die Priorität des In-App-Updates muss in der Edit.tracks-Ressource angegeben werden, die in der Edit.tracks: update-Methode übergeben wird. Im folgenden Beispiel wird das Veröffentlichen 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 mithilfe von UpdatePriority prüfen:

var priority = appUpdateInfoOperation.UpdatePriority;

Update starten

Wenn Sie sich vergewissert haben, dass ein Update verfügbar ist, können Sie es mit AppUpdateManager.StartUpdate() anfordern. Bevor Sie ein Update anfordern, müssen Sie ein aktuelles AppUpdateInfo-Objekt haben. Sie müssen auch ein AppUpdateOptions-Objekt erstellen, um den Aktualisierungsablauf zu konfigurieren.

Im folgenden Beispiel wird ein AppUpdateOptions-Objekt für einen sofortigen Aktualisierungsablauf erstellt:

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

Im folgenden Beispiel wird ein AppUpdateOptions-Objekt für einen flexiblen Aktualisierungsablauf erstellt:

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

Das AppUpdateOptions-Objekt enthält außerdem ein AllowAssetPackDeletion-Feld, das festlegt, ob beim Update Asset-Pakete gelöscht werden dürfen, wenn der Gerätespeicher begrenzt ist. Dieses Feld ist standardmäßig auf false festgelegt. Sie können das optionale Argument allowAssetPackDeletion an ImmediateAppUpdateOptions() oder FlexibleAppUpdateOptions() übergeben, um es stattdessen auf true festzulegen:

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

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

Flexible Aktualisierung verarbeiten

Wenn du ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt hast, kannst du AppUpdateManager.StartUpdate() aufrufen, um asynchron einen Aktualisierungsablauf anzufordern.

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

}

Für einen flexiblen Updatevorgang müssen Sie die Installation des App-Updates auslösen, nachdem der Download erfolgreich abgeschlossen wurde. Rufen Sie dazu AppUpdateManager.CompleteUpdate() auf, wie im folgenden Beispiel gezeigt:

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

Sofortige Aktualisierung verarbeiten

Wenn du ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt hast, kannst du AppUpdateManager.StartUpdate() aufrufen, um asynchron einen Aktualisierungsablauf anzufordern.

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

Bei einem sofortigen Update wird in Google Play ein Bestätigungsdialogfeld für den 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, wenn die Installation erfolgreich war.

Fehlerbehandlung

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

• Wenn StartUpdate() eine ArgumentNullException auslöst, bedeutet das, dass AppUpdateInfo null ist. Achte darauf, dass das von GetAppUpdateInfo() zurückgegebene AppUpdateInfo-Objekt nicht null ist, bevor du mit dem Aktualisierungsvorgang beginnst.
• Wenn PlayAsyncOperation den Fehlercode ErrorUpdateUnavailable zurückgibt, prüfen Sie, ob eine aktualisierte App-Version mit derselben Anwendungs-ID und demselben Signaturschlüssel verfügbar ist.
• Wenn PlayAsyncOperation den Fehlercode ErrorUpdateNotAllowed zurückgibt, bedeutet das, dass das AppUpdateOptions-Objekt einen Updatetyp angibt, der für das verfügbare Update nicht zulässig ist. Prüfen Sie, ob das AppUpdateInfo-Objekt angibt, 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 Einbindung ordnungsgemäß funktioniert.