Supportare gli aggiornamenti in-app (Unity)

Questa guida descrive come supportare gli aggiornamenti in-app nella tua app utilizzando Unity. 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++).

Configura l'ambiente di sviluppo

openupm add com.google.play.appupdate

Panoramica dell'SDK Unity

L'API di aggiornamento in-app di Google Play fa parte della famiglia di SDK Play Core. Il plug-in Unity offre una classe AppUpdateManager per gestire la comunicazione tra la tua app e l'API Play. Devi inizializzare questa classe prima di poterla utilizzare per gestire gli aggiornamenti in-app:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Verificare la disponibilità di aggiornamenti

Prima di richiedere un aggiornamento, controlla se è disponibile un aggiornamento per la tua app. Utilizza AppUpdateManager per controllare se è disponibile un aggiornamento in una coerenza:

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(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

L'istanza AppUpdateInfo ritornata 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.

Controllare 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 ClientVersionStalenessDays per controllare il numero di giorni dall'aggiornamento è diventato disponibile tramite il Play Store:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

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à di 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 update, 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 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 dell'app, puoi controllare il livello di priorità di un determinato aggiornamento utilizzando UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

Avviare un aggiornamento

Dopo aver verificato che è disponibile un aggiornamento, puoi richiederlo utilizzando AppUpdateManager.StartUpdate(). Prima di richiedere un aggiornamento, assicurati di avere un oggetto AppUpdateInfo aggiornato. Devi anche creare un oggetto AppUpdateOptions per configurare il flusso di aggiornamento.

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

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

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

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

L'oggetto AppUpdateOptions contiene anche un campo AllowAssetPackDeletion che definisce se l'aggiornamento è autorizzato a cancellare i pacchetti di asset in caso di spazio di archiviazione limitato del dispositivo. Per impostazione predefinita, questo campo è impostato su false, ma puoi passare l'argomento facoltativo allowAssetPackDeletion a ImmediateAppUpdateOptions() o FlexibleAppUpdateOptions() per impostarlo su 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);

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 AppUpdateInfo aggiornato e un oggetto AppUpdateOptions configurato correttamente, puoi chiamare AppUpdateManager.StartUpdate() per richiedere in modo asincrono un flusso di aggiornamento.

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

}

Per un flusso di aggiornamento flessibile, devi attivare l'installazione dell'aggiornamento dell'app dopo il completamento del download. Per farlo, chiama AppUpdateManager.CompleteUpdate(), come mostrato nell'esempio seguente:

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

Gestire un aggiornamento immediato

Dopo aver creato un oggetto AppUpdateInfo aggiornato e un oggetto AppUpdateOptions configurato correttamente, puoi chiamare AppUpdateManager.StartUpdate() per richiedere in modo asincrono un flusso di aggiornamento.

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

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 va a buon fine.

Gestione degli errori

Questa sezione descrive le soluzioni per gli errori più comuni.

• Se StartUpdate() genera un ArgumentNullException, significa che AppUpdateInfo è null. Prima di avviare il flusso di aggiornamento, assicurati che l'oggetto AppUpdateInfo restituito da GetAppUpdateInfo() non sia null.
• Se PlayAsyncOperation restituisce il codice di errore ErrorUpdateUnavailable, assicurati che sia disponibile una versione aggiornata dell'app con lo stesso ID applicazione e la stessa chiave di firma.
• Se PlayAsyncOperation restituisce il codice di errore ErrorUpdateNotAllowed, significa che l'oggetto AppUpdateOptions indica un tipo di aggiornamento non consentito per l'aggiornamento disponibile. Controlla se l'oggetto AppUpdateInfo 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.