Migrazione da Dynamic Links a App Links e Link universali

Questa guida alla migrazione si concentra sull'utilizzo di link app e link universali, eventualmente utilizzando Firebase Hosting per ospitare i file di associazione app-sito.

Questa migrazione sostituisce le seguenti funzionalità di Firebase Dynamic Links:

Funzionalità	Firebase Dynamic Links	Link app / link universali
Indirizzare gli utenti allo store corretto per il loro dispositivo con un solo clic sul link		^★
Offrire agli utenti la possibilità di continuare il percorso dopo aver scaricato e installato la tua app utilizzando un link diretto differito		^★
Offrire agli utenti un'esperienza contestuale utilizzando contenuti con link diretti nella tua app (se già installata)
Fornire dati di analisi relativi agli eventi di clic sui link dinamici
Offrire la possibilità di creare URL di link brevi

Nota: i banner delle app intelligenti su iOS forniscono un mezzo alternativo per mostrare un banner cliccabile che indirizza gli utenti all'App Store se la tua app non è installata o alla tua app se è già installata.

I banner di app intelligenti offrono anche la possibilità di passare parametri dopo che un utente fa clic sul link del banner di app intelligente, offrendo potenzialmente un modo per consentire agli utenti di continuare il loro percorso quando passano alla tua app facendo clic sul banner di app intelligente.

Se hai ancora bisogno di altre funzionalità di Firebase Dynamic Link per la migrazione che non sono supportate in questa guida, consulta gli altri scenari di migrazione nella documentazione relativa alle domande frequenti sul ritiro dei link dinamici.

Supponiamo di avere un link dinamico Firebase simile al seguente:

Esempio di link dinamico
Nome del link	Ti diamo il benvenuto su Example.com
Link diretto	https://example.web.app/welcome
App per Android	com.example.android
App Apple	com.example.ios
Link dinamico esteso	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinamico breve	https://example.page.link/m9Mm

Lo scopo di questa guida alla migrazione è sostituire Firebase Dynamic Links nel seguente modo:

https://example.page.link/m9Mm

Con link diretti di App Link / link universali che hanno il seguente aspetto:

https://your-project-domain.web.app/welcome

Tieni presente che il link diretto del link app / link universale fornirà ai tuoi utenti quanto segue:

• Un link diretto su cui possono fare clic per aprire la tua app se è già installata
• Una continuazione del percorso dell'utente che lo indirizza a una parte specifica della tua app quando viene aperta

Tuttavia, il link diretto del link app / link universale non fornirà ai tuoi utenti i seguenti comportamenti (come accadeva in precedenza con i link dinamici Firebase):

• Indirizzare gli utenti allo store corretto per il loro dispositivo per scaricare e installare la tua app
• Offrire un'esperienza utente continua dopo il download, l'installazione e l'apertura dell'app per la prima volta

Tieni presente le differenze di comportamento e funzionalità di questi link alle app / link universali rispetto ai link dinamici di Firebase indicati nella tabella sopra.

Prima di iniziare

Firebase Dynamic Links utilizza i link app (su Android) e i link universali (su iOS) nella propria implementazione di base per fornire funzionalità di link diretti dopo che l'app è già installata.

Questa guida illustra come creare i tuoi link di app e link universali utilizzando Firebase Hosting per sostituire la parte di funzionalità fornita da Firebase Dynamic Links durante la migrazione dei tuoi Firebase Dynamic Links alla nuova soluzione di migrazione di App Links / Universal Links.

Per completare la migrazione, ti serviranno le seguenti informazioni:

• I link dinamici Firebase di cui vuoi eseguire la migrazione
• I parametri URL dei link diretti inclusi nei link dinamici
• Il dominio che intendi utilizzare per sostituire il dominio Firebase Dynamic Links precedente (se applicabile)

Puoi utilizzare la guida all'esportazione dei metadati dei link dinamici per esportare i metadati dei link esistenti e ottenere le informazioni elencate sopra.

Panoramica dei passaggi di migrazione

1. Esegui il provisioning di un nuovo dominio (se non ne hai già uno da utilizzare) per ospitare i file di configurazione di App Link / Link universali utilizzando Firebase Hosting.

2. Crea e ospita i file di configurazione di Link app / Link universale sul tuo dominio di hosting.

3. Crea nuovi link alle app / link universali corrispondenti allo schema dei link diretti utilizzato nei tuoi link dinamici Firebase.

4. Aggiorna le app Android / iOS e il codice dell'applicazione per ricevere i link diretti.

5. Testare le integrazioni di App Links / Universal Links.

6. Sostituisci i link dinamici Firebase pubblicati o condivisi con i link app e i link universali.

Il primo passaggio sarà comune sia ai flussi di migrazione dei link alle app sia a quelli dei link universali. Il resto della procedura varia a seconda della piattaforma, quindi vai alla sezione della guida di seguito in base alla piattaforma di cui vuoi eseguire prima la migrazione.

• Passaggi per la migrazione dei link per app Android
• Passaggi per la migrazione dei link universali su iOS

Esegui il provisioning di un nuovo dominio per ospitare i file di configurazione di App Link / Link universali utilizzando Firebase Hosting

Scegli un dominio

Il primo passaggio consiste nel scegliere un dominio da utilizzare per i link alle app/ Universal Link. Questo sarà il dominio che verrà utilizzato per i nuovi link che condividerai con i tuoi utenti.

Se utilizzi Firebase Hosting, viene eseguito automaticamente il provisioning dei sottodomini del progetto con il formato your-project-domain.web.app o your-project-domain.firebaseapp.com senza costi. Se vuoi, puoi utilizzare un dominio personalizzato con o senza Firebase Hosting per ospitare anche i file di configurazione di App Link / Link universali.

Configura Firebase Hosting

Successivamente, dovrai configurare l'istanza Firebase Hosting.

Al termine della configurazione dell'istanza Firebase Hosting, avrai un dominio simile a your-project-domain.web.app o un dominio personalizzato se preferisci.

Passaggi per la migrazione di Link per app Android

Crea e ospita i file di configurazione di App Link sul nuovo dominio di hosting

Per utilizzare App Link, devi ospitare un file di configurazione che aiuti a stabilire un'associazione sicura tra il dominio utilizzato nei link e la tua app. Per App Link, si tratta del file assetlinks.json.

Procedura per creare e ospitare il file assetlinks.json

Il file assetlinks.json ci consente di fornire un elenco di app autorizzate che possono gestire i contenuti del dominio web che utilizzeremo per i nostri link alle app. Il file assetlinks.json deve essere ospitato nella directory principale del dominio web nel percorso: /.well-known.

Per completare questa configurazione, segui i passaggi riportati di seguito:

1. Crea la cartella .well-known nella cartella public della directory principale di Firebase Hosting.

2. Crea un file denominato assetlinks.json nella cartella .well-known.

3. Copia i seguenti contenuti nel file assetlinks.json, tenendo presente il significato di ciascun campo riportato di seguito:

   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.example.android",
       "sha256_cert_fingerprints":
         ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
     }
   }]
   

   • namespace: si riferisce al nome dell'applicazione che vuoi fornire
   • package_name: si riferisce all'applicationId dichiarato nel file build.gradle dell'app
   • sha256_cert_fingerprints: si riferisce all'impronta SHA256 del file del keystore utilizzato per la firma dell'applicazione.

   Puoi utilizzare il file debug.keystore utilizzato da Android Studio per generare un record sha256_cert_fingerprints a scopo di debug. Puoi trovare il file all'indirizzo /Users/<username>/.android/debug.keystore su Mac e Linux e C:\Users\<username>\.android\debug.keystore su Windows.

   Da questo keystore, puoi recuperare il valore SHA256 utilizzando keytool.

   Per ulteriori istruzioni su come completare questo passaggio, consulta questa sezione della documentazione di App Links.

   In alternativa, puoi anche utilizzare l'Assistente Link per app in Android Studio per generare i contenuti del file assetlinks.json e configurare la tua applicazione per gestire i link per app.

4. Aggiorna il file firebase.json per indicizzare il file per l'hosting.

   "headers": [
     {
       "source": "/.well-known/assetlinks.json",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. Ora che abbiamo il file assetlinks.json, esegui firebase deploy per ospitare le modifiche.

   Tieni presente che per eseguire il comando di deployment riportato sopra devi avere installato l'interfaccia a riga di comando di Firebase.

   firebase deploy --only hosting
   

6. Verifica il file assetlinks.json andando a https://your-project-domain.web.app/.well-known/assetlinks.json

Crea nuovi link di app corrispondenti allo schema dei link diretti utilizzato nei tuoi link dinamici Firebase

In questo passaggio, ricrei i link diretti dai tuoi link dinamici Firebase utilizzando URL di link diretti regolari corrispondenti al nuovo dominio che hai creato per i tuoi link di app.

Ad esempio, supponiamo di avere il seguente link dinamico Firebase:

Esempio di link dinamico
Nome del link	Ti diamo il benvenuto su Example.com
Link diretto	https://example.web.app/welcome
App per Android	com.example.android
App Apple	com.example.ios
Link dinamico esteso	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinamico breve	https://example.page.link/m9Mm

In questo caso, estrai il parametro del link diretto, ad esempio https://example.web.app/welcome, e utilizzalo come parametro Link app per la tua app.

Nota: quando hai creato per la prima volta Firebase Dynamic Link, potresti aver creato un parametro di link diretto che utilizza un dominio di cui non sei proprietario (ad es. example.com/welcome). Firebase Dynamic Links supportava questa funzionalità, ma in questa migrazione tutti i link profondi che prevedi di utilizzare devono essere modificati in modo da utilizzare il dominio di tua proprietà e configurato in precedenza con Firebase Hosting. Se hai già utilizzato un dominio di tua proprietà per i parametri URL dei link diretti utilizzati nei tuoi link dinamici Firebase, potresti risparmiare molto tempo e la tua app potrebbe essere già configurata per gestire i link dell'app in entrata che dovrai creare.

Ti consigliamo di ripetere questa procedura per ogni link dinamico Firebase di cui vuoi eseguire la migrazione utilizzando i link app / universali e di replicare lo schema di link diretti che hai utilizzato.

Ad esempio, consulta il seguente insieme di link abbreviati, parametri di link diretti e valori di link diretti di Firebase Dynamic Links di cui è stata eseguita la migrazione:

Link breve	Parametro link diretto	Link diretto sottoposto a migrazione
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

Successivamente, dovrai sostituire tutte le istanze di Firebase Dynamic Links che sono state pubblicate o condivise con i nuovi link diretti di cui è stata eseguita la migrazione in modo che gli utenti facciano clic su questi link dell'app anziché sui precedenti link dinamici Firebase.

Nota: questi nuovi link funzioneranno solo dopo aver completato il resto delle istruzioni di questa guida e dopo che l'utente avrà già scaricato e installato la tua app sul proprio dispositivo Android.

Aggiornare l'app e il codice dell'applicazione Android per ricevere i link diretti

Dopo aver selezionato un dominio, scelto uno schema di link diretti e eseguito la migrazione di Firebase Dynamic Links ad App Links, il passaggio successivo consiste nell'aggiornare l'app Android e il codice dell'applicazione in modo che ricevano i nuovi link diretti.

Ti consigliamo di consultare la documentazione completa di App Links qui o, in alternativa, la guida di Android Studio sulla configurazione dell'app per gestire i link diretti, ma i passaggi principali includono:

1. Identificazione delle attività che devono gestire i rispettivi link diretti
2. Aggiunta di un filtro per intent per queste attività nel file AndroidManifest.xml
3. Ricevere il link diretto nel codice dell'applicazione delle attività

Supponiamo che tu voglia utilizzare MainActivity per gestire alcuni dei tuoi link diretti. Per farlo, dovrai aggiungere il seguente filtro per intent a MainActivity nel file AndroidManifest.xml:

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

In questo passaggio specifichi che MainActivity è la destinazione per gestire i link diretti dal dominio wxample.web.app e che include il prefisso del percorso /welcome. Tieni presente che dovrai anche specificare l'attributo android:autoVerify="true", che ti consente di designare la tua app come gestori predefiniti per questo determinato tipo di link.

Infine, dovrai aggiungere il codice in MainActivity per recuperare i dati dei link diretti e utilizzarli per migliorare l'esperienza con i link diretti nella tua app. Questa logica è simile a quella che potresti aver già codificato nella tua app quando hai eseguito l'integrazione con Firebase Dynamic Links.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

Testare i link alle app

Puoi testare i link di app appena creati eseguendo l'app su un dispositivo fisico o nell'emulatore Android.

Dovrai creare un link cliccabile utilizzando il dominio configurato per i tuoi link di app, quindi fare clic sul link per assicurarti che si apra nella tua app e ti indirizzi all'attività prevista.

In alternativa, puoi anche testare l'integrazione di App Link utilizzando l'Assistente App Link in Android Studio oppure utilizzare il seguente comando per un URL di link alle app che hai configurato per assicurarti che avvii correttamente l'attività corrispondente:

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

Sostituire i link dinamici Firebase pubblicati o condivisi con App Links

Il passaggio finale della migrazione consisterà nel sostituire i link dinamici Firebase pubblicati o condivisi con App Link, ove possibile, e nel continuare a utilizzare App Link in futuro.

Il completamento di questo passaggio varia a seconda di dove e come hai pubblicato i tuoi Firebase Dynamic Link, ma per aiutarti a monitorare quelli esistenti, puoi esportare i metadati Firebase Dynamic Link esistenti. Consulta la guida all'esportazione dei metadati dei link dinamici.

Passaggi per la migrazione dei link universali su iOS

Nota: se hai già completato la migrazione ai link di app utilizzando la sezione precedente relativa ai passaggi per la migrazione ai link di app su Android, le istruzioni riportate di seguito saranno molto simili, tranne che per i link universali su iOS.

Crea e ospita i file di configurazione di Universal Links sul nuovo dominio di hosting

Per utilizzare i link universali, devi ospitare un file di configurazione che aiuti a stabilire un'associazione sicura tra il dominio utilizzato nei link e la tua app. Per i link universali, si tratta del file apple-app-site-association (noto anche come file AASA).

Passaggi per creare e ospitare il file apple-app-site-association

Il file AASA ci consente di fornire un elenco di app autorizzate che possono gestire i contenuti del dominio web che utilizzeremo per i nostri link universali. Il file AASA deve essere ospitato nella directory principale del dominio web nel percorso /.well-known.

Per completare questa configurazione, segui i passaggi riportati di seguito:

1. Crea la cartella ".well-known" nella cartella pubblica della directory principale di Firebase Hosting.

2. Crea un file denominato "apple-app-site-association" nella cartella ".well-known".

3. Copia i seguenti contenuti nel file apple-app-site-association, tenendo presente il significato di ciascun campo riportato di seguito:

   {
     "applinks": {
       "apps": [],
       "details": [
         {
           "appId": "$TEAM_ID.com.firebase.UniversalLinks",
           "paths": [
             "NOT /_/*",
             "/*"
           ]
         }
       ]
     }
   }
   

   • $TEAM_ID.BundleId: il nome completo dell'applicazione autorizzata a gestire i link

4. Aggiorna il file firebase.json per indicizzare il file per l'hosting.

   "headers": [
     {
       "source": "/.well-known/apple-app-site-association",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. Ora che abbiamo il file AASA, esegui il deployment di Firebase per ospitare le modifiche.

6. Verifica il file AASA visitando la pagina https://your-project-domain.web.app/.well-known/apple-app-site-association

Crea nuovi link universali corrispondenti allo schema dei link diretti utilizzato nei tuoi link dinamici Firebase

In questo passaggio, ricrei i link diretti dai tuoi link dinamici Firebase utilizzando URL di link diretti regolari corrispondenti al nuovo dominio che hai creato per i tuoi link universali.

Ad esempio, supponiamo di avere il seguente link dinamico Firebase:

Esempio di link dinamico
Nome del link	Ti diamo il benvenuto su Example.com
Link diretto	https://example.web.app/welcome
App per Android	com.example.android
App Apple	com.example.ios
Link dinamico esteso	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinamico breve	https://example.page.link/m9Mm

In questo caso, estrai il parametro del link diretto, ad esempio https://example.web.app/welcome, e utilizzalo come parametro UniversalLink per la tua app.

Nota: quando hai creato per la prima volta Firebase Dynamic Link, potresti aver creato un parametro di link diretto che utilizza un dominio di cui non sei proprietario (ad es. example.com/welcome). Firebase Dynamic Links supportava questa funzionalità, ma in questa migrazione tutti i link profondi che prevedi di utilizzare devono essere modificati in modo da utilizzare il dominio di tua proprietà e configurato in precedenza con Firebase Hosting. Se hai già utilizzato un dominio di tua proprietà per i parametri URL dei link diretti utilizzati nei tuoi link dinamici Firebase, potresti risparmiare molto tempo e la tua app potrebbe essere già configurata per gestire i link universali in entrata che dovrai creare.

Ti consigliamo di ripetere questa procedura per ogni link dinamico Firebase di cui vuoi eseguire la migrazione utilizzando i link app / universali e di replicare lo schema di link diretti che hai utilizzato.

Ad esempio, consulta il seguente insieme di link abbreviati, parametri di link diretti e valori di link diretti di Firebase Dynamic Links di cui è stata eseguita la migrazione:

Link breve	Parametro link diretto	Link diretto sottoposto a migrazione
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

Successivamente, dovrai sostituire tutte le istanze di Firebase Dynamic Links che sono state pubblicate o condivise con i nuovi link diretti di cui è stata eseguita la migrazione in modo che gli utenti facciano clic su questi link universali anziché sui precedenti link dinamici Firebase.

Nota: questi nuovi link funzioneranno solo dopo aver completato il resto delle istruzioni di questa guida e dopo che l'utente avrà già scaricato e installato la tua app sul proprio dispositivo iOS.

Aggiornare l'app e il codice dell'applicazione per iOS per ricevere i link diretti

Dopo aver selezionato un dominio, scelto uno schema di link diretti e eseguito la migrazione di Firebase Dynamic Links a Universal Links, devi aggiornare l'app e il codice dell'applicazione per iOS in modo che ricevano i nuovi link diretti.

Ti consigliamo di consultare la documentazione completa dei link universali qui per configurare la tua app in modo da gestire i link diretti, ma i passaggi principali includono:

1. Aggiorna la configurazione del progetto per consentire all'app di gestire i link diretti dal dominio appena creato

2. Ricevere il link diretto nel codice dell'applicazione

Per aggiornare la configurazione del progetto in modo che l'app possa gestire i link diretti, devi aggiungere un altro dominio associato al progetto in xCode per il dominio che ora prevedi di utilizzare per ospitare il file apple-app-site-associate.

A questo scopo, puoi:

1. Apertura di Xcode
2. Selezionare il progetto nel navigatore dei file
3. Vai alla scheda Firma e funzionalità delle impostazioni del progetto
4. Vai alla sezione Domini associati
5. Fai clic sul pulsante + per aggiungere il dominio aggiuntivo al progetto nel formato "applinks:".

Infine, devi aggiornare il codice dell'applicazione per poter ricevere i link diretti in entrata.

Per farlo, aggiorna innanzitutto il file AppDelegate.swift in modo che risponda a un Universal Link aggiungendo il seguente codice:

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

Il codice riportato sopra sostituisce il metodo di callback del link universale e registra l'URL del link diretto, se presente.

Ora chiameremo lo stesso metodo showReceivedUrl anche dalla classe SceneDelegate, poiché se l'app è già aperta quando l'utente fa clic sul link universale, sarà il callback del link universale all'interno di SceneDelegate a essere invocato.

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

Test dei link universali

Puoi testare i link universali appena creati eseguendo l'app su un dispositivo fisico o un simulatore.

Devi creare un link cliccabile utilizzando il dominio configurato per i tuoi Universal Link, quindi fare clic sul link per assicurarti che si apra nella tua app e ti indirizzi alla schermata prevista.

Supporto di Smart App Banners

Ti consigliamo vivamente di utilizzare Smart App Banner per offrire ai tuoi utenti un'esperienza simile a quella dei link dinamici di Firebase.

Se utilizzi i banner di app intelligenti, gli utenti verranno indirizzati alla scheda dell'app sull'App Store se l'app non è già installata sul loro dispositivo. Se vuoi, puoi anche configurare un parametro da passare all'app dopo il download e l'installazione per consentire agli utenti di continuare il loro percorso. Se la tua app è già installata, si aprirà passando il parametro all'app per aiutare l'utente a raggiungere i contenuti appropriati in base al banner dell'app intelligente su cui ha fatto clic.

Sostituire i link dinamici Firebase pubblicati o condivisi con App Links

Il passaggio finale della migrazione consisterà nel sostituire i link dinamici Firebase pubblicati o condivisi con i link universali, ove possibile, e nel continuare a utilizzare i link universali in futuro.

Il completamento di questo passaggio varia a seconda di dove e come hai pubblicato i tuoi link dinamici Firebase.

Per aiutarti a monitorare i Firebase Dynamic Links esistenti di cui eseguire la migrazione, pubblicheremo una guida su come esportare i metadati dei link brevi da Firebase Dynamic Links. Per ulteriori aggiornamenti, consulta il nostro documento sulle domande frequenti sulla ritiro dei link dinamici.