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

Para oferecer suporte aos links do app, crie um arquivo JSON 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 App Links dinâmicos no Android 15 ou mais recente, 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 sua 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 do app.

Declarar associações de site

É preciso publicar um arquivo JSON 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 arquivo build.gradle do app.
  • sha256_cert_fingerprints: as impressões digitais SHA256 do certificado de assinatura 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 a Assinatura de apps do Google Play no seu app, a impressão digital do certificado gerada ao executar keytool localmente geralmente não vai 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 do app na mesma página.

O seguinte arquivo de exemplo assetlinks.json concede direitos de abertura de links a um app para 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 mostra 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

Vários sites podem declarar associações com o 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 com o 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

Com os links dinâmicos do app no Android 15 e versões mais recentes, é possível usar regras de correspondência de links diretos do lado do servidor que funcionam com as regras definidas de forma estática no manifesto do app. É no arquivo assetlinks.json que você define as regras dinâmicas. Isso é 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 de Digital Asset Links chamada dynamic_app_link_components, que é onde você configura suas regras dinâmicas.
  • As regras dinâmicas podem incluir comparadores de padrões para parâmetros de caminho, fragmento e consulta.
  • Você também pode marcar qualquer comparador de padrões como excluído para que os URLs correspondentes não abram seu 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 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. Veja mais informações abaixo.

Declarar regras dinâmicas

Os Dynamic App Links 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 abrem 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 fragmentos
    • Chave: "#"
    • Valor: string única, expressão correspondente para o fragmento de URL
  • Correspondência de parâmetros de consulta
    • Chave: "?"
    • Valor: dicionário para corresponder a pares chave/valor nos parâmetros de consulta de 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 comparadores de padrões:

  • "*" corresponde a zero ou mais caracteres até que o caractere após o 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 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 correspondente a "/path1". A segunda regra, que impede a abertura do app por todos os URLs, será avaliada em segundo lugar, mas somente se a primeira regra não for uma correspondência.

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 Dynamic App Links no Android 15 e versões mais recentes, é importante definir o escopo delas adequadamente para que funcionem com 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 de forma estática no manifesto do app.

Por isso, recomendamos usar essa abordagem em todas as suas regras dinâmicas e estáticas:

  • No manifesto do app, defina regras com o escopo mais amplo possível, como declarando apenas esquema e domínio.
  • Conte com as regras dinâmicas do lado do servidor para mais refinamentos, como 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 encaixarão no amplo escopo definido no manifesto do app.

Para o processamento adequado das suas regras, declare apenas um objeto dynamic_app_link_components em todas as declarações de um determinado site, relação e app.

  • Procure várias declaraçõ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 do app, adicione suporte a Links dinâmicos do app diretamente no arquivo assetlinks.json atual. Os campos de relação para verificar seus App Links 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 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 Android 15 e versões mais recentes mesclam essas regras com as definidas no 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.
  • 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 Oferecer compatibilidade com links de app para diversos hosts.
  • Não publique seu app com URLs de teste no arquivo 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 build para gerar um arquivo de manifesto diferente para builds de desenvolvimento.

Consulte os seguintes guias relacionados: