Obsługa aktualizacji w aplikacji (Unity)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji za pomocą Unity. Istnieją osobne przewodniki dotyczące przypadków, w których implementacja korzysta z języka programowania Kotlin lub Java, oraz przypadków, w których implementacja korzysta z kodu natywnego (C/C++).

Omówienie pakietu Unity SDK

Interfejs Play in-app update API jest częścią rodziny pakietów podstawowej biblioteki Play SDK. Wtyczka Unity oferuje klasę AppUpdateManager, która obsługuje komunikację między aplikacją a interfejsem Google Play API. Aby móc używać tej klasy do zarządzania aktualizacjami w aplikacji, musisz utworzyć jej instancję:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Konfigurowanie środowiska programistycznego

openupm add com.google.play.appupdate

Sprawdzanie dostępności aktualizacji

Zanim poprosisz o aktualizację, sprawdź, czy jest ona dostępna dla Twojej aplikacji. Aby sprawdzić dostępność aktualizacji w współprogramie, użyj AppUpdateManager:

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

Zwrócona AppUpdateInfo instancja zawiera stan dostępności aktualizacji. Jeśli aktualizacja w aplikacji jest już w toku, instancja zgłasza też jej stan.

Sprawdzanie, czy aktualizacja jest przestarzała

Oprócz sprawdzania, czy aktualizacja jest dostępna, możesz też sprawdzić, ile czasu minęło od ostatniego powiadomienia użytkownika o aktualizacji w Sklepie Play. Pomoże Ci to zdecydować, czy zainicjować aktualizację elastyczną czy natychmiastową. Możesz na przykład poczekać kilka dni, zanim powiadomisz użytkownika o aktualizacji elastycznej, a potem kilka dni, zanim poprosisz o aktualizację natychmiastową.

Aby sprawdzić, ile dni minęło od udostępnienia aktualizacji w Sklepie Play, użyj ClientVersionStalenessDays:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Sprawdzanie priorytetu aktualizacji

Interfejs Google Play Developer API umożliwia ustawienie priorytetu każdej aktualizacji. Dzięki temu Twoja aplikacja może zdecydować, jak mocno zalecać użytkownikowi aktualizację. Rozważ na przykład tę strategię ustawiania priorytetu aktualizacji:

• Drobne ulepszenia interfejsu: aktualizacja o niskim priorytecie ; nie proś o aktualizację elastyczną ani natychmiastową.
• Poprawa wydajności: aktualizacja o średnim priorytecie ; poproś o aktualizację elastyczną.
• Krytyczna aktualizacja zabezpieczeń: aktualizacja o wysokim priorytecie ; poproś o aktualizację natychmiastową.

Aby określić priorytet, Google Play używa liczby całkowitej z zakresu od 0 do 5, gdzie 0 to wartość domyślna, a 5 to najwyższy priorytet. Aby ustawić priorytet aktualizacji, użyj pola inAppUpdatePriority w sekcji Edits.tracks.releases w interfejsie Google Play Developer API. Wszystkie nowo dodane wersje w wersji są traktowane jako mające taki sam priorytet jak wersja. Priorytet można ustawić tylko podczas wdrażania nowej wersji i nie można go później zmienić.

Ustaw priorytet za pomocą interfejsu Google Play Developer API zgodnie z opisem w dokumentacji interfejsu Play Developer API. Priorytet aktualizacji w aplikacji należy określić w zasobie Edit.tracks przekazanym w metodzie Edit.tracks: update. Ten przykład pokazuje, jak opublikować aplikację z kodem wersji 88 i inAppUpdatePriority 5:

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

W kodzie aplikacji możesz sprawdzić poziom priorytetu danej aktualizacji za pomocą UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

Rozpoczynanie aktualizacji

Po upewnieniu się, że aktualizacja jest dostępna, możesz poprosić o nią za pomocą AppUpdateManager.StartUpdate(). Zanim poprosisz o aktualizację, upewnij się, że masz aktualny obiekt AppUpdateInfo. Musisz też utworzyć obiekt AppUpdateOptions, aby skonfigurować proces aktualizacji.

Ten przykład tworzy obiekt AppUpdateOptions dla procesu aktualizacji natychmiastowej:

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

Ten przykład tworzy obiekt AppUpdateOptions dla procesu aktualizacji elastycznej:

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

Obiekt AppUpdateOptions zawiera też pole AllowAssetPackDeletion które określa, czy aktualizacja może usuwać pakiety zasobów w przypadku ograniczonej ilości pamięci urządzenia. To pole jest domyślnie ustawione na false, ale możesz przekazać opcjonalny argument allowAssetPackDeletion do ImmediateAppUpdateOptions() lub FlexibleAppUpdateOptions(), aby ustawić je na true:

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

Dalsze kroki zależą od tego, czy prosisz o aktualizację elastyczną czy o aktualizację natychmiastową.

Obsługa aktualizacji elastycznej

Gdy masz aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, możesz wywołać AppUpdateManager.StartUpdate(), aby asynchronicznie poprosić o proces aktualizacji.

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

}

W przypadku procesu aktualizacji elastycznej musisz aktywować instalację aktualizacji aplikacji po pomyślnym zakończeniu pobierania. Aby to zrobić, wywołaj AppUpdateManager.CompleteUpdate() zgodnie z tym przykładem:

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

Obsługa aktualizacji natychmiastowej

Gdy masz aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, możesz wywołać AppUpdateManager.StartUpdate(), aby asynchronicznie poprosić o proces aktualizacji.

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

W przypadku procesu aktualizacji natychmiastowej Google Play wyświetla okno potwierdzenia dla użytkownika. Gdy użytkownik zaakceptuje prośbę, Google Play automatycznie pobierze i zainstaluje aktualizację, a następnie ponownie uruchomi aplikację w zaktualizowanej wersji, jeśli instalacja się powiedzie.

Obsługa błędów

W tej sekcji opisujemy rozwiązania typowych błędów.

• Jeśli StartUpdate() zgłosi wyjątek ArgumentNullException, oznacza to, że AppUpdateInfo ma wartość null. Zanim rozpoczniesz proces aktualizacji, upewnij się, że obiekt AppUpdateInfo zwrócony przez GetAppUpdateInfo() nie ma wartości null.
• Jeśli PlayAsyncOperation zwróci kod błędu ErrorUpdateUnavailable, upewnij się, że dostępna jest zaktualizowana wersja aplikacji, która ma ten sam identyfikator aplikacji i klucz podpisywania.
• Jeśli PlayAsyncOperation zwróci kod błędu ErrorUpdateNotAllowed, oznacza to, że obiekt AppUpdateOptions wskazuje typ aktualizacji, który nie jest dozwolony w przypadku dostępnej aktualizacji. Zanim rozpoczniesz proces aktualizacji, sprawdź, czy obiekt AppUpdateInfo wskazuje, że wybrany typ aktualizacji jest dozwolony.

Dalsze kroki

Przetestuj aktualizacje w aplikacji, aby sprawdzić, czy integracja działa prawidłowo.