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
Scarica il plug-in Play Unreal Engine dal repository GitHub.
Copia la cartella
GooglePlay
all'interno della cartellaPlugins
nel progetto Unreal Engine.Apri il progetto Unreal Engine e fai clic su Modifica → Plug-in.
Cerca Google Play e seleziona la casella di controllo Attiva.
Riavviare il progetto di gioco e attivare una compilazione.
Apri il file
Build.cs
del progetto e aggiungi il moduloPlayInAppUpdates
aPublicDependencyModuleNames
: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:
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.
}
}
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.
void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
// ...
}
// .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:
void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
// ...
}
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.
void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
// ...
}
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 erroreAppUpdate_INVALID_REQUEST
, significa cheUAppUpdateInfo
è non valido. Prima di avviare il flusso di aggiornamento, assicurati che l'oggettoUAppUpdateInfo
restituito daUInAppUpdatesManager::RequestInfo
non sia null. - Se
UInAppUpdatesManager::StartUpdate
restituisce l'erroreAppUpdate_NOT_ALLOWED
, significa che l'oggettoUAppUpdateOptions
indica un tipo di aggiornamento non consentito per l'aggiornamento disponibile. Controlla se l'oggettoUAppUpdateInfo
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.