Obsługa aktualizacji w aplikacji (Unity)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji w aplikacji korzystającej z Unity. Istnieją oddzielne przewodniki na wypadek, gdy Twoja implementacja korzysta z języka programowania Kotlin lub Javy, oraz na wypadek, gdy Twoja implementacja korzysta z kodu natywnego (C/C++).

Omówienie pakietu Unity SDK

Interfejs API aktualizacji w aplikacji Play należy do rodziny pakietów Play Core SDK. Wtyczka Unity udostępnia 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 dostępna aktualizacja aplikacji. Aby sprawdzić, czy coroutine została zaktualizowana, 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 instancja AppUpdateInfo zawiera stan dostępności aktualizacji. Jeśli aktualizacja w aplikacji jest już w toku, instancja podaje też stan tej aktualizacji.

Sprawdzanie aktualności aktualizacji

Oprócz sprawdzenia, czy jest dostępna aktualizacja, warto też sprawdzić, ile czasu minęło od ostatniego powiadomienia o aktualizacji w Sklepie Play. Pomoże Ci to zdecydować, czy chcesz przeprowadzić elastyczne, czy natychmiastowe wprowadzenie zmian. Możesz na przykład poczekać kilka dni, zanim powiadomisz użytkownika o możliwości aktualizacji, a potem jeszcze kilka dni, zanim poprosisz o natychmiastową aktualizację.

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. Pozwala to aplikacji określić, jak mocno zalecić użytkownikowi zaktualizowanie aplikacji. Rozważ zastosowanie tej strategii ustawiania priorytetu aktualizacji:

• Niewielkie ulepszenia interfejsu: aktualizacja o niskim priorytecie; prośba o nieelastyczne ani natychmiastowe wdrożenie.
• Ulepszenia dotyczące wydajności: aktualizacja o średnim priorytecie; poproś o elastyczne aktualizacje.
• Niezbędna aktualizacja zabezpieczeń: wysoki priorytet; zalecana natychmiastowa aktualizacja.

Aby określić priorytet, Google Play używa liczby całkowitej z zakresu od 0 do 5, gdzie 0 to domyślny priorytet, a 5 – 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 ramach danej wersji mają ten sam priorytet. 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 Play Developer API. Priorytet aktualizacji w aplikacji powinien być określony w zasobie Edit.tracks przekazanym w ramach metody 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 sprawdzeniu, czy aktualizacja jest dostępna, możesz poprosić o nią za pomocą AppUpdateManager.StartUpdate(). Zanim poprosisz o aktualizację, upewnij się, że masz aktualny obiekt AppUpdateInfo. Aby skonfigurować proces aktualizacji, musisz też utworzyć obiekt AppUpdateOptions.

W tym przykładzie tworzymy obiekt AppUpdateOptions do natychmiastowego procesu aktualizacji:

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

W tym przykładzie tworzymy obiekt AppUpdateOptions do elastycznego procesu aktualizacji:

// 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 miejsca na urządzeniu. Domyślnie to pole jest ustawione na false, ale możesz przekazać opcjonalny argument allowAssetPackDeletion jako 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 prośba dotyczy elastycznej aktualizacji, czy natychmiastowej aktualizacji.

Obsługa elastycznej aktualizacji

Gdy masz aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, możesz wywołać funkcję AppUpdateManager.StartUpdate(), aby asynchronicznie poprosić o przeprowadzenie procesu 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;
  }

}

Aby umożliwić elastyczny proces aktualizacji, musisz wywołać instalację aktualizacji aplikacji po pomyślnym pobraniu. Aby to zrobić, wywołaj funkcję AppUpdateManager.CompleteUpdate(), jak w tym przykładzie:

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

Przeprowadzanie natychmiastowej aktualizacji

Gdy masz aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, możesz wywołać funkcję AppUpdateManager.StartUpdate(), aby asynchronicznie poprosić o przeprowadzenie procesu 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 natychmiastowej aktualizacji Google Play wyświetla użytkownikowi okno potwierdzenia. Gdy użytkownik zaakceptuje prośbę, Google Play automatycznie pobierze i zainstaluje aktualizację, a następnie uruchomi zaktualizowaną wersję aplikacji, jeśli instalacja przebiegnie pomyślnie.

Obsługa błędów

W tej sekcji znajdziesz rozwiązania typowych problemów.

• Jeśli funkcja StartUpdate() zwraca wartość ArgumentNullException, oznacza to, że AppUpdateInfo ma wartość null. Przed rozpoczęciem procesu aktualizacji sprawdź, czy obiekt AppUpdateInfo zwracany przez funkcję GetAppUpdateInfo() nie jest pusty.
• Jeśli funkcja PlayAsyncOperation zwraca kod błędu ErrorUpdateUnavailable, sprawdź, czy jest dostępna zaktualizowana wersja aplikacji z tym samym identyfikatorem aplikacji i tym samym kluczem podpisywania.
• Jeśli PlayAsyncOperation zwróci kod błędu ErrorUpdateNotAllowed, oznacza to, że obiekt AppUpdateOptions wskazuje typ aktualizacji, który nie jest dozwolony dla dostępnej aktualizacji. Przed rozpoczęciem procesu 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.