Distribuzione di App Center: aggiornamenti di MAUI e Xamarin In-app

2025-05-05

Importante

Visual Studio App Center è stato ritirato il 31 marzo 2025, ad eccezione delle funzionalità di Analisi e diagnostica, che continueranno a essere supportate fino al 30 giugno 2026. Ulteriori informazioni.

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

Avvertimento

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

Annotazioni

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

Seguire la sezione Introduzione se non è ancora stato configurato e avviato l'SDK nell'applicazione.

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.

Visual Studio per Mac

Aprire Visual Studio per Mac.
Fare clic su FileOpen (Apri file>) e scegliere la soluzione.
Nello strumento di spostamento della soluzione fare clic con il pulsante destro del mouse sulla sezione Pacchetti e scegliere Aggiungi pacchetti NuGet.
Cercare App Center e installare App Center Distribute.
Fare clic su Aggiungi pacchetti.

Visual Studio per Windows

Aprire Visual Studio per Windows.
Fare clic su FileOpen (Apri file>) e scegliere la soluzione.
Nello strumento di spostamento della soluzione fare clic con il pulsante destro del mouse su Riferimenti e scegliere Gestisci pacchetti NuGet.
Cercare App Center e installare Microsoft.AppCenter.Distribute.

Console di gestione pacchetti

Aprire la console in Visual Studio. A tale scopo, scegliere Strumenti>Gestione pacchetti NuGet>Console di gestione pacchetti.
Se si usa Visual Studio per Mac, assicurarsi di aver installato le estensioni di gestione pacchetti NuGet. A tale scopo, scegliereEstensioni di Visual Studio>, cercare NuGet e installare, se necessario.
Digitare il comando seguente nella console:

Install-Package Microsoft.AppCenter.Distribute

Annotazioni

Se si usa App Center SDK in un progetto portabile (ad esempio Xamarin.Forms), è necessario installare i pacchetti in ognuno dei progetti: quelli portabili, Android e iOS. A tale scopo, è necessario aprire ogni sottoprogetto e seguire i passaggi corrispondenti descritti nelle sezioni di Visual Studio per Mac o Visual Studio per Windows .

Annotazioni

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.

Annotazioni

Le app in esecuzione in Android 10 (edizione Go) non possono ricevere l'autorizzazione SYSTEM_ALERT_WINDOW . Si prega di consultare l'articolo su SYSTEM_ALERT_WINDOW sui dispositivi Go.

Annotazioni

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

2. Avviare App Center Distribute

Configurare App Center SDK chiamando AppCenter.Start(...) come descritto nella Guida introduttiva.

Per l'applicazione iOS, aprire AppDelegate.cs e aggiungere la riga seguente prima della chiamata a LoadApplication:

Distribute.DontCheckForUpdatesInDebug();

Questo passaggio non è necessario in Android in cui la configurazione di debug viene rilevata automaticamente in fase di esecuzione.

Per abilitare gli aggiornamenti in-app per le build di debug su Android, chiamare il metodo seguente nel metodo OnCreate, nel file MainActivity.cs del progetto, e prima di LoadApplication.

Distribute.SetEnabledForDebuggableBuild(true);

Annotazioni

Questo metodo influisce solo sulle compilazioni di debug e non ha alcun impatto sulle build di versione.

2.3 [Solo per iOS] Modificare il file Info.plist del progetto

App Center SDK controlla gli URL che reindirizzano all'applicazione per evitare download non autorizzati, quindi per consentire la corretta gestione degli aggiornamenti distribuiti tramite il portale, è necessario specificare CFBundleURLSchemes nella CFBundleURLTypes sezione nel Info.plist file:

Annotazioni

Info.plisto un file dell'elenco di proprietà delle informazioni è un file di testo strutturato che contiene informazioni di configurazione essenziali per un eseguibile in bundle. Altre informazioni sono disponibili nella documentazione per sviluppatori Apple.

Aggiungere una nuova chiave per URL types o CFBundleURLTypes nel file Info.plist (nel caso in cui Xcode visualizzi Info.plist come codice sorgente).
Modificare la chiave del primo elemento figlio in URL Schemes o CFBundleURLSchemes.
Immettere appcenter-${APP_SECRET} come schema URL e sostituire ${APP_SECRET} con il segreto dell'app della tua app.

Suggerimento

Per verificare che info.plist sia stato modificato correttamente, aprirlo come codice sorgente. Deve contenere la voce seguente con il segreto dell'app invece di ${APP_SECRET}:

<key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>appcenter-${APP_SECRET}</string>
          </array>
      </dict>
  </array>

Eliminare gli aggiornamenti in-app per le versioni 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. La mancata rimozione del codice di aggiornamento in-app può causare la mancata conformità e la rimozione dell'app da Google Play. Per semplificare l'operazione, forniamo la versione di App Center Distribute SDK con API stub, quindi l'unica modifica è uno scambio di dipendenze.

