Condividi tramite

App Center Distribute - Aggiornamenti in-app di Unity

  • Articolo

Importante

Visual Studio App Center è pianificato per il ritiro il 31 marzo 2025. Anche se è possibile continuare a usare Visual Studio App Center fino a quando non viene completamente ritirato, esistono diverse alternative consigliate a cui è possibile prendere in considerazione la migrazione.

Altre informazioni sulle sequenze temporali di supporto e sulle alternative.

La distribuzione di App Center consente agli utenti/tester di installare nuove versioni di un'app dopo averla distribuita tramite App Center. Dopo l'abilitazione, l'SDK presenta una finestra di dialogo di aggiornamento agli utenti per scaricare o posticipare l'installazione dell'aggiornamento più recente. Dopo aver scelto di eseguire l'aggiornamento, l'SDK inizierà ad aggiornare l'applicazione.

Importante

Distribute SDK per Unity non supporta la piattaforma UWP. Le istruzioni in questa pagina riguardano solo Android e iOS.

Avviso

Google Play considera il codice di aggiornamento in-app come un comportamento dannoso anche se non viene usato in fase di esecuzione. Rimuovere questo codice come indicato in questa sezione prima di inviare l'app a Google Play. La mancata rimozione del codice di aggiornamento in-app può causare la mancata conformità e la rimozione dell'app da Google Play.

Nota

Se si eseguono test automatizzati dell'interfaccia utente, gli aggiornamenti in-app abilitati bloccano i test automatizzati dell'interfaccia utente man mano che proveranno a eseguire l'autenticazione nel back-end di App Center. È consigliabile disabilitare gli aggiornamenti in-app per i test dell'interfaccia utente.

Aggiungere aggiornamenti in-app all'app

Aggiungere il modulo App Center Distribute

App Center SDK è progettato con un approccio modulare: uno sviluppatore deve integrare solo i moduli dei servizi a cui sono interessati.

Seguire la documentazione introduttiva di Unity se non è ancora stato configurato e avviato l'SDK nell'applicazione. Assicurarsi di importare il pacchetto App Center Distribute. Il nome deve essere nel formato AppCenterDistribute-v{version}.unitypackage.

Nota

Android 10 o versione successiva presenta restrizioni per l'attività di avvio in background. Vedere l'articolo sulle restrizioni relative all'avvio delle attività in background.

Nota

Le app in esecuzione in Android 10 (edizione Go) non possono ricevere l'autorizzazione SYSTEM_ALERT_WINDOW . Vedere l'articolo sulle SYSTEM_ALERT_WINDOW nei dispositivi Go.

Nota

A partire da Android 11, ACTION_MANAGE_OVERLAY_PERMISSION le finalità portano sempre l'utente alla schermata Impostazioni di primo livello, in cui l'utente può concedere o revocare le autorizzazioni per le SYSTEM_ALERT_WINDOW app. Vedere l'articolo sugli aggiornamenti delle autorizzazioni in Android 11.

Rimuovere gli aggiornamenti in-app per le compilazioni di Google Play

Google Play considera il codice di aggiornamento in-app come un comportamento dannoso anche se non viene usato in fase di esecuzione. Rimuovere questo codice prima di inviare l'app a Google Play. La mancata rimozione del codice di aggiornamento in-app può causare la mancata conformità e la rimozione dell'app da Google Play. Per rimuovere il codice nativo degli aggiornamenti in-app, deselezionare la casella di controllo Usa distribuzione nella sezione Distribuisci nell'oggetto gioco con AppCenterBehavior collegato.

Usare un gruppo di distribuzione privato

Per impostazione predefinita, Distribute usa un gruppo di distribuzione pubblico. Se si vuole usare un gruppo di distribuzione privato, è necessario passare UpdateTrack a Privato. A tale scopo, scegliere Privato nell'elenco a discesa Aggiorna traccia in Distribuisci sezione dell'oggetto gioco con AppCenterBehavior associato.

Quando si usa la traccia privata, verrà aperta una finestra del browser per autenticare l'utente. Tutti i controlli di aggiornamento successivi otterranno la versione più recente sulla traccia privata.

Se un utente è sulla traccia privata, significa che dopo l'autenticazione completata, otterrà la versione più recente da qualsiasi gruppo di distribuzione privato di cui è membro. Se un utente è sulla traccia pubblica, significa che otterrà la versione più recente da qualsiasi gruppo di distribuzione pubblico.

Disabilitare il controllo automatico per l'aggiornamento

Per impostazione predefinita, l'SDK verifica automaticamente la presenza di nuove versioni:

  • All'avvio dell'applicazione.
  • Quando l'applicazione entra in background, in primo piano.
  • Quando si abilita il modulo Distribuisci se in precedenza è disabilitato.

Se si vuole verificare manualmente la disponibilità di nuove versioni, è possibile disabilitare il controllo automatico per l'aggiornamento.

A tale scopo, deselezionare la casella di controllo Controllo automatico per l'aggiornamento nella sezione Distribuisci nell'oggetto gioco con AppCenterBehavior collegato.

È quindi possibile usare l'API CheckForUpdate descritta nella sezione seguente.

Controllare manualmente la disponibilità di aggiornamenti

Distribute.CheckForUpdate();

In questo modo viene inviata una richiesta ad App Center e viene visualizzata una finestra di dialogo di aggiornamento nel caso in cui sia disponibile una nuova versione.

Nota

Un controllo manuale della chiamata di aggiornamento funziona anche quando sono abilitati gli aggiornamenti automatici. Un controllo manuale per l'aggiornamento viene ignorato se è già in corso un altro controllo. Il controllo manuale per l'aggiornamento non verrà elaborato se l'utente ha posticipato gli aggiornamenti (a meno che la versione più recente non sia un aggiornamento obbligatorio).

Personalizzare o localizzare la finestra di dialogo di aggiornamento in-app

1. Personalizzare o localizzare il testo

È possibile specificare stringhe di risorse personalizzate se si vuole localizzare il testo visualizzato nella finestra di dialogo di aggiornamento. Esaminare i file stringa per iOS in questo file di risorse iOS e per Android in questo file di risorse Android. Usare la stessa stringa nome/chiave e specificare il valore localizzato da riflettere nella finestra di dialogo nei propri file di risorse dell'app.

2. Personalizzare la finestra di dialogo di aggiornamento

È possibile personalizzare l'aspetto della finestra di dialogo di aggiornamento predefinita implementando il ReleaseAvailable callback.

Avviso

È necessario registrare il callback nel Awake metodo di un MonoBehaviour oggetto nella prima scena caricata dall'applicazione per evitare la mancanza di chiamate di callback di rilascio.

// In this example, OnReleaseAvailable is a method name in same class
Distribute.ReleaseAvailable = OnReleaseAvailable;

Ecco un'implementazione di callback che sostituisce la finestra di dialogo SDK con logica personalizzata:

bool OnReleaseAvailable(ReleaseDetails releaseDetails)
{
    // Look at releaseDetails public properties to get version information, release notes text or release notes URL
    string versionName = releaseDetails.ShortVersion;
    string versionCodeOrBuildNumber = releaseDetails.Version;
    string releaseNotes = releaseDetails.ReleaseNotes;
    Uri releaseNotesUrl = releaseDetails.ReleaseNotesUrl;

    // (Do something with the values if you want)

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        // Force user to update (you should probably show some custom UI here)
        Distribute.NotifyUpdateAction(UpdateAction.Update);
    }
    else
    {
        // Allow user to update or postpone (you should probably show some custom UI here)
        // "GetUserUpdateAction()" isn't part of the SDK; it just represents a way of getting user response.
        // This blocks the thread while awaiting the user's response! This example shouldn't be used literally
        UpdateAction updateAction = GetUserUpdateAction();
        Distribute.NotifyUpdateAction(updateAction);
    }
    // Return true if you're using your own UI to get user response, false otherwise
    return true;
}

Note sull'implementazione per Android:

Come illustrato nell'esempio, è necessario chiamare Distribute.NotifyUpdateAction(UpdateAction.UPDATE); o Distribute.NotifyUpdateAction(UpdateAction.POSTPONE); se il callback restituisce true.

Se non si chiama NotifyUpdateAction, il callback verrà ripetuto in ogni modifica dell'attività.

