Supportare gli aggiornamenti in-app (Unity)

Questa guida descrive come supportare gli annunci in-app aggiornamenti nella tua app utilizzando Unity. Esistono guide separate per i casi in cui la tua implementazione utilizzi la programmazione Kotlin o la programmazione Java lingua e i casi in cui le tue l'implementazione utilizza il codice nativo (C/C++).

Configura l'ambiente di sviluppo

Scarica la versione più recente 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 sono soggetti ai Termini di servizio del kit di sviluppo software di base di Play. Se scarichi e utilizzi i plug-in Unity di Google Play, accetti i Termini di servizio principali del Software Development Kit.

Panoramica dell'SDK Unity

L'API In-app Update di Google Play fa parte del programma Play Core SDK. L'unità Il plug-in offre AppUpdateManager per gestire la comunicazione tra la tua app e l'API Play. Devi Crea un'istanza di questo corso prima di poterlo utilizzare per gestire gli aggiornamenti in-app:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Verificare la disponibilità degli aggiornamenti

Prima di richiedere un aggiornamento, controlla se è disponibile un aggiornamento per il tuo dell'app. Usa AppUpdateManager per controllare se è disponibile un aggiornamento in un 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'oggetto restituito AppUpdateInfo contiene lo stato di disponibilità dell'aggiornamento. Se è già disponibile un aggiornamento in-app In corso, l'istanza segnala anche lo stato dell'aggiornamento.

Controlla lo stato di inattività degli aggiornamenti

Oltre a verificare la disponibilità di un aggiornamento, controlla quanto tempo è trascorso dall'ultima notifica di un aggiornamento all'utente tramite il Play Store. Questo può aiutarti a decidere se devi avviare o meno flessibile o immediato. Ad esempio, potresti attendere alcuni giorni prima di informare l'utente con un aggiornamento flessibile e alcuni giorni dopo prima di richiedere un aggiornamento immediato.

Utilizza le funzionalità di ClientVersionStalenessDays per controllare il numero di giorni da quando l'aggiornamento è diventato disponibile tramite Google Play Negozio:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Controlla 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 in che misura consigliare un aggiornamento all'utente. Ad esempio, considera la seguente strategia per impostare la priorità degli aggiornamenti:

• Miglioramenti di minore entità all'interfaccia utente: aggiornamento a priorità bassa; non richiede uno spazio né un aggiornamento immediato.
• Miglioramenti delle prestazioni: aggiornamento a priorità media; richiedere un piano flessibile aggiornamento.
• Aggiornamento critico della sicurezza: aggiornamento ad alta priorità; richiedi un accesso immediato aggiornamento.

Per determinare la priorità, Google Play utilizza un valore intero compreso tra 0 e 5, con 0 il valore predefinito e 5 la priorità massima. Per impostare la priorità di un aggiorna, usa il campo inAppUpdatePriority sotto Edits.tracks.releases nella API Google Play Developer. Tutte le versioni appena aggiunte nella release con la stessa priorità dell'uscita. La priorità può essere impostata solo quando una nuova release e non può essere modificata in un secondo momento.

Imposta la priorità utilizzando l'API Google Play Developer come descritto nella sezione API per sviluppatori documentazione. La priorità dell'aggiornamento in-app deve essere specificata nel Edit.tracks passata nella Edit.tracks: update . L'esempio seguente mostra il rilascio di un'app con il 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;

Avvia un aggiornamento

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

L'esempio seguente crea un oggetto AppUpdateOptions per una richiesta immediata flusso di aggiornamento:

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

Nell'esempio seguente viene creato un oggetto AppUpdateOptions per un'istanza flessibile flusso di aggiornamento:

// 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 asset pacchetti se lo spazio di archiviazione sul dispositivo è limitato. Questo il campo è impostato su false per impostazione predefinita, ma puoi trasmettere allowAssetPackDeletion argomento facoltativo per 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);

Nota: utilizza con attenzione l'opzione API AllowAssetPackDeletion per evitare l'eliminazione accidentale di asset. Prima di impostare questa opzione su true, devi controlla AppUpdateManager.IsUpdateTypeAllowed() con AllowAssetPackDeletion impostata su false.

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

Gestire un aggiornamento flessibile

Dopo che hai un oggetto AppUpdateInfo aggiornato e un oggetto configurato correttamente AppUpdateOptions oggetto, puoi chiamare AppUpdateManager.StartUpdate() a 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. A questo scopo, 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 che hai un oggetto AppUpdateInfo aggiornato e un oggetto configurato correttamente AppUpdateOptions oggetto, puoi chiamare AppUpdateManager.StartUpdate() a 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 automaticamente e installa l'aggiornamento, quindi riavvia l'app con la versione aggiornata, se l'installazione è riuscita.

Gestione degli errori

Questa sezione descrive le soluzioni agli errori comuni.

• Se StartUpdate() lancia un ArgumentNullException, significa che AppUpdateInfo è nullo. Assicurati che l'oggetto AppUpdateInfo restituito da GetAppUpdateInfo() non è null prima di avviare il flusso di aggiornamento.
• Se PlayAsyncOperation restituisce il codice di errore ErrorUpdateUnavailable, effettua assicurati che sia disponibile una versione aggiornata dell'app con la stessa applicazione ID e chiave di firma.
• Se PlayAsyncOperation restituisce il codice di errore ErrorUpdateNotAllowed, significa che l'oggetto AppUpdateOptions indica un tipo di aggiornamento che non è consentito per l'aggiornamento disponibile. Controlla se l'oggetto AppUpdateInfo indica che il tipo di aggiornamento selezionato è consentito prima di avviare l'aggiornamento flusso di lavoro.

Passaggi successivi

Testare gli aggiornamenti in-app dell'app per effettuare la verifica che l'integrazione funzioni correttamente.