Aggiungere una nuova configurazione di compilazione denominata GooglePlay per i progetti Xamarin.Android e condivisi. Assicurarsi che la configurazione della compilazione dei progetti sia mappata correttamente alla configurazione della soluzione appropriata. Per altri dettagli, vedere Le istruzioni di Visual Studio o Visual Studio per Mac .
Aprire Xamarin.Android e i progetti .csproj condivisi in qualsiasi editor di testo e spostare i riferimenti distribuiti nel gruppo di elementi condizionali:
```
<ItemGroup Condition=" '$(Configuration)' != 'GooglePlay' ">
    <PackageReference Include="Microsoft.AppCenter.Distribute" Version="3.3.0" />
</ItemGroup>
<ItemGroup Condition=" '$(Configuration)' == 'GooglePlay' ">
    <PackageReference Include="Microsoft.AppCenter.DistributePlay" Version="3.3.0" />
</ItemGroup>
```
Annotazioni

Se si usa un formato dipackages.config precedente per gestire i riferimenti NuGet, è possibile eseguire la migrazione a un formato PackageReference , seguire l'istruzione di migrazione.
Salvare le modifiche e ripristinare i pacchetti NuGet.
È possibile modificare la configurazione nella barra dei comandi nella parte superiore dell'IDE.

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 UpdateTrack la proprietà .

Distribute.UpdateTrack = UpdateTrack.Private;

Annotazioni

Il valore predefinito è UpdateTrack.Public. Questa proprietà può essere aggiornata 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 la proprietà non viene sempre aggiornata prima della AppCenter.Start chiamata, sarà pubblica, per impostazione predefinita.

Dopo questa chiamata, verrà aperta una finestra del browser per autenticare l'utente. Tutti i controlli di aggiornamento successivi otterranno la versione più recente sulla traccia privata. La traccia di aggiornamento non viene salvata in modo permanente nell'SDK tra gli avvii dell'app.

Se un utente è sulla traccia privata, significa che dopo l'autenticazione completata, otterrà la versione più recente da tutti i gruppi di distribuzione privati 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 e ritorna in primo piano.
Quando si abilita il modulo Distribuisci se in precedenza è disabilitato.

Se si vuole verificare manualmente la presenza 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();

Annotazioni

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();

Annotazioni

Un controllo manuale della chiamata di aggiornamento funziona anche quando gli aggiornamenti automatici sono abilitati. 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 vuole localizzare il testo visualizzato nella finestra di dialogo di aggiornamento. Osserva i file delle stringhe per iOS in questo file di risorse e quelli per Android in questo file di risorse. Usare la stessa stringa nome/chiave e specificare il valore localizzato da riflettere nella finestra di dialogo nei file di risorse dell'app.

2. Personalizzare la finestra di dialogo di aggiornamento

È possibile personalizzare l'aspetto della finestra di dialogo di aggiornamento predefinito implementando il ReleaseAvailable callback. È necessario registrare il callback prima di chiamare AppCenter.Start come illustrato nell'esempio seguente:

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

Di seguito è riportato un esempio dell'implementazione del callback che sostituisce la finestra di dialogo sdk con una 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;

    // custom dialog
    var title = "Version " + versionName + " available!";
    Task answer;

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install");
    }
    else
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install", "Maybe tomorrow...");
    }
    answer.ContinueWith((task) =>
    {
        // If mandatory or if answer was positive
        if (releaseDetails.MandatoryUpdate || (task as Task<bool>).Result)
        {
            // Notify SDK that user selected update
            Distribute.NotifyUpdateAction(UpdateAction.Update);
        }
        else
        {
            // Notify SDK that user selected postpone (for 1 day)
            // This method call is ignored by the SDK if the update is mandatory
            Distribute.NotifyUpdateAction(UpdateAction.Postpone);
        }
    });

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

Note sull'implementazione per Xamarin.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 ogni volta che c'è un cambiamento nell'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, 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 il dialogo potrebbe essere sostituita senza l'interazione dell'utente. L'SDK chiama di nuovo il listener in modo che sia possibile 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.");
}

Abilitare o disabilitare App Center Distribute in fase di esecuzione

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

Distribute.SetEnabledAsync(false);

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

Distribute.SetEnabledAsync(true);

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 all'avvio dell'applicazione.

Annotazioni

Questo metodo deve essere utilizzato solo dopo l'avvio di Distribute.

Controllare se App Center Distribute è abilitato

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

bool enabled = await Distribute.IsEnabledAsync();

Annotazioni

Questo metodo deve essere usato solo dopo che Distribute è stato avviato; restituirà sempre false prima dell'avvio.

Eseguire la pulizia subito prima della chiusura dell'app per l'aggiornamento (solo 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
}

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

Come funzionano gli aggiornamenti in-app?

Annotazioni

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à di aggiornamento in-app funziona nel modo seguente:

Questa funzionalità funziona solo con le build RELEASE (per impostazione predefinita) distribuite con il servizio App Center Distribute . Non funzionerà se la funzionalità di accesso guidato iOS è attivata.
Dopo aver integrato l'SDK, compilare la versione di rilascio dell'app e caricarla in App Center, gli utenti del gruppo di distribuzione riceveranno una notifica per la nuova versione tramite un messaggio di posta elettronica.
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.
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 aprirà di nuovo finché le informazioni di autenticazione rimangono valide anche quando si torna alla traccia pubblica e si torna nuovamente privati 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 avviene direttamente.
- In iOS 9 e 10, un'istanza di SFSafariViewController verrà aperta all'interno dell'app per autenticare l'utente. Si chiude automaticamente dopo l'esito positivo dell'autenticazione.
- In iOS 11 l'esperienza utente è simile a iOS 10, ma iOS 11 chiederà all'utente l'autorizzazione per accedere alle informazioni di accesso. Questa è una finestra di dialogo a livello di sistema e non può essere personalizzata. Se l'utente annulla la finestra di dialogo, può continuare a usare la versione che sta testando, ma non riceverà gli aggiornamenti in-app. Verrà chiesto di accedere di nuovo alle informazioni di accesso quando avviano l'app la volta successiva.
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.
- Androide:
  - un valore superiore di versionCode o
  - un valore uguale di 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 poiché 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.

Come si testano gli aggiornamenti in-app?

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

Creare l'app nel portale di App Center, se non è già stato fatto.
Creare un nuovo gruppo di distribuzione e denominarlo, in modo da poterlo riconoscere per testare la funzionalità di aggiornamento in-app.
Aggiungi te stesso (o tutte le persone che vuoi includere nel test della funzionalità di aggiornamento in-app). Usa un indirizzo email nuovo o usa un indirizzo email temporaneo per questo, che non è stato utilizzato per quell'app su App Center. Ciò garantisce che l'esperienza sia vicina all'esperienza dei tester reali.
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à .
Fare clic sul pulsante Distribuisci nuova versione nel portale e caricare la compilazione dell'app.
Al termine del caricamento, fare clic su Avanti e selezionare il gruppo di distribuzione creato come Destinazione della distribuzione dell'app.
Esamina la distribuzione e distribuisci il build al gruppo di test in-app.
Gli utenti del gruppo riceveranno 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.
Aggiornare la versione dell'app (CFBundleShortVersionString o CFBundleVersion per iOS versionCode , per Android)
Compilare la versione di rilascio dell'app e caricare una nuova build dell'app come nel passaggio precedente e distribuirla al gruppo di distribuzione creato in precedenza. Ai membri del gruppo di distribuzione verrà richiesta una nuova versione al successivo 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.

Disabilitare l'inoltro automatico dei metodi del delegato dell'applicazione ai servizi di App Center

App Center utilizza lo swizzling per inoltrare automaticamente i metodi del delegate dell'applicazione ai servizi di App Center per migliorare l'integrazione con l'SDK. Esiste una possibilità di conflitti con altre librerie di terze parti o con il delegato dell'applicazione stesso. In questo caso, è possibile disabilitare l'inoltro del delegato dell'applicazione App Center per tutti i servizi di App Center seguendo questa procedura:

Aprire il file Info.plist del progetto.
Aggiungere la chiave AppCenterAppDelegateForwarderEnabled e impostare il valore su 0. In questo modo viene disabilitato l'inoltro del delegato dell'applicazione per tutti i servizi di App Center.
Aggiungere callback OpenUrl nel file AppDelegate.cs.

public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}

Condividi tramite

Distribuzione di App Center: aggiornamenti di MAUI e Xamarin In-app

Aggiungere aggiornamenti in-app all'app

1. Aggiungere il modulo App Center Distribute

Visual Studio per Mac

Visual Studio per Windows

Console di gestione pacchetti

2. Avviare App Center Distribute

2.3 [Solo per iOS] Modificare il file Info.plist del progetto

Eliminare gli aggiornamenti in-app per le versioni di Google Play

Usare un gruppo di distribuzione privato

Disabilitare il controllo automatico per l'aggiornamento

Controllare manualmente la disponibilità di aggiornamenti

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

1. Personalizzare o localizzare il testo

2. Personalizzare la finestra di dialogo di aggiornamento

3. Eseguire il codice se non vengono trovati aggiornamenti

Abilitare o disabilitare App Center Distribute in fase di esecuzione

Controllare se App Center Distribute è abilitato

Eseguire la pulizia subito prima della chiusura dell'app per l'aggiornamento (solo iOS)

Come funzionano gli aggiornamenti in-app?

Come si testano gli aggiornamenti in-app?

Disabilitare l'inoltro automatico dei metodi del delegato dell'applicazione ai servizi di App Center

Commenti e suggerimenti

Risorse aggiuntive