Condividi tramite

App Center Distribute : aggiornamenti in-app Android

  • 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.

App Center Distribute consentirà agli utenti di installare una nuova versione dell'app quando la distribuisci tramite App Center. Con una nuova versione dell'app disponibile, l'SDK presenterà una finestra di dialogo di aggiornamento per gli utenti per scaricare o posticipare la nuova versione. Dopo aver scelto di eseguire l'aggiornamento, l'SDK inizierà ad aggiornare l'applicazione.

Avviso

Google Play considera il codice di aggiornamento in-app come un comportamento dannoso anche se non viene usato in fase di esecuzione. Usare una variante di Distribute SDK come indicato in questa sezione o rimuovere completamente l'SDK di distribuzione che contiene il codice di aggiornamento in-app prima di inviare l'app a Google Play. In caso contrario, 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 non abilitare App Center Distribute per i test dell'interfaccia utente.

Aggiungere aggiornamenti in-app all'app

Se non è ancora stato configurato e avviato l'SDK nell'applicazione, seguire la sezione Introduzione .

1. 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.

  1. Aprire il file build.gradle a livello di app del progetto (app/build.gradle) e aggiungere le righe seguenti dopo apply plugin.

    dependencies {
   def appCenterSdkVersion = '5.0.4'
   implementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
}

    Nota

    Se la versione del plug-in Android Gradle è inferiore alla 3.0.0, è necessario sostituire l'implementazione con la compilazione.

  2. Salvare il file build.gradle e assicurarsi di attivare una sincronizzazione Gradle in Android Studio.

  3. DownloadManager viene usato per scaricare gli aggiornamenti. App Center SDK impone TLS 1.2 per migliorare la sicurezza.

2. Avviare App Center Distribute

Per usare App Center, acconsentire esplicitamente ai moduli da usare. Per impostazione predefinita, non vengono avviati moduli ed è necessario chiamarli in modo esplicito all'avvio dell'SDK.

Aggiungere la classe Distribute al AppCenter.start() metodo per avviare il servizio App Center Distribute.

AppCenter.start(getApplication(), "{Your App Secret}", Distribute.class);

AppCenter.start(application, "{Your App Secret}", Distribute::class.java)

Assicurarsi di aver sostituito {Your App Secret} nell'esempio di codice precedente con il segreto dell'app. Android Studio suggerisce automaticamente l'istruzione import necessaria dopo aver aggiunto un riferimento alla classe al Distributestart() metodo , ma se viene visualizzato un errore che indica che i nomi delle classi non vengono riconosciuti, aggiungere le righe seguenti alle istruzioni import nella classe di attività:

import com.microsoft.appcenter.AppCenter;
import com.microsoft.appcenter.distribute.Distribute;

import com.microsoft.appcenter.AppCenter
import com.microsoft.appcenter.distribute.Distribute

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.

Preparare la compilazione 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. Usare una variante di Distribute SDK come indicato in questa sezione o rimuovere completamente l'SDK di distribuzione che contiene il codice di aggiornamento in-app prima di inviare l'app a Google Play. In caso contrario, può causare la mancata conformità e la rimozione dell'app da Google Play. Per semplificare, forniamo la versione di App Center Distribute SDK con API stub, quindi l'unica modifica è uno scambio di dipendenze.

  1. Aprire il file build.gradle a livello di app del progetto (app/build.gradle).

  2. Configurare le varianti di compilazione aggiungendo versioni di prodotto:

    android {
    flavorDimensions "distribute"
    productFlavors {
        appCenter {
            dimension "distribute"
        }
        googlePlay {
            dimension "distribute"
        }
    }
}

  3. Modificare il blocco delle dipendenze per utilizzare dipendenze diverse in base al tipo di prodotto:

    dependencies {
    def appCenterSdkVersion = "5.0.4"
    appCenterImplementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
    googlePlayImplementation "com.microsoft.appcenter:appcenter-distribute-play:${appCenterSdkVersion}"
}

  4. Salvare il file build.gradle e assicurarsi di attivare una sincronizzazione Gradle in Android Studio.

  5. È possibile modificare la variante di compilazione nel menu a discesa Build > Select Build Variant (Compila variante) o Build Variants (Compila varianti ) nella barra delle finestre degli strumenti.

Per altre informazioni sulla configurazione delle varianti di compilazione, vedere la documentazione di Android.

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 impostarlo in modo esplicito tramite setUpdateTrack l'API.

Distribute.setUpdateTrack(UpdateTrack.PRIVATE);

Distribute.setUpdateTrack(UpdateTrack.PRIVATE)

Nota

Il valore predefinito è UpdateTrack.PUBLIC. Questo metodo può essere chiamato solo prima della chiamata al AppCenter.start metodo. Le modifiche apportate alla traccia di aggiornamento non vengono mantenute al riavvio del processo dell'applicazione e pertanto, se il metodo non viene sempre chiamato prima della AppCenter.start chiamata, sarà pubblico, per impostazione predefinita.

Quando l'app è in primo piano (dopo Distribute.setUpdateTrack(UpdateTrack.PRIVATE); e AppCenter.start), viene 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 primo piano dopo aver passato in background.
  • 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, chiamare il metodo seguente prima dell'avvio dell'SDK:

Distribute.disableAutomaticCheckForUpdate();

Distribute.disableAutomaticCheckForUpdate()

Nota

Questo metodo deve essere chiamato prima della chiamata al AppCenter.start metodo.

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

Controllare manualmente la disponibilità di aggiornamenti

Distribute.checkForUpdate();

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 facilmente stringhe di risorse personalizzate se si desidera modificare o localizzare il testo visualizzato nella finestra di dialogo di aggiornamento. Esaminare i file di stringa in questo file di risorse. 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 l'interfaccia DistributeListener . È necessario registrare il listener prima di chiamare AppCenter.start come illustrato nell'esempio seguente:

Distribute.setListener(new MyDistributeListener());
AppCenter.start(...);

Distribute.setListener(MyDistributeListener())
AppCenter.start(...)

Di seguito è riportato un esempio dell'implementazione del listener che sostituisce la finestra di dialogo SDK con una versione personalizzata:

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.net.Uri;

import com.microsoft.appcenter.distribute.Distribute;
import com.microsoft.appcenter.distribute.DistributeListener;
import com.microsoft.appcenter.distribute.ReleaseDetails;
import com.microsoft.appcenter.distribute.UpdateAction;

public class MyDistributeListener implements DistributeListener {

    @Override
    public boolean onReleaseAvailable(Activity activity, ReleaseDetails releaseDetails) {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        String versionName = releaseDetails.getShortVersion();
        int versionCode = releaseDetails.getVersion();
        String releaseNotes = releaseDetails.getReleaseNotes();
        Uri releaseNotesUrl = releaseDetails.getReleaseNotesUrl();

        // Build our own dialog title and message
        AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(activity);
        dialogBuilder.setTitle("Version " + versionName + " available!"); // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes);

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download, new DialogInterface.OnClickListener() {

            @Override
            public void onClick(DialogInterface dialog, int which) {

                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.UPDATE);
            }
        });

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate()) {
            dialogBuilder.setNegativeButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone, new DialogInterface.OnClickListener() {

                @Override
                public void onClick(DialogInterface dialog, int which) {

                    // This method is used to tell the SDK what button was clicked
                    Distribute.notifyUpdateAction(UpdateAction.POSTPONE);
                }
            });
        }
        dialogBuilder.setCancelable(false); // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show();

        // Return true if you're using your own dialog, false otherwise
        return true;
    }
    
    @Override
    public void onNoReleaseAvailable(Activity activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show();
    }
}

import android.app.Activity
import android.app.AlertDialog
import com.microsoft.appcenter.distribute.Distribute
import com.microsoft.appcenter.distribute.DistributeListener
import com.microsoft.appcenter.distribute.ReleaseDetails
import com.microsoft.appcenter.distribute.UpdateAction

class MyDistributeListener : DistributeListener {

    override fun onReleaseAvailable(activity: Activity, releaseDetails: ReleaseDetails): Boolean {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        val versionName = releaseDetails.shortVersion
        val versionCode = releaseDetails.version
        val releaseNotes = releaseDetails.releaseNotes
        val releaseNotesUrl = releaseDetails.releaseNotesUrl

        // Build our own dialog title and message
        val dialogBuilder = AlertDialog.Builder(activity)
        dialogBuilder.setTitle("Version $versionName available!") // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes)

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(
            com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download
        ) { dialog, which ->
            // This method is used to tell the SDK what button was clicked
            Distribute.notifyUpdateAction(UpdateAction.UPDATE)
        }

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate) {
            dialogBuilder.setNegativeButton(
                com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone
            ) { dialog, which ->
                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.POSTPONE)
            }
        }
        dialogBuilder.setCancelable(false) // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show()

        // Return true if you're using your own dialog, false otherwise
        return true
    }

    override fun onNoReleaseAvailable(activity: Activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show()
    }
}

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

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

Il listener 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).
  • Altri scenari simili.

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

Nei casi in cui l'SDK controlla gli aggiornamenti e non trova aggiornamenti disponibili più recenti di quello attualmente usato, viene richiamato un onNoReleaseAvailable callback dall'interfaccia DistributeListener . Ciò consente di eseguire codice personalizzato in tali scenari. L'esempio precedente mostra come visualizzare un messaggio di tipo avviso popup quando non vengono trovati aggiornamenti.

Abilitare o disabilitare App Center Distribute in fase di esecuzione

È possibile abilitare e disabilitare App Center Distribute in fase di esecuzione. Se la disabilita, l'SDK non fornirà alcuna funzionalità di aggiornamento in-app, ma è comunque possibile usare il servizio Distribute nel portale di App Center.

Distribute.setEnabled(false);

Distribute.setEnabled(false)

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

Distribute.setEnabled(true);

Distribute.setEnabled(true)

Lo stato viene mantenuto nello spazio di archiviazione del dispositivo tra i lanci dell'applicazione.

Questa API è asincrona, è possibile leggere altre informazioni sulla guida alle API asincrone di App Center .

Nota

Questo metodo deve essere usato solo dopo Distribute l'avvio.

Verificare se App Center Distribute è abilitato

È anche possibile verificare se App Center Distribute è abilitato o meno:

Distribute.isEnabled();

Distribute.isEnabled()

Questa API è asincrona, è possibile leggere altre informazioni sulla guida alle API asincrone di App Center .

Nota

Questo metodo deve essere usato solo dopo Distribute l'avvio, verrà sempre restituito false prima dell'avvio.

Abilitare gli aggiornamenti in-app per le compilazioni di debug

Per impostazione predefinita, App Center abilita gli aggiornamenti in-app solo per le build di versione.

Per abilitare gli aggiornamenti in-app nelle compilazioni di debug, chiamare il metodo seguente prima AppCenter.startdi :

Distribute.setEnabledForDebuggableBuild(true);

Distribute.setEnabledForDebuggableBuild(true)

Nota

Questo metodo influisce solo sulle build di debug e non ha alcun impatto sulle build di versione. La compilazione di debug indica che il android:debuggable flag è impostato su true (che viene in genere impostato automaticamente da gradle predefinite varianti di compilazione di debug). In caso contrario, si tratta di una build di versione.

Come funzionano gli aggiornamenti in-app?

Nota

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

La funzionalità aggiornamenti in-app funziona come indicato di seguito:

  1. Questa funzionalità funziona solo con le build RELEASE (per impostazione predefinita) distribuite usando il servizio Distribuzione di App Center .

  2. Dopo aver integrato l'SDK, compilare la versione della versione dell'app e caricare in App Center, gli utenti del gruppo di distribuzione riceveranno una notifica per la nuova versione tramite un messaggio di posta elettronica.

  3. Quando ogni utente apre il collegamento nel proprio messaggio di posta elettronica, l'applicazione verrà installata nel dispositivo. È importante che usino il collegamento di posta elettronica per installare: non supportiamo il caricamento laterale. Quando un'applicazione viene scaricata dal collegamento, l'SDK salva informazioni importanti dai cookie per verificare gli 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 verrà nuovamente aperto fino a quando le informazioni di autenticazione rimangono valide anche quando si torna alla traccia pubblica e torna nuovamente in 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 è:

    • valore superiore di versionCode o
    • valore uguale di versionCode ma un valore diverso di versionName.

Suggerimento

Se si carica lo stesso APK una seconda volta, la finestra di dialogo non verrà visualizzata come le versioni sono identiche.

Ricerca per categorie testare gli aggiornamenti in-app?

È necessario caricare le build di versione (che usano il modulo Distribute of the App Center SDK) al 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 assegnarne il nome, in modo da poter riconoscere che è destinato al test della funzionalità di aggiornamento in-app.
  3. Aggiungi te stesso (o tutte le persone che vuoi includere nel test della funzionalità di aggiornamento in-app). Usare un nuovo indirizzo di posta elettronica o eliminato per questo, che non è stato usato per l'app in App Center. Ciò garantisce che l'esperienza sia vicina all'esperienza dei tester reali.
  4. Creare una nuova compilazione dell'app che include App Center Distribute e contiene la logica di installazione come descritto in precedenza. Se il gruppo è privato, non dimenticare di impostare la traccia di aggiornamento privato in-app prima di iniziare a usare l'API setUpdateTrack.
  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 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, è possibile scaricare l'app dal portale di App Center dal dispositivo mobile. Dopo aver installato gli aggiornamenti in-app, è possibile testare gli aggiornamenti in-app.
  9. Urtare l'app versionCode .
  10. Compilare la versione dell'app e caricare una nuova compilazione dell'app come è stato fatto nel passaggio precedente e distribuirlo al gruppo di distribuzione creato in precedenza. I membri del gruppo di distribuzione verranno richiesti per una nuova versione al successivo avvio dell'app.

Suggerimento

Esaminare le informazioni su come usare App Center Distribute per informazioni più dettagliate sui gruppi di distribuzione e così via. 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.