Il callback può essere chiamato di nuovo con la stessa versione se l'attività cambia prima che l'azione dell'utente venga notificata all'SDK.

Questo comportamento è necessario per coprire gli scenari seguenti:

  • L'applicazione viene inviata in background (ad esempio premendo HOME) e quindi ripresa in un'attività diversa.
  • L'attività è coperta da un'altra senza uscire dall'applicazione (ad esempio facendo clic su alcune notifiche).
  • Scenari simili ai precedenti.

In tal caso, l'attività che ospita il dialogo potrebbe essere sostituita senza l'interazione dell'utente. L'SDK chiama di nuovo il listener in modo da poter ripristinare la finestra di dialogo personalizzata.

3. Eseguire il codice se non vengono trovati aggiornamenti

Nei casi in cui l'SDK controlla la disponibilità di aggiornamenti e non trova aggiornamenti disponibili più recenti di quelli attualmente usati, viene richiamato un NoReleaseAvailable callback. In questo modo è possibile eseguire codice personalizzato in tali scenari. È necessario registrare il callback prima di chiamare AppCenter.Start come illustrato nell'esempio seguente:

// In this example OnNoReleaseAvailable is a method name in same class
Distribute.NoReleaseAvailable = OnNoReleaseAvailable;
AppCenter.Start(...);

void OnNoReleaseAvailable()
{
    AppCenterLog.Info(LogTag, "No release available callback invoked.");
}

## Enable or disable App Center Distribute at runtime

You can enable and disable App Center Distribute at runtime. If you disable it, the SDK won't provide any in-app update functionality but you can still use the Distribute service in the App Center portal.

To disable the Distribute service, use the following code:

```csharp
Distribute.SetEnabledAsync(false);

Per abilitare di nuovo App Center Distribute, usare la stessa API ma passare true come parametro.

Distribute.SetEnabledAsync(true);

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Non è necessario attendere questa chiamata per rendere coerenti altre chiamate API ( ad esempio IsEnabledAsync).

Lo stato viene salvato in modo permanente nella risorsa di archiviazione del dispositivo tra i lanci dell'applicazione.

Controllare se App Center Distribute è abilitato

È anche possibile controllare se App Center Distribute è abilitato:

Distribute.IsEnabledAsync();

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Abilitare gli aggiornamenti in-app per le compilazioni di debug

Per impostazione predefinita, gli aggiornamenti in-app sono abilitati solo per le build di versione.

Per abilitare gli aggiornamenti in-app per le build di debug in Android e iOS, selezionare la casella di controllo Abilita distribuzione in debug nella sezione Distribuisci nell'oggetto gioco con AppCenterBehavior collegato.

Comportamento di App Center

In Unity, una compilazione debugbile è una compilazione con un'opzione di compilazione sviluppo selezionata.

Eseguire la pulizia subito prima della chiusura dell'app per l'aggiornamento

Nota

Questo callback funziona solo in iOS.

Registrare il callback come illustrato nell'esempio seguente:

// In this example, OnWillExitApp is a method name in same class
Distribute.WillExitApp = OnWillExitApp;

void OnWillExitApp()
{
    // Perform clean up here
}

A questo scopo, OnWillExitApp() verrà richiamato quando Distribute sta per chiudersi.

Funzionamento degli aggiornamenti in-app

Nota

Per il funzionamento degli aggiornamenti in-app, è necessario scaricare una compilazione dell'app dal collegamento. Non funzionerà se installato da un IDE o manualmente.

La funzionalità aggiornamenti in-app funziona come segue:

  1. Questa funzionalità funziona solo con le build RELEASE (per impostazione predefinita) distribuite con il servizio App Center Distribute . Non funzionerà se la funzionalità accesso guidato iOS è attivata.
  2. Dopo aver integrato l'SDK, compilare una versione di rilascio dell'app e caricarla in App Center. Gli utenti del gruppo di distribuzione ricevono una notifica sulla nuova versione tramite posta elettronica.
  3. Quando ogni utente apre il collegamento nel messaggio di posta elettronica, l'applicazione verrà installata nel dispositivo. È importante che usino il collegamento di posta elettronica per l'installazione. Non è supportato il sideload. Quando un'applicazione viene scaricata dal collegamento, l'SDK salva informazioni importanti dai cookie per verificare la disponibilità di aggiornamenti in un secondo momento, altrimenti l'SDK non dispone di tali informazioni chiave.
  4. Se l'applicazione imposta la traccia su privata, verrà aperto un browser per autenticare l'utente e abilitare gli aggiornamenti in-app. Il browser non si riaprirà finché le informazioni di autenticazione rimangono valide anche quando si torna alla traccia pubblica e si torna nuovamente a privato in un secondo momento. Se l'autenticazione del browser ha esito positivo, l'utente viene reindirizzato automaticamente all'applicazione. Se la traccia è pubblica (ovvero l'impostazione predefinita), il passaggio successivo viene eseguito direttamente.
  5. Una nuova versione dell'app mostra la finestra di dialogo di aggiornamento in-app che chiede agli utenti di aggiornare l'applicazione se è:
    • iOS:
      • un valore superiore di CFBundleShortVersionString o
      • un valore uguale di CFBundleShortVersionString ma un valore superiore di CFBundleVersion.
      • le versioni sono uguali, ma l'identificatore univoco della compilazione è diverso.
    • Android:
      • un valore superiore di versionCode o
      • un valore uguale a versionCode ma un valore diverso di versionName.

Suggerimento

Se si carica lo stesso .apk/.ipa una seconda volta, la finestra di dialogo non verrà visualizzata come i file binari sono identici. In iOS, se si carica una nuova build con le stesse proprietà della versione, verrà visualizzata la finestra di dialogo di aggiornamento. Il motivo è che si tratta di un file binario diverso. In Android i file binari vengono considerati uguali se entrambe le proprietà della versione sono uguali.

Ricerca per categorie testare gli aggiornamenti in-app?

È necessario caricare le build di versione (che usano il modulo Distribuisci di App Center SDK) nel portale di App Center per testare gli aggiornamenti in-app, aumentando i numeri di versione ogni volta.

  1. Creare l'app nel portale di App Center, se non è già stato fatto.
  2. Creare un nuovo gruppo di distribuzione e assegnargli un nome.
  3. Aggiungi te stesso (o tutte le persone che vuoi includere nel test della funzionalità di aggiornamento in-app). Usa un indirizzo di posta elettronica nuovo o eliminato per questo passaggio, non già usato con questa app. Ciò garantisce che l'esperienza sia vicina all'esperienza dei tester reali.
  4. Creare una nuova build dell'app che include App Center Distribute e contiene la logica di configurazione, come descritto di seguito. Se il gruppo è privato, non dimenticare di impostare la traccia di aggiornamento in-app privata prima di iniziare a usare la UpdateTrack proprietà .
  5. Fare clic sul pulsante Distribuisci nuova versione nel portale e caricare la compilazione dell'app.
  6. Al termine del caricamento, fare clic su Avanti e selezionare il gruppo di distribuzione creato in precedenza come Destinazione della distribuzione dell'app.
  7. Esaminare la distribuzione e distribuire la compilazione nel gruppo di test in-app.
  8. Persone in tale gruppo riceverà un invito a essere tester dell'app. Dopo aver accettato l'invito, può scaricare l'app dal portale di App Center dal dispositivo mobile. Dopo aver installato gli aggiornamenti in-app, si è pronti per testare gli aggiornamenti in-app.
  9. Aggiornare la versione dell'app (CFBundleShortVersionString o CFBundleVersion per iOS, versionCode per Android).
  10. Compilare la versione di rilascio dell'app e caricare una nuova build come nel passaggio precedente. Eseguire la distribuzione al gruppo di distribuzione creato in precedenza. I membri del gruppo di distribuzione verranno richiesti per una nuova versione alla successiva avvio dell'app.

Suggerimento

Per informazioni più dettagliate sui gruppi di distribuzione e così via, vedere le informazioni su come usare App Center Distribute. Anche se è possibile usare App Center Distribute per distribuire una nuova versione dell'app senza aggiungere codice, l'aggiunta di App Center Distribute al codice dell'app comporterà un'esperienza più semplice per i tester e gli utenti man mano che ottengono l'esperienza di aggiornamento in-app.