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 il 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 che è stata effettuata una richiesta, l'app può controllarne lo stato utilizzando EAppUpdateErrorCode.

Versioni di Unreal Engine supportate

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

Configura l'ambiente di sviluppo

  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 Modifica → Plug-in.

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

  5. Riavviare il progetto di gioco e attivare una compilazione.

  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");
    
        // ...
      }
    }
    

Verificare la disponibilità di aggiornamenti

Prima di richiedere un aggiornamento, controlla se è disponibile un aggiornamento per la tua app. Usa 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 riporta anche lo stato dell'aggiornamento in corso.

Verificare l'obsolescenza degli aggiornamenti

Oltre a verificare se è disponibile un aggiornamento, ti consigliamo di controllare anche quanto tempo è trascorso dall'ultima notifica di aggiornamento inviata all'utente tramite il Play Store. In questo modo, puoi decidere se avviare un aggiornamento flessibile o immediato. Ad esempio, potresti attendere qualche giorno prima di inviare una notifica all'utente con un aggiornamento flessibile e qualche giorno dopo 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();

Controllare la priorità dell'aggiornamento

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

  • Miglioramenti secondari all'interfaccia utente: aggiornamento a bassa priorità; non richiedere un aggiornamento flessibile né un aggiornamento immediato.
  • Miglioramenti delle prestazioni: aggiornamento con priorità media; richiedi un aggiornamento flessibile.
  • Aggiornamento della sicurezza critico: priorità elevata; 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 nella release sono considerate della 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 in-app deve essere specificata nella risorsa Edit.tracks passata al metodo Edit.tracks: update. L'esempio seguente mostra il rilascio di un'app con codice versione 88 e inAppUpdatePriority 5:

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

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

int32 Priority = UpdateInfo->GetPriority();

Avviare un aggiornamento

Dopo aver verificato 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 restituisce se l'aggiornamento è autorizzato a eliminare i pacchetti di asset in caso di spazio di archiviazione del dispositivo limitato. Per impostazione predefinita, questo campo è impostato su false, ma puoi impostarlo su UAppUpdateOptions::SetAssetPackDeletionAllowed per impostarlo su true:

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

I passaggi successivi dipendono dal fatto che tu stia richiedendo un aggiornamento flessibile o un aggiornamento immediato.

Gestire un aggiornamento flessibile

Dopo aver creato 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 dopo il completamento 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);
}

Gestire un aggiornamento immediato

Dopo aver creato 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 dell'utente. Quando l'utente accetta la richiesta, Google Play scarica e installa automaticamente l'aggiornamento, quindi riavvia l'app con la versione aggiornata se l'installazione è andata 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. Prima di avviare il flusso di aggiornamento, assicurati che l'oggetto UAppUpdateInfo restituito da UInAppUpdatesManager::RequestInfo non sia null.
  • 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

Esegui il test degli aggiornamenti in-app della tua app per verificare che l'integrazione funzioni correttamente.