O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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

Para oferecer suporte aos Links do App, crie um arquivo JSON do Digital Asset Links chamado assetlinks.json e publique-o 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 parâmetros de caminho, fragmento e consulta. Os dispositivos Android com o Android 15 (nível 35 da API) ou mais recente que têm os Serviços do Google instalados vão recuperar periodicamente o arquivo 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, gere um arquivo assetlinks.json com a ferramenta de links diretos do Google Play ou o 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

Publique um arquivo JSON do Digital Asset Links no seu site para indicar os apps Android associados a ele e verificar as intents de URL do app. O arquivo JSON usa os seguintes campos para identificar apps associados:

package_name: o ID do aplicativo declarado no arquivo build.gradle do app.
sha256_cert_fingerprints: as impressões digitais SHA256 do certificado de assinatura do app. Use o seguinte comando para gerar a impressão digital com o keytool do Java:

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

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

O exemplo de arquivo assetlinks.json a seguir concede direitos de abertura de links 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 listagem de arquivos a seguir mostra um exemplo de um arquivo de declaração que declara associação com dois apps, separadamente, e reside 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

Vários sites podem declarar associações com o mesmo app nos respectivos arquivos assetlinks.json. As listagens de arquivos a seguir mostram um exemplo de como declarar a associação de example.com e example.net com o app1. A primeira lista mostra a associação de example.com com 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. Apenas o local em que esses arquivos sã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+ 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 as regras dinâmicas. A 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 periodicamente esse arquivo do seu servidor e mesclar a configuração de regras dinâmicas com a configuração estática no manifesto do app. Confira abaixo 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}
        ]
      }
    }
  }
]

Pontos principais 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 suas regras dinâmicas.
As regras dinâmicas podem incluir correspondências de padrão para parâmetros de caminho, fragmento e 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 ("#") e parâmetros de consulta ("?"), além de 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 usar as 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. Consulte a seção Declarar regras dinâmicas.

Declarar regras dinâmicas

Os Links Dinâmicos para Apps são compatíveis com 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ão para caminhos, fragmentos e parâmetros de consulta que vão abrir o app. As correspondências também podem ser excluídas individualmente para que não abram o app. Todas elas são opcionais.

Correspondência de caminho
- Tecla: "/"
- Valor: string única, expressão de correspondência para o caminho do URL
Correspondência de fragmentos
- Tecla: "#"
- Valor: string única, expressão de correspondência para o fragmento do URL
Correspondência de parâmetros de consulta
- Tecla: "?"
- Valor: dicionário para corresponder aos 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 ou Falso opcional para cada regra definida em dynamic_app_link_components (consulte o exemplo).

Você pode usar estes caracteres especiais em correspondências de padrão:

"*" 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 as correspondências (exclude: true), o que significa que ela impede que todos os URLs abram o app. Nesse caso, a segunda regra que permite "/path1" nunca será avaliada.

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

No entanto, no próximo exemplo, a regra "/path1" é declarada primeiro. Portanto, ela será avaliada primeiro e abrirá o app para um URL que corresponda a "/path1". A segunda regra, que impede que todos os URLs abram o app, será avaliada em seguida, mas somente se a primeira regra não for correspondente.

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 o 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 significa que todos os URLs serão excluídos do app.

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

Defina o escopo das regras dinâmicas corretamente

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

As regras dinâmicas declaradas no arquivo assetlinks.json só podem especificar regras para os hosts que você declara 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 isso, 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 um refinamento adicional, 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 se encaixam no escopo amplo definido no manifesto do app.

Declarar dynamic_app_link_components apenas uma vez

Para que as regras sejam processadas corretamente, 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 do app 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 anterior) 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 mesclam essas regras com as 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 é disponibilizado com o tipo de conteúdo application/json.
O arquivo assetlinks.json precisa ser acessível por uma conexão HTTPS, independentemente de os filtros de intent do app declararem HTTPS como o esquema de dados.
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, publique o arquivo assetlinks.json em cada domínio. Consulte Suporte à vinculação de apps para vários hosts.
Não publique o app com URLs de teste no arquivo de manifesto que talvez não estejam acessíveis ao público (como aqueles que só podem ser acessados com uma VPN). Uma solução alternativa nesses casos é configurar variantes de build para gerar um arquivo de manifesto diferente para builds de desenvolvimento.

Consulte os seguintes guias relacionados: