Skip to content

Links universais e App Links

Este artigo descreve como configurar links universais da Apple e Android App Links.

Os links universais da Apple e os Android App Links são mecanismos criados para proporcionar uma transição fluida entre conteúdo web e apps móveis. Enquanto os links universais são específicos do iOS, os Android App Links servem ao mesmo propósito para aplicativos Android.

Links universais (iOS) e App Links (Android) são links da web padrão (http://mydomain.com) que apontam tanto para uma página da web quanto para um conteúdo dentro de um app.

Quando um link universal ou App Link é aberto, o sistema operacional verifica se algum app instalado está registrado para aquele domínio. Se um app for encontrado, ele é aberto imediatamente, sem nunca carregar a página da web. Se nenhum app for encontrado, a URL da web é carregada no navegador web padrão do usuário, que também pode estar configurado para redirecionar para a App Store ou Google Play Store, respectivamente.

Em termos simples, os links universais permitem que um website associe suas páginas da web a telas específicas do app. Então, quando um usuário clica em um link para uma página da web que corresponde a uma tela do app, o app pode ser aberto diretamente (se estiver instalado no momento).

Esta tabela descreve as principais diferenças entre links universais e deep links tradicionais:

  Links universais e App Links Deep links
Compatibilidade de plataforma iOS (versão 9 e posterior) e Android (versão 6.0 e posterior) Usado em diversos sistemas operacionais móveis
Finalidade Conectar conteúdo da web e do app de forma integrada em dispositivos iOS e Android Direcionar para conteúdo específico do app
Função Direciona para páginas da web ou conteúdo do app com base no contexto Abre telas específicas do app
Instalação do app Abre o app se ele estiver instalado; caso contrário, abre o conteúdo da web Requer que o app esteja instalado

Casos de uso

Links universais e App Links são mais comumente usados em Campaigns de e-mail, já que os e-mails podem ser abertos e clicados tanto em dispositivos desktop quanto em dispositivos móveis.

Alguns canais não funcionam bem com esses links. Por exemplo, notificações por push, mensagens no app e Content Cards devem usar deep links baseados em esquema (mydomain://).

Pré-requisitos

Para usar links universais e App Links:

  • Seu website deve ser acessível via HTTPS
  • Seu app deve estar disponível na App Store (iOS) ou Google Play Store (Android)

Para que os apps ofereçam suporte a links universais ou App Links, tanto iOS quanto Android exigem que um arquivo de permissões especial seja hospedado no domínio do link. Esse arquivo contém definições de quais apps podem abrir links daquele domínio e, no caso do iOS, quais caminhos esses apps têm permissão para abrir:

  • iOS: Arquivo Apple App Site Association (AASA)
  • Android: Arquivo Digital Asset Links

Além desse arquivo de permissões, existem definições codificadas de quais domínios de links o app tem permissão para abrir, configuradas dentro do próprio app:

  • iOS: Definidos como “Associated Domains” no Xcode
  • Android: Definidos no arquivo AndroidManifest.xml do app

Essa associação bidirecional entre domínio e app é necessária para que um link universal ou App Link funcione, impedindo que qualquer app se apodere de links de um domínio específico ou que qualquer domínio abra um app específico.

Essas etapas foram adaptadas da documentação do desenvolvedor Apple. Para saber mais, consulte Allowing apps and websites to link to your content.

Etapa 1: Configure as permissões do seu app

Etapa 1a: Registre seu app

  1. Acesse developer.apple.com e faça login.
  2. Clique em Certificates, Identifiers & Profiles.
  3. Clique em Identifiers.
  4. Se você ainda não tiver um App Identifier registrado, clique em + para criar um. a. Insira um Name. Pode ser o que você quiser. b. Insira o Bundle ID. Você pode encontrar o Bundle ID na guia General do seu projeto no Xcode para o build target correto.

Etapa 1b: Ative os Associated Domains no identificador do seu app

  1. No App Identifier existente ou recém-criado, localize a seção App Services.
  2. Selecione Associated Domains.
  3. Clique em Save.

Seção App Services

Etapa 1c: Ative os Associated Domains no seu projeto Xcode

Antes de prosseguir, verifique se o seu projeto Xcode tem o mesmo time selecionado em que você acabou de registrar o App Identifier.

  1. No Xcode, acesse a guia Capabilities do arquivo do seu projeto.
  2. Ative Associated Domains.
Dica de solução de problemas

Se você vir o erro “An App ID with Identifier ‘your-app-id’ is not available. Please enter a different string”, faça o seguinte:

  1. Verifique se o time correto está selecionado.
  2. Verifique se o Bundle ID (etapa 1a) do seu projeto Xcode corresponde ao usado para registrar o App Identifier.

Etapa 1d: Adicione a permissão do domínio

Na seção de domínios, adicione a tag de domínio apropriada. Você deve prefixá-la com applinks:. Neste caso, você pode ver que adicionamos applinks:yourdomain.com.

Seção Associated Domains

Etapa 1e: Confirme que o arquivo de permissões está incluído na compilação

No navegador do projeto, verifique se o novo arquivo de permissões está selecionado em Target Membership.

O Xcode deve fazer isso automaticamente.

Etapa 2: Configure seu website para hospedar o arquivo AASA

Para associar o domínio do seu website ao seu app nativo no iOS, você precisa hospedar o arquivo Apple App Site Association (AASA) no seu website. Esse arquivo funciona como uma maneira segura de verificar a propriedade do domínio para o iOS. Antes do iOS 9, os desenvolvedores podiam registrar qualquer esquema de URI para abrir seus apps, sem nenhuma verificação. No entanto, com o AASA, esse processo se tornou muito mais seguro e confiável.

O arquivo AASA contém um objeto JSON com uma lista de apps e os caminhos de URL no domínio que devem ser incluídos ou excluídos como links universais. Veja um exemplo de arquivo AASA:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "JHGFJHHYX.com.facebook.ios",
        "paths": [
          "*"
        ]
      }
    ]
  }
}
  • appID: Construído combinando o Team ID do seu app (acesse https://developer.apple.com/account/#/membership/ para obter o Team ID) e o Bundle Identifier. Neste exemplo, “JHGFJHHYX” é o Team ID e “com.facebook.ios” é o Bundle ID.
  • paths: Array de strings que especificam quais caminhos são incluídos ou excluídos da associação. Você pode usar NOT antes do caminho para desativar caminhos. Neste exemplo, todos os links nesse caminho irão para a web em vez de abrir o app. Você pode usar * como caractere curinga para ativar todos os caminhos em um diretório e ? para corresponder a um único caractere (como /archives/201?/ para corresponder a todos os números de 2010 a 2019).

Etapa 3: Hospede o arquivo AASA no seu domínio

Quando o arquivo AASA estiver pronto, você pode hospedá-lo no seu domínio em https://<<yourdomain>>/apple-app-site-association ou em https://<<yourdomain>>/.well-known/apple-app-site-association.

Faça o upload do arquivo apple-app-site-association para o seu servidor web HTTPS. Você pode colocar o arquivo na raiz do servidor ou no subdiretório .well-known. Não adicione .json ao nome do arquivo.

Ao hospedar o arquivo AASA, verifique se o arquivo segue estas diretrizes:

  • É servido via HTTPS.
  • Usa o tipo MIME application/json.
  • Não excede 128 KB (requisito a partir do iOS 9.3.1)

Quando um usuário toca em um link universal em um dispositivo iOS, o dispositivo inicia o app e envia a ele um objeto NSUserActivity. O app pode então consultar o objeto NSUserActivity para determinar como foi iniciado.

Para oferecer suporte a links universais no seu app, siga estas etapas:

  1. Adicione uma permissão que especifique os domínios com os quais seu app é compatível.
  2. Atualize o app delegate para responder adequadamente quando receber o objeto NSUserActivity.

No Xcode, abra a seção Associated Domains na guia Capabilities e adicione uma entrada para cada domínio com o qual seu app é compatível, prefixado com applinks:. Por exemplo, applinks:www.mywebsite.com.

Adicione o link universal a um e-mail e envie-o para um dispositivo de teste. Colar um link universal diretamente no campo de URL do Safari não fará com que o app abra automaticamente. Se você fizer isso, terá que puxar manualmente o website para baixo para que um prompt apareça no topo perguntando se deseja abrir o app correspondente.

Essas etapas foram adaptadas da documentação do desenvolvedor Android. Para saber mais, consulte Add Android App Links e Create Deep Links to App Content.

Primeiro, você precisa criar deep links para o seu app Android. Isso pode ser feito adicionando intent filters no arquivo AndroidManifest.xml. O intent filter deve incluir a ação VIEW e a categoria BROWSABLE, junto com a URL do seu website no elemento de dados.

Etapa 2: Associe seu app ao seu website

Você precisa associar seu app ao seu website. Isso pode ser feito criando um arquivo Digital Asset Links. Esse arquivo deve estar no formato JSON e inclui detalhes sobre os apps Android que podem abrir links para o seu website. Ele deve ser colocado no diretório .well-known do seu website.

Etapa 3: Atualize o arquivo de manifesto do seu app

No arquivo AndroidManifest.xml, adicione um elemento meta-data dentro do elemento application. O elemento meta-data deve ter um atributo android:name com valor “asset_statements” e um atributo android:resource que aponte para um arquivo de recurso com um array de strings que inclua a URL do seu website.

No seu app Android, você precisa lidar com os deep links recebidos. Isso pode ser feito obtendo o intent que iniciou sua activity e extraindo os dados dele.

Por fim, você pode testar seus deep links. Envie um link para si mesmo por meio de um app de envio de mensagens ou e-mail e clique nele. Se tudo estiver configurado corretamente, o app deve ser aberto.

Nossos parceiros de envio de e-mail usam domínios de rastreamento de cliques para envolver todos os links e incluir parâmetros de URL para rastreamento de cliques em e-mails da Braze.

Por exemplo, um link como https://www.example.com se torna algo como https://links.email.example.com/uni/wf/click?upn=abcdef123456….

Para permitir que links de e-mail com rastreamento de cliques funcionem como links universais ou App Links, você precisará realizar algumas configurações adicionais. Certifique-se de adicionar o domínio de rastreamento de cliques (links.email.example.com) como um domínio que o app tem permissão para abrir. Além disso, o domínio de rastreamento de cliques deve servir os arquivos AASA (iOS) ou Digital Asset Links (Android). Isso ajudará a garantir que os links de e-mail com rastreamento de cliques funcionem perfeitamente.

Se você não quiser que todos os links de rastreamento de cliques sejam links universais ou App Links, é possível especificar quais links devem ser links universais com base no parceiro de envio de e-mail. Consulte as guias a seguir para mais detalhes.

Para tratar um link de rastreamento de cliques do SendGrid como um link universal:

  1. Configure os valores de pathPrefix do AASA ou AndroidManifest para tratar apenas links com /uni/ no caminho da URL como links universais.
  2. Adicione o atributo universal="true" à tag âncora (<a>) do seu link. Isso altera o caminho da URL do link envolvido para incluir /uni/.

Por exemplo:

1

<a href=”https://www.example.com” universal="true">
  1. Certifique-se de que o seu app está configurado para lidar corretamente com os links envolvidos. Consulte o artigo do SendGrid sobre Resolving SendGrid Click Tracking Links e siga as etapas para o seu sistema operacional. Este artigo contém código de exemplo para iOS e Android.

Com essa configuração, links com /uni/ no caminho da URL funcionarão como links universais, enquanto todos os outros links funcionarão como links da web.

Para tratar um link de rastreamento de cliques do SparkPost como um link universal, adicione o seguinte atributo na seção de Atributos do editor de arrastar e soltar para e-mail, ou edite manualmente o HTML do link para incluir o seguinte atributo na tag âncora do seu link: data-msys-sublink="custom_path".

Esse caminho personalizado permite que você trate seletivamente URLs com esse valor como um link universal.

Por exemplo:

1

<a href=”https://www.example.com” data-msys-sublink="open-in-app">

Em seguida, certifique-se de que o seu app está configurado para lidar corretamente com o caminho personalizado. Consulte o artigo do SparkPost sobre Using SparkPost click tracking on deep links. Este artigo contém código de exemplo para iOS e Android.

Use caminhos personalizados para adicionar segmentos de caminho às URLs de rastreamento de cliques de e-mail. Isso cria padrões de URL previsíveis que os sistemas operacionais móveis podem reconhecer para links universais e App Links.

Quando os usuários tocam em links de e-mail em dispositivos móveis, os caminhos personalizados ajudam a controlar se os links abrem no app móvel principal, em um app especializado ou no navegador móvel (por exemplo, páginas de produtos, programas de fidelidade, links de cancelamento de inscrição ou páginas legais).

Para tratar um link de rastreamento de cliques do Amazon SES como um link universal ou App Link:

  1. Adicione atributos ses:custom-path às suas tags âncora no HTML do e-mail, ou adicione o atributo na seção Atributos do editor de arrastar e soltar para e-mail. O caminho personalizado é inserido na URL de rastreamento de cliques envolvida.

Por exemplo:

1
2
3
4
5
6
7
8

<!-- Opens main shopping app -->
<a href="https://yourstore.com/product" ses:custom-path="shop">Shop Now</a>
<!-- Opens loyalty app -->
<a href="https://yourstore.com/rewards" ses:custom-path="rewards">My Rewards</a>
<!-- Opens specialized app -->
<a href="https://yourstore.com/limited" ses:custom-path="limited">Limited Edition</a>
<!-- Stays in browser -->
<a href="https://yourstore.com/unsubscribe" ses:no-track>Unsubscribe</a>

Certifique-se de que os seus caminhos personalizados seguem estes requisitos:

  • Formato: Apenas caracteres alfanuméricos, pontos, underscores e hifens
  • Comprimento: 1 a 32 caracteres
  • Sensibilidade a maiúsculas e minúsculas: Os caminhos diferenciam maiúsculas de minúsculas para atender aos requisitos do sistema operacional móvel
  1. Confirme que as suas URLs de rastreamento envolvidas incluem o segmento de caminho personalizado. Sem o atributo, links rastreados usam track.yourstore.com/CL0/{encodedUrl}/.... Com o atributo, eles seguem este formato: track.yourstore.com/CL1/{customPath}/{encodedUrl}/...

Por exemplo:

  • track.yourstore.com/CL1/shop/...
  • track.yourstore.com/CL1/rewards/...
  1. Configure seus arquivos de associação de site no domínio de rastreamento de cliques para que os caminhos correspondam a /CL1/{customPath}/.

iOS (Apple App Site Association):

1
2
3
4
5
6
7
8
9
10
11
12

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.yourcompany.mainapp",
      "paths": ["/CL1/shop/*", "/CL1/rewards/*"]
    }, {
      "appID": "TEAMID.com.yourcompany.limitedapp",
      "paths": ["/CL1/limited/*"]
    }]
  }
}

