Migrar do Dynamic Links para links de apps e universais

O foco deste guia de migração é o uso de links de apps e links universais. Como opção, use o Firebase Hosting para hospedar os arquivos de associação entre o site e o app.

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

Recurso	Firebase Dynamic Links	Links universais / de aplicativo
Direcione os usuários para a loja certa do dispositivo com um único clique no link		^★
Forneça aos usuários uma continuação da jornada após o download e a instalação do app usando um link direto adiado		^★
Ofereça aos usuários uma experiência contextual usando conteúdo com link direto no seu app (quando já instalado)
Forneça dados de análise relacionados a eventos de clique em links dinâmicos
Permita criar URLs de links curtos

Observação: os banners inteligentes de aplicativos no iOS fornecem uma maneira alternativa de exibir um banner clicável que encaminha os usuários à App Store se o aplicativo não estiver instalado para seu seu aplicativo, se já estiver instalado.

Os banners inteligentes de apps também oferecem a capacidade de transmitir parâmetros depois que um usuário clica no link do banner, o que possibilita oferecer uma continuação da jornada do usuário ao navegar para seu app clicando no banner do app inteligente.

Se você precisar 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 a suspensão de uso do Dynamic Links.

Suponha que você tenha um link dinâmico do Firebase como este:

Exemplo de link dinâmico
Nome da vinculação	Bem-vindo ao Example.com
Link direto	https://example.web.app/welcome
App 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 os links dinâmicos do Firebase como este:

https://example.page.link/m9Mm

Com links diretos do link do app / link universal que têm a seguinte aparência:

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

Os links diretos do link do app / link universal fornecerão o seguinte aos seus usuários:

• Um link direto no qual o usuário pode clicar para abrir seu aplicativo quando já estiver instalado
• Uma continuação da jornada do usuário, levando-o a uma parte específica do seu app quando ele é aberto

No entanto, o link direto do app / link universal não fornecerá os seguintes comportamentos para seus usuários (o que o Firebase Dynamic Links já fez):

• Como levar os usuários até a loja certa do dispositivo para fazer o download e instalar o app
• Oferecer uma continuação da jornada do usuário após o download, a instalação e a abertura do app pela primeira vez

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

Antes de começar

O Firebase Dynamic Links utiliza links de app (no Android) e links universais (no iOS) na própria implementação subjacente para fornecer funcionalidade de link direto depois que o aplicativo já estiver instalado.

Este guia explica como criar seus próprios links universais e de app usando o Firebase Hosting para substituir essa parte da funcionalidade fornecida pelo Firebase Dynamic Links enquanto migra seus links dinâmicos do Firebase para o novo App Links / Solução de migração de links universais.

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

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

Use o Guia de metadados de exportação de links dinâmicos para exportar seus metadados de link existentes e conseguir 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 de link do app / link universal usando o Firebase Hosting.

2. Crie e hospede seus arquivos de configuração de link do app / link universal no seu domínio de hospedagem.

3. Crie novos links universais / de app que correspondam ao esquema de links diretos usado nos seus links dinâmicos do Firebase.

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

5. Testar as integrações do App Links / Links universais.

6. Substitua os links dinâmicos publicados ou compartilhados do Firebase pelos links de app e universais.

A primeira etapa será comum para os fluxos de migração de links de app ou links universais. O restante varia de acordo com a plataforma. Portanto, navegue até a seção do guia abaixo, dependendo da plataforma que você quer migrar primeiro.

• Etapas da migração para Android App Links
• Etapas de migração para links universais no iOS

Provisionar um novo domínio para hospedar os arquivos de configuração do link do app / link universal usando o Firebase Hosting

Escolher um domínio

A primeira etapa é escolher um domínio que você quer usar para Links do app ou Universal. Esse será o domínio usado para os novos links que você compartilhará com os 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 são provisionados automaticamente sem custo. Se quiser, use um domínio personalizado com ou sem o Firebase Hosting para hospedar seus arquivos de configuração de link do app / link universal.

Configurar o Firebase Hosting

Em seguida, é preciso configurar sua instância do Firebase Hosting.

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

Etapas de migração para Android App Links

Crie e hospede seus arquivos de configuração de link de app no novo domínio de hospedagem

Para usar links de app, é necessário hospedar um arquivo de configuração que ajude a estabelecer uma associação segura entre o domínio usado nos seus links e no seu aplicativo. Para Links de apps, é o arquivo assetlinks.json.

Etapas para criar e hospedar o arquivo assetlinks.json

O arquivo assetlinks.json permite fornecer uma lista de apps autorizados que podem processar o conteúdo do domínio da Web que usaremos para nossos links de apps. O próprio arquivo assetlinks.json precisa estar hospedado na raiz do domínio da Web no caminho: /.well-known.

Siga as etapas abaixo para concluir essa 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 conteúdo a seguir para seu arquivo assetlinks.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ê quer fornecer;
   • package_name: refere-se ao applicationId declarado no arquivo build.gradle do app;
   • sha256_cert_fingerprints: refere-se à impressão digital SHA256 do arquivo de keystore usado 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 no Linux e C:\Users\<username>\.android\debug.keystore no Windows.

   A partir desse armazenamento de chaves, é possível buscar o valor SHA256 usando o keytool.

   Consulte esta seção da documentação de links do app para mais instruções sobre como concluir esta etapa.

   Como alternativa, você também pode usar o App Links Assistant no Android Studio para gerar o conteúdo do arquivo assetlinks.json e configurar seu aplicativo para processar links do app.

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 o arquivo assetlinks.json está no lugar, execute firebase deploy para hospedar as alterações.

   Você precisará ter a CLI do Firebase instalada para executar o comando de implantação acima.

   firebase deploy --only hosting
   

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

Crie novos links de apps que correspondam ao esquema de links diretos usado nos seus links dinâmicos do Firebase

Nesta etapa, você recriará os links diretos do seu Firebase Dynamic Links usando URLs de link direto regulares que correspondem ao novo domínio que você criou para seus links de aplicativos.

Por exemplo, digamos que você tenha o seguinte link dinâmico do Firebase:

Exemplo de link dinâmico
Nome da vinculação	Bem-vindo ao Example.com
Link direto	https://example.web.app/welcome
App 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, como https://example.web.app/welcome, e o usará agora como parâmetro do link de app.

Observação: quando você criou o Firebase Dynamic Link pela primeira vez, pode ter criado um parâmetro de link direto que usou um domínio que não é seu (por exemplo, example.com/welcome). O Firebase Dynamic Links era compatível com isso. No entanto, nessa migração todos os links diretos que você planeja usar precisam ser alterados para usar o domínio de sua propriedade e que estava configurado anteriormente com o Firebase Hosting. Se você já usou um domínio próprio para os parâmetros de URL de link direto usados nos seus links dinâmicos do Firebase, isso pode economizar muito tempo e seu aplicativo pode já estar configurado para tratar os Links de app recebidos que você precisará criar.

Repita esse processo para cada Firebase Dynamic Link que você queira migrar usando os links universais / de apps e replique o esquema de links diretos que você usou.

Por exemplo, veja o seguinte conjunto de links curtos, parâmetros e links diretos migrados do Firebase Dynamic Links:

Link curto	Parâmetro de link direto	Link direto migrado
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

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

Observação: esses novos links só funcionarão depois que você concluir o restante das instruções neste guia e depois que o usuário já tiver feito o download e instalado o app no dispositivo Android.

Atualizar o app Android e o código do seu 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 o App Links é atualizar seu app Android e o código do aplicativo para receber os novos links diretos.

Recomendamos seguir a documentação completa de links de apps ou o guia do Android Studio sobre como configurar seu app para processar links diretos, mas as principais etapas incluem:

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

Digamos que você queira usar sua MainActivity para processar alguns dos links diretos. Para fazer isso, adicione o seguinte filtro de intent à MainActivity no 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 processar links diretos do domínio wxample.web.app e que inclui o prefixo de caminho /welcome. Você também precisará especificar o atributo android:autoVerify="true", que permite designar seu app como o gerenciador padrão desse tipo de link.

Por fim, você precisa adicionar o código na MainActivity para recuperar os dados de link direto e usá-los para impulsionar a experiência de link direto no seu app. Isso é semelhante à lógica que você pode já ter codificado no app quando se integrou 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()
}

Como testar links de apps

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

Será necessário criar um link clicável usando o domínio configurado para seus links de app e, em seguida, clicar nesse link para garantir que ele abra o app e leve você à 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 comando a seguir para um URL do App Link configurado para garantir que ele inicia a atividade correspondente corretamente:

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

Substituir seus links dinâmicos publicados ou compartilhados do Firebase por links de apps

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

A conclusão dessa etapa varia de acordo com o local e a maneira como você publica seus links dinâmicos do Firebase, mas, para ajudar a rastrear quais deles existem, é possível exportar os metadados existentes do Firebase Dynamic Links. Consulte o Guia de metadados de exportação de Dynamic Links.

Etapas de migração para links universais no iOS

Observação: se você já concluiu a migração para os links de apps usando as etapas anteriores para seções do Android no Android, as instruções aqui serão muito semelhantes. exceto agora para links universais no iOS.

Crie e hospede seus arquivos de configuração de links universais no seu novo domínio de hospedagem

Para usar links universais, é necessário hospedar um arquivo de configuração que ajude a estabelecer uma associação segura entre o domínio usado nos seus links e no 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 permite fornecer uma lista de apps autorizados que podem processar o conteúdo do domínio da Web que usaremos para nossos links universais. O próprio arquivo ASA precisa ser hospedado na raiz do domínio da Web no caminho: /.well-known.

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

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

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

3. Copie o conteúdo a seguir no arquivo apple-app-site-association, observando o significado de cada campo abaixo:

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

   • $TEAM_ID.BundleId: nome do aplicativo totalmente qualificado autorizado a lidar com 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, faça a implantação do Firebase para hospedar as alterações.

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

Crie novos links universais que correspondam ao esquema de links diretos usado nos Firebase Dynamic Links

Nesta etapa, você recriará os links diretos do seu Firebase Dynamic Links usando URLs normais de links diretos que correspondem ao novo domínio que você criou para seus links universais.

Por exemplo, digamos que você tenha o seguinte link dinâmico do Firebase:

Exemplo de link dinâmico
Nome da vinculação	Bem-vindo ao Example.com
Link direto	https://example.web.app/welcome
App 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 (https://example.web.app/welcome) e o usará como parâmetro do link universal para seu app.

Observação: quando você criou o Firebase Dynamic Link pela primeira vez, pode ter criado um parâmetro de link direto que usou um domínio que não é seu (por exemplo, example.com/welcome). O Firebase Dynamic Links era compatível com isso. No entanto, nessa migração todos os links diretos que você planeja usar precisam ser alterados para usar o domínio de sua propriedade e que estava configurado anteriormente com o Firebase Hosting. Se você já usou um domínio que é seu para os parâmetros de URL de link direto usados no Firebase Dynamic Links, isso pode economizar muito tempo e seu app pode já estar configurado para lidar com a entrada de Links universais que precisam ser criados.

Repita esse processo para cada Firebase Dynamic Link que você queira migrar usando os links universais / de apps e replique o esquema de links diretos que você usou.

Por exemplo, veja o seguinte conjunto de links curtos, parâmetros e links diretos migrados do Firebase Dynamic Links:

Link curto	Parâmetro de link direto	Link direto migrado
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

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

Observação: esses novos links só funcionarão depois que você concluir o restante das instruções neste guia e depois que o usuário já tiver feito o download e instalado o app no dispositivo iOS.

Atualize o app 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 app iOS e o código do aplicativo para receber os novos links diretos.

Recomendamos que você siga a documentação completa sobre links universais sobre como configurar seu app para processar links diretos, mas as principais etapas incluem:

1. Atualizar a configuração do projeto para permitir que o app processe links diretos do domínio recém-criado.

2. Receber o link direto no código do aplicativo

Para atualizar a configuração do projeto e permitir que o app lide com links diretos, você precisa adicionar outro domínio associado ao projeto em xCode para o domínio que agora planeja usar para hospedar o arquivo apple-app-site-associate.

Isto pode ser feito da seguinte maneira:

1. Abrindo o Xcode
2. Selecionando seu projeto no navegador de arquivos
3. Navegando até a guia "Signing & Capabilities" nas configurações do projeto
4. Navegando até a seção "Domínios associados".
5. Clicando no botão "+" para adicionar o outro domínio ao projeto no formato "applinks:".

Por fim, você precisa atualizar o código do aplicativo para 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 callback do link universal e registra o URL do link direto, se houver.

Agora, vamos chamar o mesmo método showReceivedUrl da classe SceneDelegate, já que, se o app já estiver aberto no momento em que o usuário clicar no link universal, o callback do link universal dentro de SceneDelegate será o invocado.

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

Como testar links universais

É possível testar os links universais que você acabou de criar executando seu app em um dispositivo ou simulador físico.

Será necessário criar um link clicável usando o domínio configurado para seus links universais e, em seguida, clicar nesse link para garantir que ele abra o aplicativo e leve você até a tela pretendida no aplicativo.

Compatibilidade com banners de aplicativos inteligentes

É altamente recomendável usar os banners de aplicativos inteligentes como uma maneira de oferecer aos seus usuários uma experiência semelhante à do Firebase Dynamic Links.

Com os banners inteligentes de aplicativos, seus usuários serão levados à App Store para a listagem se seu aplicativo ainda não estiver instalado no dispositivo. Como opção, você pode configurar um parâmetro para transmitir ao seu app depois que ele for transferido por download e instalado para fornecer aos usuários uma continuação da jornada. Se o app já estiver instalado, ele abrirá o parâmetro para ajudar a navegar o usuário para o conteúdo apropriado com base no banner do app inteligente em que ele clicou.

Substituir seus links dinâmicos publicados ou compartilhados do Firebase por links de apps

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

A conclusão dessa etapa varia de acordo com o local e a maneira como você publica seus links dinâmicos do Firebase.

Para ajudar você a acompanhar a migração dos Firebase Dynamic Links, publicaremos um guia sobre como exportar os metadados de links curtos do Firebase Dynamic Links. Verifique nosso documento de perguntas frequentes sobre a suspensão de uso do Dynamic Links para mais atualizações.