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

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

Unity SDK – Übersicht

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

AppUpdateManager appUpdateManager = new AppUpdateManager();

Entwicklungsumgebung einrichten

openupm add com.google.play.appupdate

Prüfen, ob ein Update verfügbar ist

Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre App verfügbar ist. Verwenden Sie AppUpdateManager, um in einer Coroutine nach einem Update zu 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(), ... 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 Updateverfügbarkeit. Wenn ein In-App-Update bereits ausgeführt wird, wird auch der Status des laufenden Updates gemeldet.

Aktualität von Updates prüfen

Sie sollten nicht nur prüfen, ob ein Update verfügbar ist, sondern auch, wie viel Zeit seit der letzten Benachrichtigung des Nutzers über ein Update im Google Play Store vergangen ist. So können Sie besser entscheiden, ob Sie ein flexibles oder ein sofortiges Update starten sollten. Sie können beispielsweise einige Tage warten, bevor Sie den Nutzer mit einem flexiblen Update benachrichtigen, 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 Google Play Store prüfen:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Priorität von Updates prüfen

Mit der Google Play Developer API können Sie die Priorität der einzelnen Updates festlegen. So kann Ihre App entscheiden, wie dringend sie dem Nutzer ein Update empfiehlt. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Updatepriorität:

• Kleinere UI-Verbesserungen: Update mit niedriger Priorität; beantragen Sie weder ein flexibles noch ein sofortiges Update.
• Leistungsverbesserungen: Mittelpriorität; flexible Aktualisierung anfordern.
• Kritisches Sicherheitsupdate: Update mit hoher Priorität; sofortiges Update anfordern.

Google Play verwendet zur Bestimmung der Priorität einen ganzzahligen Wert zwischen 0 und 5, wobei 0 der Standardwert und 5 die höchste Priorität ist. Wenn Sie die Priorität für ein Update festlegen möchten, verwenden Sie 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 einer Neuveröffentlichung festgelegt und später nicht mehr geändert werden.

Legen Sie die Priorität mit der Google Play Developer API fest, wie in der Play Developer API-Dokumentation beschrieben. 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 gezeigt, wie eine App mit dem Versionscode 88 und 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 UpdatePriority prüfen:

var priority = appUpdateInfoOperation.UpdatePriority;

Update starten

Nachdem 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 sicherstellen, dass 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 Updateablauf erstellt:

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

Das AppUpdateOptions-Objekt enthält auch das Feld AllowAssetPackDeletion, das definiert, ob durch das Update Asset-Packs gelöscht werden dürfen, wenn der Gerätespeicher begrenzt ist. Dieses Feld ist standardmäßig auf false gesetzt. Sie können aber das optionale Argument allowAssetPackDeletion an ImmediateAppUpdateOptions() oder FlexibleAppUpdateOptions() übergeben, um es auf true zu setzen:

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

Nachdem Sie ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt haben, können Sie 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 abgeschlossen ist. 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).
}

Sofortiges Update durchführen

Nachdem Sie ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt haben, können Sie 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-Ablauf wird in Google Play ein Bestätigungsdialogfeld für den Nutzer angezeigt. Wenn der Nutzer die Anfrage akzeptiert, lädt Google Play das Update automatisch herunter und installiert es. Anschließend wird die App in der aktualisierten Version neu gestartet, sofern 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. Prüfen Sie, ob das von GetAppUpdateInfo() zurückgegebene AppUpdateInfo-Objekt nicht null ist, bevor Sie den Aktualisierungsvorgang starten.
• 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 Aktualisierungstyp 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 Integration ordnungsgemäß funktioniert.