Configurar associações de sites e regras dinâmicas

Para oferecer suporte a links de apps, é necessário criar um Digital Asset Links arquivo JSON chamado assetlinks.json e publicá-lo em um local conhecido no seu site. Esse arquivo declara publicamente quais apps estão autorizados a processar links para seu domínio, e os dispositivos Android vão recuperar esse arquivo do seu servidor para verificar os links diretos.

Para links dinâmicos de apps no Android 15 e versões mais recentes, o arquivo assetlinks.json também é onde você define a configuração de regras dinâmicas, como correspondências de padrões para caminho, fragmento e parâmetros de consulta. Os dispositivos Android com o Android 15 (nível 35 da API) ou versões mais recentes que têm os Serviços do Google instalados vão recuperar o arquivo periodicamente e mesclar a configuração dinâmica com a estática no manifesto do app.

Este guia descreve como preparar um arquivo assetlinks.json e publicá-lo no seu site. Se preferir, você pode gerar um arquivo assetlinks.json na ferramenta Play Deep Links ou no assistente de Links do App do Android Studio. Para mais informações, consulte Ferramentas para desenvolvedores de links de apps.

Declarar associações de site

É necessário publicar um arquivo JSON do Digital Asset Links no seu site para indicar os apps para Android associados ao site e verificar os intents de URL do app. O arquivo JSON usa os seguintes campos para identificar apps associados:

package_name: o ID do aplicativo declarado no build.gradle arquivo do app.
sha256_cert_fingerprints: as impressões digitais SHA256 do certificado assinado do app. É possível usar o Java Keytool para gerar a impressão digital usando o seguinte comando:

keytool -list -v -keystore my-release-key.keystore

Esse campo é compatível com diversas impressões digitais, que podem ser usadas para fins de compatibilidade com diferentes versões do seu app, como versões de depuração e de produção. Se você estiver usando Assinatura de apps do Google Play no seu app, a impressão digital do certificado gerada pela execução do keytool localmente geralmente não vai corresponder à dos dispositivos dos usuários. É possível verificar se você está usando a Assinatura de apps do Google Play no seu app na sua conta de desenvolvedor do Play Console em Release > Setup > App signing. Se você estiver usando, também vai encontrar o snippet JSON correto do Digital Asset Links do app na mesma página.

O seguinte arquivo assetlinks.json de exemplo concede direitos de abertura de link a um app Android com.example:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Associar um site a vários apps

Um site pode declarar associações com vários apps no mesmo arquivo assetlinks.json. A seguinte lista de arquivos exibe um exemplo de arquivo de declaração de associação com dois apps separadamente e está localizada em https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Diferentes apps podem processar links para recursos distintos sob o mesmo host da Web. Por exemplo, o app1 pode declarar um filtro de intent para https://example.com/articles, e o app2 pode declarar um filtro de intent para https://example.com/videos.

Associar vários sites a um único app

Diversos sites podem declarar associações ao mesmo app nos respectivos arquivos assetlinks.json. As listas de arquivos a seguir mostram um exemplo de como declarar a associação de example.com e example.net ao app1. A primeira lista mostra a associação de example.com ao app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

