Supportare gli aggiornamenti in-app (Unity)

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

Configurazione dell'ambiente di sviluppo

Scarica l'ultima release del plug-in Unity di aggiornamento in-app di Google Play dai pacchetti Google per Unity.

Nota: il download e l'utilizzo dei plug-in Unity di Google Play è soggetto ai Termini di servizio del Software Development Kit di Play Core. Se scarichi e utilizzi i plug-in Unity di Google Play, accetti i Termini di servizio del Play Core Software Development Kit.

Panoramica dell'SDK Unity

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

AppUpdateManager appUpdateManager = new AppUpdateManager();

Verifica la disponibilità di aggiornamenti

Prima di richiedere un aggiornamento, controlla se è disponibile un aggiornamento per la tua app. Usa 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(), etc. 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.

Controlla lo stato di obsolescenza degli aggiornamenti

Oltre a verificare la disponibilità di un aggiornamento, potresti anche controllare quanto tempo è trascorso dall'ultima notifica all'utente tramite il Play Store. Questo può aiutarti a 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 alcuni giorni dopo prima di richiedere un aggiornamento immediato.

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

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Controlla la priorità degli aggiornamenti

L'API Google Play Developer ti consente di impostare la priorità di ogni aggiornamento. Ciò consente all'app di decidere in che misura consigliare un aggiornamento all'utente. Ad esempio, considera la seguente strategia per l'impostazione della priorità di aggiornamento:

• Miglioramenti minori all'interfaccia utente: 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 critico della sicurezza: aggiornamento con 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, usa il campo inAppUpdatePriority in Edits.tracks.releases nell'API Google Play Developer. Tutte le nuove versioni aggiunte nella 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 Play Developer. La priorità di 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à per un determinato aggiornamento utilizzando UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

Avvia un aggiornamento

Dopo aver verificato che è disponibile un aggiornamento, puoi richiederlo utilizzando AppUpdateManager.StartUpdate(). Prima di richiedere un aggiornamento, assicurati di disporre di un oggetto AppUpdateInfo aggiornato. Devi inoltre 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 i pacchetti di asset in caso di spazio di archiviazione limitato sul dispositivo. Questo campo è impostato su false per impostazione predefinita, ma puoi passare l'argomento facoltativo allowAssetPackDeletion a ImmediateAppUpdateOptions() oppure 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);

Nota: utilizza l'opzione API AllowAssetPackDeletion con attenzione per evitare di eliminare accidentalmente gli asset. Prima di impostare questa opzione su true, dovresti controllare AppUpdateManager.IsUpdateTypeAllowed() con l'opzione AllowAssetPackDeletion impostata su false.

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

Gestire un aggiornamento flessibile

Dopo aver ottenuto 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 al termine 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 ottenuto 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 agli 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 che abbia 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

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