Obsługa aktualizacji w aplikacji (Unreal Engine)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji za pomocą Unreal Engine. Dostępne są osobne przewodniki dotyczące przypadków, w których implementacja używa języka programowania Kotlin lub Java, oraz przypadków, w których implementacja używa kodu natywnego (C/C++) lub Unity.

Omówienie pakietu SDK Unreal Engine

Interfejs Play In-App Updates API należy do rodziny pakietów SDK Play Core. Interfejs API dla Unreal Engine udostępnia klasę UInAppUpdatesManager do obsługi komunikacji między aplikacją a interfejsem Play API. Po wysłaniu prośby aplikacja może sprawdzić jej stan za pomocą EAppUpdateErrorCode.

Obsługiwane wersje Unreal Engine

Wtyczka obsługuje Unreal Engine 5.0 i wszystkie nowsze wersje.

Konfigurowanie środowiska programistycznego

Uwaga: jeśli w Unreal Engine używasz już wtyczek do opinii lub aktualizacji w aplikacji, możesz przejść do ostatniego kroku.

1. Pobierz wtyczkę Play Unreal Engine z repozytorium GitHub.

2. Skopiuj folder GooglePlay do folderu Plugins w projekcie Unreal Engine.

3. Otwórz projekt Unreal Engine i kliknij Edit → Plugins (Edytuj → Wtyczki).

4. Wyszukaj Google Play i zaznacz pole wyboru Włączone.

5. Uruchom ponownie projekt gry i aktywuj kompilację.

6. Otwórz plik Build.cs projektu i dodaj moduł PlayInAppUpdates do PublicDependencyModuleNames:

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

Sprawdzanie dostępności aktualizacji

Zanim poprosisz o aktualizację, sprawdź, czy jest dostępna aktualizacja aplikacji. Aby sprawdzić, czy jest dostępna aktualizacja, użyj UInAppUpdatesManager::RequestInfo:

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

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

Sprawdzanie aktualności aktualizacji

Oprócz sprawdzenia, 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 odczekać kilka dni, zanim powiadomisz użytkownika o elastycznej aktualizacji, i kolejne kilka dni, zanim zażądasz natychmiastowej aktualizacji.

Użyj UAppUpdateInfo:GetClientVersionStalenessDays, aby sprawdzić liczbę dni, które upłynęły od udostępnienia aktualizacji w Sklepie Play:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Sprawdzanie priorytetu aktualizacji

Interfejs Google Play Developer API umożliwia ustawienie priorytetu każdej aktualizacji. Dzięki temu aplikacja może określić, jak bardzo zalecać użytkownikowi aktualizację. Rozważmy na przykład taką strategię ustawiania priorytetu aktualizacji:

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

Do określenia priorytetu 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 ten sam priorytet co 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 przekazywanym w metodzie Edit.tracks: update. Poniższy 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, używając UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Rozpoczynanie aktualizacji

Po potwierdzeniu, że aktualizacja jest dostępna, możesz poprosić o jej zainstalowanie za pomocą UInAppUpdatesManager::StartUpdate. Zanim poprosisz o aktualizację, upewnij się, że masz aktualny obiekt UAppUpdateInfo. Musisz też utworzyć obiekt UAppUpdateOptions, aby skonfigurować proces aktualizacji.

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

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

Poniższy przykład tworzy obiekt UAppUpdateOptions dla elastycznego procesu aktualizacji:

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

Obiekt UAppUpdateOptions zawiera też funkcję IsAssetPackDeletionAllowed, która zwraca informację o tym, czy aktualizacja może wyczyścić pakiety zasobów w przypadku ograniczonej pamięci urządzenia. To pole jest domyślnie ustawione na false, ale możesz je ustawić na true, używając UAppUpdateOptions::SetAssetPackDeletionAllowed:

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

Uwaga: korzystaj z opcji interfejsu API AllowAssetPackDeletion ostrożnie, aby uniknąć przypadkowego usunięcia zasobów. Zanim ustawisz tę opcję na true, sprawdź UAppUpdateInfo::IsUpdateTypeAllowed z opcją AllowAssetPackDeletion ustawioną na false.

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

Obsługa aktualizacji elastycznej

Gdy masz aktualny obiekt UAppUpdateInfo i prawidłowo skonfigurowany obiekt UAppUpdateOptions, możesz wywołać UInAppUpdatesManager::StartUpdate, aby poprosić o proces aktualizacji.

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

W przypadku elastycznego procesu aktualizacji musisz uruchomić instalację aktualizacji aplikacji po zakończeniu pobierania. Aby to zrobić, wywołaj InAppUpdatesManager::CompleteUpdate, jak pokazano w tym przykładzie:

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

Obsługa natychmiastowej aktualizacji

Gdy masz aktualny obiekt UAppUpdateInfo i prawidłowo skonfigurowany obiekt UAppUpdateOptions, możesz wywołać InAppUpdatesManager::StartUpdate, aby poprosić o proces aktualizacji.

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

W przypadku natychmiastowej aktualizacji Google Play wyświetla okno potwierdzenia. Gdy użytkownik zaakceptuje prośbę, Google Play automatycznie pobierze i zainstaluje aktualizację, a następnie uruchomi ponownie 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 UInAppUpdatesManager::StartUpdate zwraca błąd AppUpdate_INVALID_REQUEST, oznacza to, że UAppUpdateInfo jest nieprawidłowy. Przed rozpoczęciem procesu aktualizacji upewnij się, że obiekt UAppUpdateInfo zwrócony z UInAppUpdatesManager::RequestInfo nie ma wartości null.
• Jeśli UInAppUpdatesManager::StartUpdate zwróci błąd AppUpdate_NOT_ALLOWED, oznacza to, że obiekt UAppUpdateOptions wskazuje typ aktualizacji, który nie jest dozwolony w przypadku dostępnej aktualizacji. Przed rozpoczęciem procesu aktualizacji sprawdź, czy obiekt UAppUpdateInfo wskazuje, że wybrany typ aktualizacji jest dozwolony.

Dalsze kroki

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