Migrazione da collegamenti dinamici a collegamenti app e amp; Collegamenti universali

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

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

Caratteristica Collegamenti dinamici Firebase Collegamenti alle app/Collegamenti universali
Indirizza gli utenti al negozio corretto per il loro dispositivo con un singolo clic sul collegamento
Fornisci agli utenti la continuazione del viaggio dopo aver scaricato e installato la tua app utilizzando un collegamento diretto differito
Fornisci agli utenti un'esperienza contestuale utilizzando contenuti con collegamenti diretti nella tua app (se già installata)
Fornire dati analitici relativi agli eventi di clic sui collegamenti dinamici
Fornire la possibilità di creare URL di collegamento brevi

Se continui ad aver bisogno di altre funzionalità di Firebase Dynamic Link per la tua migrazione che non sono supportate in questa guida, consulta altri scenari di migrazione nella documentazione delle domande frequenti sulla deprecazione di Dynamic Links .

Supponiamo di avere un collegamento dinamico Firebase simile a questo:

Esempio di collegamento dinamico
Nome del collegamento Benvenuto su Esempio.com
Collegamento profondo https://example.web.app/welcome
Applicazione Android com.example.android
Applicazione Apple com.example.ios
Collegamento dinamico lungo https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Breve collegamento dinamico https://example.page.link/m9Mm

L'obiettivo di questa guida alla migrazione è sostituire i collegamenti dinamici Firebase in questo modo:

https://example.page.link/m9Mm

Con App Link/Universal Link i link diretti assomigliano a questo:

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

Tieni presente che il collegamento diretto App Link/Universal Link fornirà quanto segue ai tuoi utenti:

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

Tuttavia, il collegamento diretto App Link/Universal Link non fornirà i seguenti comportamenti per i tuoi utenti (come facevano in precedenza Firebase Dynamic Links):

  • Indirizzare gli utenti allo store corretto per il loro dispositivo per scaricare e installare la tua app
  • Fornire una continuazione del percorso dell'utente dopo aver scaricato, installato e aperto l'app per la prima volta

Nota le differenze nel comportamento e nella funzionalità di questi collegamenti app/collegamenti universali rispetto ai collegamenti dinamici Firebase indicati nella tabella sopra.

Prima di iniziare

Firebase Dynamic Links utilizza App Link (su Android) e Universal Links (su iOS) nella propria implementazione sottostante per fornire funzionalità di collegamento diretto dopo che l'app è già installata.

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

Avrai bisogno delle seguenti informazioni per completare la migrazione:

  • I Firebase Dynamic Links che intendi migrare
  • I parametri URL del collegamento diretto inclusi nei collegamenti dinamici
  • Il dominio che prevedi di utilizzare per sostituire il tuo precedente dominio Firebase Dynamic Links (se applicabile)

È possibile utilizzare la guida Esporta metadati dei collegamenti dinamici per esportare i metadati dei collegamenti esistenti e ottenere le informazioni elencate sopra.

Panoramica dei passaggi della migrazione

  1. Fornisci un nuovo dominio (se non ne hai già uno che desideri utilizzare) per ospitare i file di configurazione App Link/Universal Link utilizzando Firebase Hosting.

  2. Crea e ospita i file di configurazione App Link/Universal Link sul tuo dominio di hosting.

  3. Crea nuovi collegamenti app/collegamenti universali corrispondenti allo schema di collegamento diretto utilizzato nei collegamenti dinamici Firebase.

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

  5. Testare le integrazioni dei collegamenti app/collegamenti universali.

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

Il primo passaggio sarà comune sia ai flussi di migrazione App Link che a quelli Universal Link. Il resto varierà a seconda della piattaforma, quindi vai alla sezione della guida di seguito a seconda della piattaforma di cui desideri eseguire la migrazione per prima.

Scegli un dominio