Android (Digital Asset Links):

1
2
3
4
5
6
7
8

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.mainapp",
    "sha256_cert_fingerprints": ["..."]
  }
}]

O Android faz a correspondência de caminhos no seu app, e não no assetlinks.json. Defina android:pathPrefix="/CL1/{customPath}/" no intent filter do seu AndroidManifest.xml para cada caminho personalizado que o seu app manipula.

Certifique-se de que o seu app está configurado para lidar com esses links envolvidos. Adicione o domínio de rastreamento de cliques aos domínios associados do seu app (iOS) ou intent filters (Android), e hospede o arquivo AASA ou Digital Asset Links nesse domínio conforme descrito anteriormente neste artigo.

Você pode desativar o rastreamento de cliques para links específicos adicionando código HTML à sua mensagem de e-mail no editor de HTML ou a um bloco HTML no editor de arrastar e soltar.

SendGrid

Se o seu provedor de serviços de e-mail é o SendGrid, use o código HTML clicktracking=off assim:

<a clicktracking=off href="[INSERT https LINK HERE]">click here</a>

SparkPost

Se o seu provedor de serviços de e-mail é o SparkPost, use o código HTML data-msys-clicktrack="0" assim:

<a data-msys-clicktrack="0" href="[INSERT https LINK HERE]">click here</a>

Amazon SES

Se o seu provedor de serviços de e-mail é o Amazon SES, use o código HTML ses:no-track assim:

<a ses:no-track href="[INSERT https LINK HERE]">click here</a>

Editor de arrastar e soltar

Ao usar o editor de arrastar e soltar de e-mail, insira o código HTML como um atributo personalizado se o link estiver vinculado a um texto, botão ou imagem.

Atributo personalizado para um link de texto

SendGrid

Selecione o seguinte para o atributo personalizado:

  • Nome: clicktracking
  • Valor: off

SparkPost

Selecione o seguinte para o atributo personalizado:

  • Nome: data-msys-clicktrack
  • Valor: 0

Um atributo personalizado para um link de texto.

Atributo personalizado para um botão ou imagem

SendGrid

Selecione o seguinte para o atributo personalizado:

  • Nome: clicktracking
  • Valor: off
  • Tipo: Link

SparkPost

Selecione o seguinte para o atributo personalizado:

  • Nome: data-msys-clicktrack
  • Valor: 0
  • Tipo: Link

Um atributo personalizado para um botão.

Se os seus links universais não estiverem funcionando conforme o esperado nos seus e-mails, como quando o destinatário é direcionado do app de e-mail para o navegador antes de ser redirecionado para o app, consulte estas dicas para solucionar problemas na configuração dos seus links universais.