A próxima lista mostra a associação de example.net ao app1. Somente o local em que esses arquivos estão hospedados é diferente (.com e .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Configurar regras dinâmicas

Os links dinâmicos de apps no Android 15 e versões mais recentes permitem usar regras de correspondência de links diretos do lado do servidor que funcionam com as regras definidas estaticamente no manifesto do app. O arquivo assetlinks.json é onde você define regras dinâmicas. Essa inclusão é opcional.

Os dispositivos Android com o Android 15 (nível 35 da API) ou versões mais recentes que têm os Serviços do Google instalados vão recuperar esse arquivo periodicamente do seu servidor e mesclar a configuração de regras dinâmicas com a configuração estática no manifesto do app. Confira a seguir um exemplo de arquivo assetlinks.json com regras dinâmicas:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Principais pontos sobre o código

Os links dinâmicos de apps adicionam uma nova extensão de relação do Digital Asset Links chamada dynamic_app_link_components, que é onde você configura as regras dinâmicas.
As regras dinâmicas podem incluir correspondências de padrões para caminho, fragmento e parâmetros de consulta.
Também é possível marcar qualquer correspondência de padrão como excluída para que os URLs correspondentes não abram o app.
Este exemplo mostra correspondências para caminho ("/"), fragmento ("#"), parâmetros de consulta ("?") e correspondências excluídas ("exclude").
Se algum dos campos no arquivo estiver incorreto ou vazio, o Android vai descartar as regras dinâmicas, e o dispositivo vai voltar às regras definidas estaticamente no manifesto do app.

As regras dinâmicas só podem especificar regras que se aplicam ao escopo dos domínios declarados no arquivo de manifesto do app. Veja abaixo.

Declarar regras dinâmicas

Os links dinâmicos de apps oferecem suporte a uma nova extensão de relação dynamic_app_link_components, que contém uma matriz de objetos de regras. Cada regra é definida usando correspondências de padrões para caminhos, fragmentos e parâmetros de consulta que vão abrir seu app. As correspondências também podem ser excluídas individualmente para que não abram seu app. Todas essas opções são opcionais.

Correspondência de caminho
- Chave: "/"
- Valor: string única, expressão correspondente para o caminho do URL
Correspondência de fragmento
- Chave: "#"
- Valor: string única, expressão correspondente para o fragmento do URL
Correspondência de parâmetros de consulta
- Chave: "?"
- Valor: dicionário para corresponder a pares de chave/valor nos parâmetros de consulta do URL.
- Por exemplo, o dicionário "?", {"dl": "*", "in_app":"true" vai corresponder à string de consulta "?in_app=true&dl=abc".
- A ordem dos pares de chave/valor no dicionário não precisa corresponder à ordem dos pares na string de consulta. Além disso, o dicionário não precisa corresponder a todos os pares de chave/valor na string de consulta, mas uma correspondência precisa ser encontrada para cada entrada do dicionário.
- Por exemplo, o dicionário também corresponderia à string de consulta "?lang=en&in_app=true&tz=pst&dl=abc", mas não à string de consulta "?lang=en&tz=pst&dl=abc"
Excluído
- Chave: "exclude"
- Valor: valor verdadeiro/falso opcional para cada regra definida em dynamic_app_link_components (consulte o exemplo).

É possível usar estes caracteres especiais em correspondências de padrões:

"*" corresponde a zero ou mais caracteres até que o caractere após o caractere curinga no padrão seja encontrado na string correspondente.
"?" corresponde a qualquer caractere único.
"?*" corresponde a um ou mais caracteres.

Não há outras restrições de caracteres para valores.

Ordenar regras dinâmicas

A ordem em que as regras são declaradas é importante. O Android avalia cada regra em ordem até encontrar uma correspondência.

O exemplo a seguir mostra como a ordenação pode afetar o processamento. A primeira regra corresponde a todos os caminhos ("*"), mas exclui correspondências (exclude: true), o que significa que ela exclui todos os URLs da abertura do app. Nesse caso, a segunda regra que permite "/path1" nunca será avaliada.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

No entanto, no exemplo a seguir, a regra "/path1" é declarada primeiro. Portanto, ela será avaliada primeiro e vai abrir o app para um URL correspondente a "/path1". A segunda regra, que exclui todos os URLs da abertura do app, será avaliada em segundo lugar, mas somente se a primeira regra não for uma correspondência.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Se nenhuma correspondência for encontrada na lista de componentes declarados, o URL não vai abrir o app. No exemplo a seguir, nenhum dos caminhos corresponde a "/path3", então o dispositivo vai tratar esse caminho como excluído.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Esse comportamento é importante se você quiser que dynamic_app_link_components exclua apenas determinadas partes do URL, mas permita todas as outras. No exemplo a seguir, omitir a regra final para permitir todos os caminhos restantes significaria que todos os URLs seriam excluídos do app.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Definir o escopo das regras dinâmicas corretamente

Ao definir as regras do lado do servidor para uso com links dinâmicos de apps no Android 15 e versões mais recentes, é importante definir o escopo delas adequadamente para que funcionem e complementem os filtros de intent estáticos declarados no manifesto do app.

As regras dinâmicas declaradas no arquivo assetlinks.json só podem especificar regras para os hosts declarados no arquivo AndroidManifest.xml do app. As regras dinâmicas não podem expandir o escopo das regras de URL declaradas estaticamente no manifesto do app.

Por esse motivo, recomendamos usar essa abordagem nas regras dinâmicas e estáticas:

No manifesto do app, defina regras com o escopo mais amplo possível, como declarar apenas o esquema e o domínio.
Confie nas regras dinâmicas do lado do servidor para mais refinamento, como o roteamento no nível do caminho.

Com essa configuração ideal, você poderá adicionar dinamicamente novos caminhos de links de apps no arquivo assetlinks.json conforme necessário, sabendo que eles vão se ajustar ao escopo amplo definido no manifesto do app.

Declarar dynamic_app_link_components apenas uma vez

Para o processamento adequado das regras, declare apenas um objeto dynamic_app_link_components nas instruções de um determinado site, relação e app.

Procure várias instruções para o mesmo site, relação e app que declaram um objeto dynamic_app_link_components.
Procure vários objetos dynamic_app_link_components declarados em uma única instrução.

Nesses casos, o Android não garante qual configuração de regras dinâmicas será usada.

Compatibilidade de regras dinâmicas com configurações anteriores de links de apps

Se você já oferece suporte a links de apps, pode adicionar suporte a links dinâmicos de apps diretamente no arquivo assetlinks.json. Os campos de relação para verificar os links de apps permanecem os mesmos, e você pode adicionar os novos campos de extensão de relação para regras dinâmicas sem outras mudanças.

Os dispositivos Android com o Android 14 (nível 34 da API ou versões anteriores) ignoram os novos campos de extensão de relação para regras dinâmicas, enquanto os dispositivos com o Android 15 e versões mais recentes vão mesclar essas regras com as regras definidas pelo manifesto.

Publicar o arquivo de verificação JSON

É preciso publicar o arquivo de verificação JSON no seguinte local:

https://domain.name/.well-known/assetlinks.json

As condições a seguir precisam ser atendidas:

O arquivo assetlinks.json é exibido com tipo de conteúdo application/json.
O arquivo assetlinks.json precisa ser acessível por meio de uma conexão HTTPS, independentemente de os filtros de intent do app declararem HTTPS como o esquema de dados ou não.
O arquivo assetlinks.json precisa ser acessível sem redirecionamentos (sem redirecionamentos 301 ou 302).
Se os links do app forem compatíveis com vários domínios de host, será necessário publicar o arquivo assetlinks.json em cada domínio. Consulte Como oferecer compatibilidade com links de app para diversos hosts.
Não publique seu app com URLs de teste em arquivos de manifesto que podem não ser publicamente acessíveis (por exemplo, todos aqueles que só podem ser acessados com uma VPN). Uma solução alternativa nesses casos é configurar variantes de compilação para gerar outro arquivo de manifesto para versões de desenvolvimento.

Consulte os seguintes guias relacionados: