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 codice nativo (C/C++).

Panoramica dell'SDK Unity

L'API aggiornamento in-app di 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 Google Play. Devi creare un'istanza di questa classe prima di poterla utilizzare per gestire gli aggiornamenti in-app:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Configurazione dell'ambiente di sviluppo

openupm add com.google.play.appupdate

Verificare la disponibilità di aggiornamenti

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

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

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

Controllare l'obsolescenza degli aggiornamenti

Oltre a verificare se è disponibile un aggiornamento, potresti anche voler controllare 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 un aggiornamento immediato. Ad esempio, potresti attendere alcuni giorni prima di notificare all'utente un aggiornamento flessibile e alcuni giorni dopo prima di richiedere un aggiornamento immediato.

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

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Controllare 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 insistenza consigliare un aggiornamento all'utente. Ad esempio, considera la seguente strategia per impostare la priorità di aggiornamento:

• Miglioramenti secondari dell'interfaccia utente: aggiornamento a bassa priorità; non richiedere un aggiornamento flessibile né un aggiornamento immediato.
• Miglioramenti delle prestazioni: aggiornamento a media priorità; 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 aggiunte di recente nella release hanno 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 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 può cancellare gli asset pack in caso di spazio di archiviazione del dispositivo limitato. Questo campo è impostato su false per impostazione predefinita, ma puoi trasmettere 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 tipo di aggiornamento richiesto: flessibile o 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 che il download è stato completato correttamente. 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 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 StartUpdate() genera un ArgumentNullException, significa che AppUpdateInfo è null. Assicurati che l'oggetto AppUpdateInfo restituito da GetAppUpdateInfo() non sia nullo prima di avviare il flusso di aggiornamento.
• 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 iniziare il flusso di aggiornamento.

Passaggi successivi

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