Supporto degli aggiornamenti in-app (Unreal Engine)

Questa guida descrive come supportare gli aggiornamenti in-app nella tua app utilizzando Unreal Engine. Esistono guide separate per i casi in cui l'implementazione utilizza il linguaggio di programmazione Kotlin o il linguaggio di programmazione Java e per i casi in cui l'implementazione utilizza codice nativo (C/C++) o Unity.

Panoramica dell'SDK Unreal Engine

L'API Play In-App Updates fa parte della famiglia di SDK Play Core. L'API per Unreal Engine offre una classe UInAppUpdatesManager per gestire la comunicazione tra la tua app e l'API Play. Dopo aver effettuato una richiesta, l'app può controllare lo stato della richiesta utilizzando EAppUpdateErrorCode.

Versioni di Unreal Engine supportate

Il plug-in supporta Unreal Engine 5.0 e tutte le versioni successive.

Configurazione dell'ambiente di sviluppo

Nota: se hai già utilizzato i plug-in per le recensioni o gli aggiornamenti dell'app in Unreal Engine, puoi andare direttamente al passaggio finale.

1. Scarica il plug-in Play Unreal Engine dal repository GitHub.

2. Copia la cartella GooglePlay all'interno della cartella Plugins nel progetto Unreal Engine.

3. Apri il progetto Unreal Engine e fai clic su Edit → Plugins (Modifica → Plug-in).

4. Cerca Google Play e seleziona la casella di controllo Attivato.

5. Riavvia il progetto di gioco e attiva una build.

6. Apri il file Build.cs del progetto e aggiungi il modulo PlayInAppUpdates a PublicDependencyModuleNames:

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

Verifica la presenza di aggiornamenti

Prima di richiedere un aggiornamento, controlla se è disponibile un aggiornamento per la tua app. Utilizza UInAppUpdatesManager::RequestInfo per verificare la presenza di un aggiornamento:

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

L'istanza UAppUpdateInfo restituita contiene lo stato di disponibilità dell'aggiornamento. Se è già in corso un aggiornamento in-app, l'istanza segnala anche lo stato dell'aggiornamento in corso.

Controlla l'obsolescenza degli aggiornamenti

Oltre a controllare se è disponibile un aggiornamento, potresti anche voler controllare quanto tempo è trascorso dall'ultima volta che l'utente ha ricevuto una notifica di un aggiornamento tramite il Play Store. In questo modo, puoi decidere se avviare un aggiornamento flessibile o un aggiornamento immediato. Ad esempio, potresti attendere alcuni giorni prima di inviare una notifica all'utente con un aggiornamento flessibile e altri giorni prima di richiedere un aggiornamento immediato.

Utilizza UAppUpdateInfo:GetClientVersionStalenessDays per controllare il numero di giorni da quando l'aggiornamento è diventato disponibile tramite il Play Store:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Controlla la priorità degli aggiornamenti

L'API Google Play Developer ti consente di impostare la priorità di ogni aggiornamento. In questo modo, la tua app può decidere con quale intensità consigliare un aggiornamento all'utente. Ad esempio, considera la seguente strategia per impostare la priorità di aggiornamento:

• Miglioramenti secondari della UI: aggiornamento con priorità bassa; non richiedere un aggiornamento flessibile né un aggiornamento immediato.
• Miglioramenti delle prestazioni: aggiornamento con priorità media; richiedi un aggiornamento flessibile.
• Aggiornamento della sicurezza critico: aggiornamento ad alta priorità; richiedi un aggiornamento immediato.

Per determinare la priorità, Google Play utilizza un valore intero compreso tra 0 e 5, dove 0 è il valore predefinito e 5 è la priorità più alta. Per impostare la priorità di un aggiornamento, utilizza il campo inAppUpdatePriority in Edits.tracks.releases nell'API Google Play Developer. Tutte le versioni appena aggiunte alla release sono considerate con la stessa priorità della release. La priorità può essere impostata solo durante l'implementazione di una nuova release e non può essere modificata in un secondo momento.

Imposta la priorità utilizzando l'API Google Play Developer come descritto nella documentazione dell'API Google Play Developer. La priorità dell'aggiornamento dell'app in-app deve essere specificata nella risorsa Edit.tracks passata nel metodo Edit.tracks: update. L'esempio seguente mostra il rilascio di un'app con codice di versione 88 e inAppUpdatePriority 5:

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

Nel codice della tua app, puoi controllare il livello di priorità di un determinato aggiornamento utilizzando UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Avvia un aggiornamento

Dopo aver confermato che è disponibile un aggiornamento, puoi richiederlo utilizzando UInAppUpdatesManager::StartUpdate. Prima di richiedere un aggiornamento, assicurati di avere un oggetto UAppUpdateInfo aggiornato. Devi anche creare un oggetto UAppUpdateOptions per configurare il flusso di aggiornamento.

L'esempio seguente crea un oggetto UAppUpdateOptions per un flusso di aggiornamento immediato:

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

L'esempio seguente crea un oggetto UAppUpdateOptions per un flusso di aggiornamento flessibile:

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

L'oggetto UAppUpdateOptions contiene anche una funzione IsAssetPackDeletionAllowed che indica se l'aggiornamento può cancellare i pacchetti di asset in caso di spazio sul dispositivo limitato. Questo campo è impostato su false per impostazione predefinita, ma puoi impostarlo utilizzando UAppUpdateOptions::SetAssetPackDeletionAllowed per impostarlo su true:

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

Nota: utilizza l'opzione API AllowAssetPackDeletion con cautela per evitare di eliminare accidentalmente gli asset. Prima di impostare questa opzione su true, devi controllare UAppUpdateInfo::IsUpdateTypeAllowed con l'opzione AllowAssetPackDeletion impostata su false.

I passaggi successivi variano a seconda che tu stia richiedendo un aggiornamento flessibile o un aggiornamento immediato.

Gestisci un aggiornamento flessibile

Una volta ottenuto un oggetto UAppUpdateInfo aggiornato e un oggetto UAppUpdateOptions configurato correttamente, puoi chiamare UInAppUpdatesManager::StartUpdate per richiedere un flusso di aggiornamento.

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

Per un flusso di aggiornamento flessibile, devi attivare l'installazione dell'aggiornamento dell'app al termine del download. Per farlo, chiama InAppUpdatesManager::CompleteUpdate, come mostrato nell'esempio seguente:

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

Gestisci un aggiornamento immediato

Una volta ottenuto un oggetto UAppUpdateInfo aggiornato e un oggetto UAppUpdateOptions configurato correttamente, puoi chiamare InAppUpdatesManager::StartUpdate per richiedere un flusso di aggiornamento.

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

Per un flusso di aggiornamento immediato, Google Play mostra una finestra di dialogo di conferma per l'utente. Quando l'utente accetta la richiesta, Google Play scarica e installa automaticamente l'aggiornamento, quindi riavvia l'app alla versione aggiornata se l'installazione va a buon fine.

Gestione degli errori

Questa sezione descrive le soluzioni per gli errori comuni.

• Se UInAppUpdatesManager::StartUpdate restituisce un errore AppUpdate_INVALID_REQUEST, significa che UAppUpdateInfo non è valido. Assicurati che l'oggetto UAppUpdateInfo restituito da UInAppUpdatesManager::RequestInfo non sia nullo prima di avviare il flusso di aggiornamento.
• Se UInAppUpdatesManager::StartUpdate restituisce l'errore AppUpdate_NOT_ALLOWED, significa che l'oggetto UAppUpdateOptions indica un tipo di aggiornamento non consentito per l'aggiornamento disponibile. Controlla se l'oggetto UAppUpdateInfo indica che il tipo di aggiornamento selezionato è consentito prima di avviare il flusso di aggiornamento.

Passaggi successivi

Testa gli aggiornamenti in-app della tua app per verificare che l'integrazione funzioni correttamente.