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

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 una continuazione del percorso dell'utente 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 universali 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.

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 Link app / 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.

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

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.

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 dinamici Firebase, parametri dei link diretti e valori dei link diretti 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.

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

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>

Il passaggio finale della migrazione consisterà nel sostituire i link dinamici Firebase pubblicati o condivisi con i link di app, ove possibile, e nel continuare a utilizzare i link di app 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.

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

In questo passaggio, ricrei i link diretti da Firebase Dynamic Links 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.

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 dinamici Firebase, parametri dei link diretti e valori dei link diretti 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.

Dopo aver selezionato un dominio, scelto uno schema di link diretti e eseguito la migrazione di Firebase Dynamic Links a Universal Links, il passaggio successivo consiste nell'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)
}

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 ai Firebase Dynamic Links.

Se utilizzi i banner di app intelligenti, gli utenti verranno indirizzati alla scheda della tua app sull'App Store se la tua 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.

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.