O Outlook mostra [?it= ou texto de URL bruto em vez de um botão

O Outlook pode exibir texto de chamada para ação como [?it= ou exibir parte do href quando um link não usa um esquema de URL válido http:// ou https://. Esquemas personalizados, esquemas ausentes ou URLs malformadas não são tratados como hiperlinks, então o cliente mostra o texto do atributo. Confirme que cada botão, link de imagem e URL rastreada usa um destino completo https:// (ou http://). Isso se aplica tanto a links universais quanto a links da web padrão.

Certifique-se de que o arquivo AASA (iOS) ou o arquivo Digital Asset Links (Android) está localizado no lugar correto:

  • iOS: https://click.tracking.domain/.well-known/apple-app-site-association
  • Android: https://click.tracking.domain/.well-known/assetlinks.json

É importante garantir que esses arquivos estejam sempre acessíveis publicamente. Se você não conseguir acessá-los, pode ter pulado uma etapa na configuração de links universais para e-mail.

Verifique as definições de domínio

Certifique-se de que as definições corretas estão configuradas para os domínios que o seu app tem permissão para abrir.

  • iOS: Revise os Associated Domains configurados no Xcode para o seu app (Etapa 1c: Ative Associated Domains no seu projeto Xcode). Verifique se o domínio de rastreamento de cliques está incluído nessa lista.
  • Android: Abra a página de informações do app (pressione e segure o ícone do app e clique em ⓘ). No menu de informações do app, localize Abrir por padrão e toque nessa opção. Deve aparecer uma tela com todos os links verificados que o app tem permissão para abrir. Verifique se o domínio de rastreamento de cliques está incluído nessa lista.

Se todos os links de um e-mail abrem o seu app, incluindo links que você espera que abram no navegador, os valores de paths do AASA (iOS) ou pathPrefix do Android no seu domínio de rastreamento de cliques correspondem ao domínio inteiro (por exemplo, * ou /*).

Limite esses padrões às URLs que devem abrir o app. Para o SendGrid, faça a correspondência com /uni/ e adicione universal="true" apenas nesses links. Consulte Links universais, App Links e rastreamento de cliques.

O domínio de rastreamento não consegue servir arquivos .well-known

Em alguns casos, o seu domínio de rastreamento de cliques pode não conseguir hospedar os arquivos .well-known necessários devido a limitações do provedor de serviços de e-mail ou restrições de infraestrutura. Se você não conseguir hospedar o arquivo AASA ou Digital Asset Links no seu domínio de rastreamento, considere as seguintes opções:

  • Desativar seletivamente o rastreamento de cliques em URLs de deep link: Você pode desativar o rastreamento de cliques para links universais específicos para que eles vão diretamente ao seu domínio principal (onde é possível hospedar o arquivo AASA ou Digital Asset Links). Observe que este método pode causar perda de análise de dados de cliques para esses links específicos. Consulte Desativando o rastreamento de cliques link por link para instruções.
  • Colocar uma rede de distribuição de conteúdo (CDN) na frente do subdomínio de rastreamento: Se você precisa de cobertura completa de rastreamento de cliques e deep linking, pode colocar uma CDN (como Cloudflare ou CloudFront) na frente do seu subdomínio de rastreamento. Configure a CDN para servir os arquivos .well-known localmente e fazer proxy de todo o restante do tráfego para o seu provedor de serviços de e-mail. Essa abordagem é mais complexa, mas oferece controle total sobre rastreamento de cliques e links universais.

Se links universais ou App Links funcionam corretamente no seu espaço de trabalho de Produção, mas falham no espaço de trabalho de Desenvolvimento ou Teste, verifique se o domínio do endereço de e-mail de envio corresponde ao domínio de rastreamento configurado nas configurações de e-mail de cada espaço de trabalho. Configurações inconsistentes entre espaços de trabalho podem fazer com que links se comportem de maneira diferente, mesmo usando os mesmos modelos de e-mail e arquivos AASA ou Digital Asset Links.

Para verificar a configuração de e-mail:

  1. Acesse Configurações > Preferências de e-mail no dashboard da Braze.
  2. Revise as Configurações de e-mail de saída em Configuração de envio.
  3. Confirme que o domínio de envio e o domínio de rastreamento estão devidamente alinhados para o espaço de trabalho onde os links não estão funcionando.

Se o domínio de envio difere entre espaços de trabalho, certifique-se de que cada espaço de trabalho tenha os registros DNS apropriados configurados e que os arquivos AASA (iOS) ou Digital Asset Links (Android) estejam acessíveis a partir de cada domínio de rastreamento.
New Stuff!