Il primo passo è scegliere un dominio che desideri utilizzare per i tuoi collegamenti alle app/collegamenti universali. Questo sarà il dominio che verrà utilizzato per i nuovi link che condividerai con i tuoi utenti.

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

Configura l'hosting Firebase

Successivamente, dovrai impostare e configurare la tua istanza di Firebase Hosting .

Quando avrai finito di configurare la tua istanza di Firebase Hosting, avrai un dominio simile al your-project-domain .web.app ` o un dominio personalizzato se preferisci.

Per utilizzare i collegamenti alle app, devi ospitare un file di configurazione che aiuti a stabilire un'associazione sicura tra il dominio utilizzato nei collegamenti e la tua app. Per i collegamenti alle app, questo è il file assetlinks.json .

Passaggi per creare e ospitare il file assetlinks.json

Il file assetlinks.json ci consente di fornire un elenco di app autorizzate in grado di gestire i contenuti del dominio web che utilizzeremo per i nostri collegamenti alle app. Il file assetlinks.json stesso deve essere ospitato nella radice del dominio Web nel percorso: /.well-known .

Seguire i passaggi seguenti per completare questa configurazione:

  1. Crea la cartella .well-known nella cartella pubblica nella directory root di Firebase Hosting.

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

  3. Copia il seguente contenuto nel tuo file assetlinks.json, prendendo nota del significato di ciascun campo sottostante:

    [{
      "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 desideri fornire
    • package_name : fa riferimento all'applicationId dichiarato nel file build.gradle dell'app
    • sha256_cert_fingerprints : si riferisce all'impronta digitale SHA256 del file di archivio di chiavi utilizzato per firmare l'applicazione.

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

    Da questo archivio di chiavi è possibile recuperare il valore SHA256 utilizzando keytool.

    Fare riferimento a questa sezione della documentazione Collegamenti app per ulteriori istruzioni su come completare questo passaggio.

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

  4. Aggiorna il tuo 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 dovrai avere la CLI Firebase installata per eseguire il comando deploy sopra.

    firebase deploy --only hosting
    
  6. Verifica il file assetlinks.json accedendo a https:// your-project-domain .web.app/.well-known/assetlinks.json

In questo passaggio, ricreerai i collegamenti diretti dai tuoi collegamenti dinamici Firebase utilizzando i normali URL di collegamento diretto corrispondenti al nuovo dominio che hai creato per i collegamenti alle app.

Quindi, ad esempio, supponiamo che tu abbia il seguente Firebase Dynamic Link:

Esempio di collegamento dinamico
Nome del collegamento Benvenuto su Esempio.com
Collegamento profondo https://example.web.app/welcome
Applicazione Android com.example.android
Applicazione Apple com.example.ios
Collegamento dinamico lungo https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Breve collegamento dinamico https://example.page.link/m9Mm

In questo caso, estrarresti il ​​parametro deep link, ad esempio https://example.web.app/welcome, e lo utilizzerai ora come parametro App Link per la tua app.

Ti consigliamo di ripetere questa procedura per ogni Firebase Dynamic Link a cui desideri eseguire la migrazione utilizzando App Link/Universal Link e replicare lo schema di deep linking che hai utilizzato.

Ad esempio, consulta il seguente set di collegamenti brevi Firebase Dynamic Links, parametri di collegamento diretto e valori di collegamento diretto migrati:

Collegamento breve Parametro del collegamento diretto Collegamento diretto migrato
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 tuaapp.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 deep link migrati in modo che gli utenti facciano clic su tali link app invece che sui precedenti Firebase Dynamic Link.

Il passaggio successivo dopo aver selezionato un dominio, scelto uno schema di collegamento diretto e migrato i collegamenti dinamici Firebase in collegamenti app è aggiornare l'app Android e il codice dell'applicazione per ricevere i nuovi collegamenti diretti.

Ti consigliamo di seguire la documentazione completa sui collegamenti alle app qui o in alternativa la guida di Android Studio sulla configurazione della tua app per gestire i collegamenti diretti, ma i passaggi principali includono:

  1. Individuare quali attività dovranno gestire i rispettivi deep link
  2. Aggiunta di un filtro intent per tali attività nel file AndroidManifest.xml
  3. Ricevere il deep link nel codice applicativo delle tue attività

Supponiamo che tu voglia utilizzare la tua MainActivity per gestire alcuni dei tuoi link diretti. Per fare ciò, dovrai aggiungere il seguente filtro intent a MainActivity nel tuo 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 la gestione dei collegamenti 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 gestore predefinito per questo determinato tipo di collegamento.

Infine, dovrai aggiungere il codice nella tua MainActivity per recuperare i dati del collegamento diretto e utilizzarli per guidare l'esperienza del collegamento diretto nella tua app. Questo è simile alla logica che potresti aver già codificato nella tua app quando hai integrato 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 collegamenti app che hai appena creato eseguendo l'app su un dispositivo fisico o nell'emulatore Android .

Dovrai creare un collegamento selezionabile utilizzando il dominio configurato per i collegamenti dell'app e quindi fare clic su quel collegamento per assicurarti che si apra nella tua app e ti indirizzi all'attività prevista.

In alternativa, puoi anche testare l'integrazione dei collegamenti app utilizzando l' Assistente collegamenti app in Android Studio oppure utilizzare il comando seguente per un URL collegamento app che hai configurato per garantire 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 collegamenti dinamici Firebase pubblicati o condivisi con i collegamenti alle app, ove possibile, e nel continuare a utilizzare i collegamenti alle app in futuro.

Il completamento di questo passaggio varierà a seconda di dove e come hai pubblicato i tuoi Firebase Dynamic Link, ma per aiutarti a tenere traccia di quelli esistenti, puoi esportare i metadati Firebase Dynamic Link esistenti. Consulta la guida Esporta metadati dei collegamenti dinamici .

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

Passaggi per creare e ospitare il file di associazione del sito dell'app apple

Il file AASA ci consente di fornire un elenco di app autorizzate in grado di gestire i contenuti del dominio web che utilizzeremo per i nostri collegamenti universali. Il file AASA stesso deve essere ospitato nella radice del dominio web nel percorso: /.well-known.

Seguire i passaggi seguenti per completare questa configurazione:

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

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

  3. Copia il seguente contenuto nel file di associazione sito-app-apple, prendendo nota del significato di ciascun campo sottostante:

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appId": "$TEAM_ID.com.firebase.UniversalLinks",
            "paths": [
              "NOT /_/*",
              "/*"
            ]
          }
        ]
      }
    }
    
    • $TEAM_ID.BundleId: il nome completo dell'applicazione autorizzata a gestire i collegamenti
  4. Aggiorna il tuo 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 la distribuzione di Firebase per ospitare le modifiche.

  6. Verifica il file AASA accedendo a https:// your-project-domain .web.app/.well-known/app-app-site-association

In questo passaggio, ricreerai i collegamenti diretti dai tuoi collegamenti dinamici Firebase utilizzando i normali URL di collegamento diretto corrispondenti al nuovo dominio che hai creato per i tuoi collegamenti universali.

Quindi, ad esempio, supponiamo che tu abbia il seguente Firebase Dynamic Link:

Esempio di collegamento dinamico
Nome del collegamento Benvenuto su Esempio.com
Collegamento profondo https://example.web.app/welcome
Applicazione Android com.example.android
Applicazione Apple com.example.ios
Collegamento dinamico lungo https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Breve collegamento dinamico https://example.page.link/m9Mm

In questo caso, estrarresti il ​​parametro deep link, ad esempio https://example.web.app/welcome, e lo utilizzerai ora come parametro Universal Link per la tua app.

Ti consigliamo di ripetere questa procedura per ogni Firebase Dynamic Link a cui desideri eseguire la migrazione utilizzando App Link/Universal Link e replicare lo schema di deep linking che hai utilizzato.

Ad esempio, consulta il seguente set di collegamenti brevi Firebase Dynamic Links, parametri di collegamento diretto e valori di collegamento diretto migrati:

Collegamento breve Parametro del collegamento diretto Collegamento diretto migrato
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 tuaapp.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 deep link migrati in modo che gli utenti facciano clic su tali link universali invece che sui precedenti Firebase Dynamic Link.

Il passaggio successivo dopo aver selezionato un dominio, scelto uno schema di collegamento diretto e migrato i collegamenti dinamici Firebase a collegamenti universali è aggiornare l'app iOS e il codice dell'applicazione per ricevere i nuovi collegamenti diretti.

Ti consigliamo di seguire la documentazione completa sui collegamenti universali qui sulla configurazione della tua app per gestire i collegamenti diretti, ma i passaggi principali includono:

  1. Aggiorna la configurazione del tuo progetto per consentire alla tua app di gestire i collegamenti diretti dal dominio appena creato

  2. Ricevi il deep link nel codice della tua applicazione

Per aggiornare la configurazione del tuo progetto per consentire alla tua app di gestire i collegamenti diretti, dovrai aggiungere un ulteriore dominio associato al tuo progetto in xCode per il dominio che intendi ora utilizzare per ospitare il tuo sito-app-apple- file associato.

Questo può essere fatto:

  1. Apertura di Xcode
  2. Selezionando il tuo progetto nel navigatore di file
  3. Passando alla scheda Firma e funzionalità delle impostazioni del progetto
  4. Scorri verso il basso fino alla sezione Domini associati
  5. Facendo clic sul pulsante + per aggiungere il dominio aggiuntivo al tuo progetto nel formato "applinks: ".

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

A tale scopo, aggiorna innanzitutto il file AppDelegate.swift per rispondere a un collegamento universale 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 precedente sovrascrive il metodo di callback Universal Link e registra l'URL del collegamento diretto, se presente.

Ora chiameremo lo stesso metodo showReceivedUrl anche dalla classe SceneDelegate poiché se l'app è già aperta nel momento in cui l'utente fa clic sul collegamento universale, il callback del collegamento universale all'interno di SceneDelegate sarà quello che verrà richiamato.

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

Puoi testare i collegamenti universali che hai appena creato eseguendo l'app su un dispositivo fisico o su un simulatore .

Dovrai creare un collegamento cliccabile utilizzando il dominio configurato per i tuoi collegamenti universali e quindi fare clic su quel collegamento per assicurarti che si apra nella tua app e ti indirizzi alla schermata desiderata nella tua app.

Supporto dei banner per app intelligenti

Ti consigliamo vivamente di utilizzare gli Smart App Banner per offrire ai tuoi utenti un'esperienza simile a Firebase Dynamic Links.

Utilizzando i banner intelligenti per app, i tuoi utenti verranno indirizzati all'App Store per l'elenco delle tue app se l'app non è già installata sul loro dispositivo. Facoltativamente, puoi anche configurare un parametro da passare alla tua app dopo averla scaricata e installata per fornire agli utenti la continuazione del loro percorso. Se la tua app è già installata, si aprirà il passaggio del parametro alla tua app per aiutare l'utente a indirizzare l'utente verso il contenuto appropriato in base al banner dell'app intelligente su cui ha fatto clic.

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

Il completamento di questo passaggio varierà a seconda di dove e come hai pubblicato i tuoi collegamenti dinamici Firebase.

Per aiutarti a tenere traccia dei Firebase Dynamic Link esistenti da migrare, pubblicheremo una guida su come esportare i metadati dei collegamenti brevi da Firebase Dynamic Links. Per ulteriori aggiornamenti, consulta il nostro documento Domande frequenti sulla deprecazione dei collegamenti dinamici .