Migre de Dynamic Links para App Links & Links Universais

Este guia de migração se concentra no uso de App Links e Universal Links , opcionalmente usando o Firebase Hosting para hospedar seus arquivos de associação de site de aplicativo.

Esta migração substitui os seguintes recursos do Firebase Dynamic Links:

Recurso	Links dinâmicos do Firebase	Links de aplicativos/links universais
Direcione os usuários para a loja correta para seus dispositivos com um único clique no link		★
Forneça aos usuários uma continuação da jornada após baixar e instalar seu aplicativo usando um link direto adiado		★
Forneça aos usuários uma experiência contextual usando conteúdo com links diretos em seu aplicativo (quando já instalado)
Fornece dados analíticos relacionados a eventos de clique em link dinâmico
Fornece a capacidade de criar URLs de links curtos

Se você continuar precisando de outros recursos do Firebase Dynamic Link para sua migração que não são compatíveis com este guia, consulte outros cenários de migração na documentação de perguntas frequentes sobre suspensão de uso do Dynamic Links .

Suponha que você tenha um Firebase Dynamic Link parecido com este:

Exemplo de link dinâmico
Nome do link	Bem-vindo ao Exemplo.com
Link profundo	https://example.web.app/welcome
Aplicativo Android	com.example.android
Aplicativo da Apple	com.example.ios
Link Dinâmico Longo	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinâmico curto	https://example.page.link/m9Mm

O objetivo deste guia de migração é substituir o Firebase Dynamic Links assim:

https://example.page.link/m9Mm

Com links diretos do App Link/Universal Link parecidos com este:

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

Observe que o link direto App Link/Universal Link fornecerá o seguinte aos seus usuários:

• Um link direto em que eles podem clicar e que abrirá seu aplicativo quando já estiver instalado
• Uma continuação da jornada do usuário, navegando até uma parte específica do seu aplicativo quando ele é aberto

No entanto, o link direto App Link/Universal Link não fornecerá os seguintes comportamentos para seus usuários (o que o Firebase Dynamic Links fazia anteriormente):

• Direcionar os usuários até a loja correta do dispositivo para baixar e instalar seu aplicativo
• Fornecer uma continuação da jornada do usuário após baixar, instalar e abrir o aplicativo pela primeira vez

Observe as diferenças de comportamento e funcionalidade desses links de aplicativos/links universais em comparação com os links dinâmicos do Firebase indicados na tabela acima.

Antes de você começar

O Firebase Dynamic Links utiliza App Links (no Android) e Universal Links (no iOS) em sua própria implementação subjacente para fornecer funcionalidade de deep linking depois que seu aplicativo já estiver instalado.

Este guia explica como criar seus próprios App Links e Universal Links usando o Firebase Hosting para substituir essa parte da funcionalidade fornecida pelo Firebase Dynamic Links ao migrar seus Firebase Dynamic Links para a nova solução de migração App Links/Universal Links.

Você precisará das seguintes informações para concluir sua migração:

• Os Firebase Dynamic Links que você pretende migrar
• Os parâmetros de URL de link direto incluídos em seus links dinâmicos
• O domínio que você planeja usar para substituir o domínio anterior do Firebase Dynamic Links (se aplicável)

Você pode usar o guia Exportar metadados de links dinâmicos para exportar os metadados de link existentes e obter as informações listadas acima.

Visão geral das etapas de migração

1. Provisione um novo domínio (se você ainda não tiver um que queira usar) para hospedar seus arquivos de configuração do App Link/Universal Link usando o Firebase Hosting.

2. Crie e hospede seus arquivos de configuração do App Link/Universal Link em seu domínio de hospedagem.

3. Crie novos links de aplicativos/links universais que correspondam ao esquema de link direto usado em seus links dinâmicos do Firebase.

4. Atualize seus aplicativos Android/iOS e o código do aplicativo para receber links diretos.

5. Testando suas integrações de App Links/Universal Links.

6. Substitua seus links dinâmicos do Firebase publicados ou compartilhados por links de aplicativos e links universais.

A primeira etapa será comum aos fluxos de migração do App Links ou do Universal Link. O restante irá variar dependendo da plataforma, então navegue até a seção do guia abaixo dependendo de qual plataforma você gostaria de migrar primeiro.

• Etapas de migração para links de aplicativos Android
• Etapas de migração para links universais no iOS

Provisione um novo domínio para hospedar seus arquivos de configuração do App Link/Universal Link usando o Firebase Hosting

Escolha um domínio

O primeiro passo é escolher um domínio que você gostaria de usar para seus App Links/Universal Links. Este será o domínio que será usado para os novos links que você compartilhará com seus usuários.

Se você usa o Firebase Hosting , os subdomínios do projeto com o formato your-project-domain .web.app ou your-project-domain .firebaseapp.com serão provisionados automaticamente sem nenhum custo. Opcionalmente, você pode usar um domínio personalizado com ou sem Firebase Hosting para hospedar seus arquivos de configuração do App Link/Universal Link.

Configurar o Firebase Hosting

Em seguida, você precisará instalar e configurar sua instância do Firebase Hosting .

Quando terminar de configurar sua instância do Firebase Hosting, você terá um domínio semelhante ao your-project-domain .web.app `ou um domínio personalizado , se preferir.

Etapas de migração para links de aplicativos Android

Crie e hospede seus arquivos de configuração do App Link em seu novo domínio de hospedagem

Para usar App Links, você deve hospedar um arquivo de configuração que ajude a estabelecer uma associação segura entre o domínio usado em seus links e seu aplicativo. Para App Links, este é o arquivo assetlinks.json .

Etapas para criar e hospedar o arquivo assetslinks.json

O arquivo assetlinks.json nos permite fornecer uma lista de aplicativos autorizados que podem lidar com o conteúdo do domínio da web que usaremos para nossos links de aplicativos. O próprio arquivo assetlinks.json precisa ser hospedado na raiz do domínio da web no caminho: /.well-known .

Siga as etapas abaixo para concluir esta configuração:

1. Crie a pasta .well-known na pasta pública no diretório raiz do Firebase Hosting.

2. Crie um arquivo chamado assetlinks.json na pasta .well-known .

3. Copie o seguinte conteúdo para seu arquivo assetslinks.json, anotando o significado de cada campo abaixo:

   [{
     "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 - refere-se ao nome do aplicativo que você deseja fornecer
   • package_name - refere-se ao applicationId declarado no arquivo build.gradle do aplicativo
   • sha256_cert_fingerprints - refere-se à impressão digital SHA256 do arquivo keystore que você usa para assinar o aplicativo.

   Você pode usar o arquivo debug.keystore usado pelo Android Studio para gerar um registro sha256_cert_fingerprints para fins de depuração. Você pode encontrar o arquivo em /Users/<username>/.android/debug.keystore no Mac e Linux e C:\Users\<username>\.android\debug.keystore no Windows.

   Nesse keystore, você pode buscar o valor SHA256 usando o keytool.

   Consulte esta seção da documentação do App Links para obter mais instruções sobre como concluir esta etapa.

   Alternativamente, você também pode usar o App Links Assistant no Android Studio para gerar o conteúdo do arquivo assetslinks.json e configurar seu aplicativo para lidar com App Links.

4. Atualize seu arquivo firebase.json para indexar o arquivo para hospedagem.

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

5. Agora que temos o arquivo assetlinks.json instalado, execute firebase deploy para hospedar as alterações.

   Observe que você precisará ter o Firebase CLI instalado para executar o comando de implantação acima.

   firebase deploy --only hosting
   

6. Verifique o arquivo assetslinks.json acessando https:// your-project-domain .web.app/.well-known/assetlinks.json

Crie novos links de aplicativos que correspondam ao esquema de link direto usado em seus Firebase Dynamic Links

Nesta etapa, você recriará os links diretos dos seus links dinâmicos do Firebase usando URLs de links diretos regulares que correspondam ao novo domínio que você criou para os links do seu aplicativo.

Por exemplo, digamos que você tenha o seguinte Firebase Dynamic Link:

Exemplo de link dinâmico
Nome do link	Bem-vindo ao Exemplo.com
Link profundo	https://example.web.app/welcome
Aplicativo Android	com.example.android
Aplicativo da Apple	com.example.ios
Link Dinâmico Longo	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinâmico curto	https://example.page.link/m9Mm

Nesse caso, você extrairia o parâmetro de link direto - ou seja, https://example.web.app/welcome e agora usaria isso como o parâmetro App Link para seu aplicativo.

Você desejará repetir esse processo para cada link dinâmico do Firebase para o qual deseja migrar usando links de aplicativos/links universais e replicar o esquema de link direto usado.

Por exemplo, consulte o seguinte conjunto de links curtos do Firebase Dynamic Links, parâmetros de link direto e valores de link direto migrados:

Ligação curta	Parâmetro de link direto	Link direto migrado
seuapp.page.link/welcome	https://example.com/welcome	seuapp.web.app/welcome
seuapp.page.link/c7sn	https://example.com/main/?p=23&t=1	seuapp.web.app/main/?p=23&t=1
seuapp.page.link/social	https://example.com/friendinvite/?add=1	seuapp.web.app/friendinvite/?add=1

Em seguida, você precisará substituir todas as instâncias do Firebase Dynamic Links que foram publicadas ou compartilhadas pelos novos links diretos migrados para que os usuários cliquem nesses App Links em vez dos Firebase Dynamic Links anteriores.

Atualize seu aplicativo Android e o código do aplicativo para receber links diretos

A próxima etapa após selecionar um domínio, escolher um esquema de link direto e migrar seus Firebase Dynamic Links para App Links é atualizar seu aplicativo Android e o código do aplicativo para receber os novos links diretos.

Recomendamos seguir a documentação completa dos App Links aqui ou, alternativamente, o guia do Android Studio sobre como configurar seu aplicativo para lidar com links diretos, mas as etapas principais incluem:

1. Identificar quais atividades devem lidar com os respectivos links diretos
2. Adicionando um filtro de intent para essas atividades em seu arquivo AndroidManifest.xml
3. Recebendo o link direto no código do aplicativo de suas atividades

Digamos que você queira usar MainActivity para lidar com alguns de seus links diretos. Para fazer isso, você precisará adicionar o seguinte filtro de intenção à MainActivity em seu arquivo 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>

Nesta etapa, você está especificando que MainActivity é o destino para lidar com links diretos do domínio wxample.web.app e isso inclui o prefixo do caminho /welcome. Observe que você também precisará especificar o atributo android:autoVerify="true", que permite designar seu aplicativo como o manipulador padrão para esse tipo de link.

Por fim, você precisará adicionar o código em sua MainActivity para recuperar os dados do link direto e usá-los para impulsionar a experiência do link direto no seu aplicativo. Isso é semelhante à lógica que você já deve ter codificado em seu aplicativo ao integrá-lo ao 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()
}

Testando links de aplicativos

Você pode testar os links de aplicativos que acabou de criar executando seu aplicativo em um dispositivo físico ou no Android Emulator .

Você precisará criar um link clicável usando o domínio configurado para seus links de aplicativos e, em seguida, clicar nesse link para garantir que ele seja aberto em seu aplicativo e direcione você para a atividade pretendida.

Como alternativa, você também pode testar a integração do App Links usando o App Links Assistant no Android Studio ou usar o seguinte comando para um URL do App Link que você configurou para garantir que ele inicie a atividade correspondente corretamente:

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

Substitua seus links dinâmicos do Firebase publicados ou compartilhados por links de aplicativos

A etapa final da migração será substituir os links dinâmicos do Firebase publicados ou compartilhados por links de aplicativos sempre que possível e continuar usando links de aplicativos daqui para frente.

A conclusão desta etapa irá variar dependendo de onde e como você publicou seus Firebase Dynamic Links, mas para ajudá-lo a rastrear quais existem, você pode exportar seus metadados existentes do Firebase Dynamic Link. Consulte o guia Exportar metadados de links dinâmicos .

Etapas de migração para links universais no iOS

Crie e hospede seus arquivos de configuração do Universal Links em seu novo domínio de hospedagem

Para usar links universais, você deve hospedar um arquivo de configuração que ajude a estabelecer uma associação segura entre o domínio usado em seus links e seu aplicativo. Para links universais, este é o arquivo apple-app-site-association (também conhecido como arquivo AASA).

Etapas para criar e hospedar o arquivo apple-app-site-associaton

O arquivo AASA nos permite fornecer uma lista de aplicativos autorizados que podem lidar com o conteúdo do domínio da web que usaremos para nossos links universais. O próprio arquivo AASA precisa ser hospedado na raiz do domínio da web no caminho: /.well-known.

Siga as etapas abaixo para concluir esta configuração:

1. Crie a pasta " .well-known " na pasta pública do diretório raiz do Firebase Hosting.

2. Crie um arquivo chamado " apple-app-site-association " na pasta ".well-known".

3. Copie o seguinte conteúdo para o arquivo apple-app-site-association, anotando o significado de cada campo abaixo:

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

   • $TEAM_ID.BundleId – o nome completo do aplicativo autorizado a manipular os links

4. Atualize seu arquivo firebase.json para indexar o arquivo para hospedagem.

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

5. Agora que temos o arquivo AASA instalado, faça o firebase deploy para hospedar as alterações.

6. Verifique o arquivo AASA acessando https:// your-project-domain .web.app/.well-known/app-app-site-association

Crie novos links universais que correspondam ao esquema de link direto usado em seus Firebase Dynamic Links

Nesta etapa, você recriará os links diretos dos seus links dinâmicos do Firebase usando URLs de links diretos regulares que correspondam ao novo domínio que você criou para seus links universais.

Por exemplo, digamos que você tenha o seguinte Firebase Dynamic Link:

Exemplo de link dinâmico
Nome do link	Bem-vindo ao Exemplo.com
Link profundo	https://example.web.app/welcome
Aplicativo Android	com.example.android
Aplicativo da Apple	com.example.ios
Link Dinâmico Longo	https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Link dinâmico curto	https://example.page.link/m9Mm

Nesse caso, você extrairia o parâmetro de link direto - ou seja, https://example.web.app/welcome e agora o usaria como parâmetro de link universal para seu aplicativo.

Você desejará repetir esse processo para cada link dinâmico do Firebase para o qual deseja migrar usando links de aplicativos/links universais e replicar o esquema de link direto usado.

Por exemplo, consulte o seguinte conjunto de links curtos do Firebase Dynamic Links, parâmetros de link direto e valores de link direto migrados:

Ligação curta	Parâmetro de link direto	Link direto migrado
seuapp.page.link/welcome	https://example.com/welcome	seuapp.web.app/welcome
seuapp.page.link/c7sn	https://example.com/main/?p=23&t=1	seuapp.web.app/main/?p=23&t=1
seuapp.page.link/social	https://example.com/friendinvite/?add=1	seuapp.web.app/friendinvite/?add=1

Em seguida, você precisará substituir todas as instâncias do Firebase Dynamic Links que foram publicadas ou compartilhadas pelos novos links diretos migrados para que os usuários cliquem nesses links universais em vez dos Firebase Dynamic Links anteriores.

Atualize seu aplicativo iOS e o código do aplicativo para receber links diretos

A próxima etapa após selecionar um domínio, escolher um esquema de link direto e migrar seus links dinâmicos do Firebase para links universais é atualizar seu aplicativo iOS e o código do aplicativo para receber os novos links diretos.

Recomendamos seguir a documentação completa do Universal Links aqui sobre como configurar seu aplicativo para lidar com links diretos, mas as etapas principais incluem:

1. Atualize a configuração do seu projeto para permitir que seu aplicativo lide com links diretos do seu domínio recém-criado

2. Receba o link direto no código do seu aplicativo

Para atualizar a configuração do seu projeto para permitir que seu aplicativo lide com links diretos, você precisará adicionar um domínio associado adicional ao seu projeto no xCode para o domínio que você planeja usar agora para hospedar seu apple-app-site- arquivo associado.

Isso pode ser feito por:

1. Abrindo o Xcode
2. Selecionando seu projeto no navegador de arquivos
3. Navegando até a guia Assinatura e recursos das configurações do seu projeto
4. Navegue até a seção Domínios Associados
5. Clicando no botão + para adicionar o domínio adicional ao seu projeto no formato "applinks: ".

Finalmente, você precisa atualizar o código do seu aplicativo para poder receber os links diretos recebidos.

Para fazer isso, primeiro atualize o arquivo AppDelegate.swift para responder a um link universal adicionando o seguinte código:

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

O código acima substitui o método de retorno de chamada do Universal Link e registra o URL do link direto, se presente.

Agora chamaremos o mesmo método showReceivedUrl da classe SceneDelegate, pois se o aplicativo já estiver aberto no momento em que o usuário clicou no link universal, o retorno de chamada do link universal dentro do SceneDelegate será aquele que será invocado.

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

Testando links universais

Você pode testar os links universais que acabou de criar executando seu aplicativo em um dispositivo físico ou em um simulador .

Você precisará criar um link clicável usando o domínio configurado para seus links universais e, em seguida, clicar nesse link para garantir que ele seja aberto em seu aplicativo e direcione você para a tela pretendida em seu aplicativo.

Suporte a banners de aplicativos inteligentes

Recomendamos fortemente o uso de banners de aplicativos inteligentes como forma de fornecer aos usuários uma experiência semelhante ao Firebase Dynamic Links.

Usando banners de aplicativos inteligentes, seus usuários serão direcionados à App Store para obter a listagem de seu aplicativo, caso ele ainda não esteja instalado em seus dispositivos. Opcionalmente, você também pode configurar um parâmetro a ser transmitido ao seu aplicativo depois que ele for baixado e instalado para fornecer aos usuários uma continuação de sua jornada. Se o seu aplicativo já estiver instalado, ele abrirá a passagem do parâmetro para o seu aplicativo para ajudar a navegar o usuário até o conteúdo apropriado com base no Smart App Banner em que ele clicou.

Substitua seus links dinâmicos do Firebase publicados ou compartilhados por links de aplicativos

A etapa final da migração será substituir os links dinâmicos do Firebase publicados ou compartilhados por links universais sempre que possível e continuar usando os links universais daqui para frente.

A conclusão desta etapa irá variar dependendo de onde e como você publicou seus Firebase Dynamic Links.

Para ajudá-lo a rastrear os Firebase Dynamic Links existentes a serem migrados, publicaremos um guia sobre como exportar seus metadados de links curtos do Firebase Dynamic Links. Verifique novamente nosso documento de perguntas frequentes sobre suspensão de uso do Dynamic Links para obter mais atualizações.