Ir para o conteúdo

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 padrão da web (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 de internet padrão do usuário, que também pode estar configurado para redirecionar para a App Store ou Google Play Store, respectivamente.

De forma simples, os links universais permitem que um website associe suas páginas da web a telas específicas do app, de modo que, 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).

Esta tabela apresenta 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 vários sistemas operacionais móveis
Finalidade Vincula de forma integrada conteúdo da web e do app em dispositivos iOS e Android Vincula a conteúdos específicos 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 estiver instalado; caso contrário, abre o conteúdo da web Requer que o app esteja instalado

Casos de uso

Os links universais e os App Links são mais comumente usados em campanhas 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 o iOS quanto o Android exigem que um arquivo especial de permissões esteja hospedado no domínio do link. Esse arquivo contém definições de quais apps podem abrir links desse domínio e, no caso do iOS, quais caminhos esses apps podem 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 link o app pode abrir, configuradas dentro do próprio app:

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

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

Estas etapas foram adaptadas da documentação para desenvolvedores da 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 quiser. b. Insira o Bundle ID. Você pode encontrar o bundle ID na guia General do seu projeto Xcode para o build target adequado.

Etapa 1b: Ative os Associated Domains no seu app identifier

  1. No seu 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 que aquele onde você registrou o App Identifier.

  1. No Xcode, acesse a guia Capabilities do arquivo do 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 de domínio

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

Seção Associated Domains

Etapa 1e: Confirme que o arquivo de permissões está incluído no build

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 serve como uma forma 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:




{
  "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 especifica quais caminhos são incluídos ou excluídos da associação. Você pode usar NOT antes do caminho para desativá-lo. Neste exemplo, todos os links nesse caminho irão para a web em vez de abrir o app. Você pode usar * como 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 seu 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 suportados pelo seu app.
  2. Atualize o app delegate para responder adequadamente ao receber o objeto NSUserActivity.

No Xcode, abra a seção Associated Domains na guia Capabilities e adicione uma entrada para cada domínio que seu app suporta, prefixada 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, precisará puxar o website para baixo manualmente para que um prompt apareça no topo perguntando se deseja abrir o app correspondente.

Estas etapas foram adaptadas da documentação para desenvolvedores do 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 seu 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 em 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 seu arquivo AndroidManifest.xml, adicione um elemento meta-data dentro do elemento application. O elemento meta-data deve ter um atributo android:name com o 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 tratar 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 mensagens ou e-mail e clique nele. Se tudo estiver configurado corretamente, o app deverá 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 nos 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á fazer 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 ajuda 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 no seu AASA ou AndroidManifest para tratar apenas links com /uni/ no caminho da URL como links universais.
  2. Adicione o atributo universal="true" à tag de âncora (<a>) do seu link. Isso altera o caminho da URL do link envolvido para incluir /uni/.

Por exemplo:




<a href=”https://www.example.com” universal="true">
  1. Certifique-se de que seu app está configurado para lidar com os links envolvidos corretamente. Consulte o artigo do SendGrid sobre Resolving SendGrid Click Tracking Links e siga as etapas para o seu sistema operacional. Este artigo contém exemplos de código 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 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 de âncora do seu link: data-msys-sublink="custom_path".

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

Por exemplo:




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

Em seguida, certifique-se de que seu app está configurado para lidar com o caminho personalizado corretamente. Consulte o artigo do SparkPost sobre Using SparkPost click tracking on deep links. Este artigo contém exemplos de código 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 nos 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 do dispositivo (por exemplo, páginas de produtos, programas de fidelidade, links de cancelamento de inscrição ou páginas de termos 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 de â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:




<!-- 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 seus caminhos personalizados sigam estes requisitos:

  • Formato: Apenas caracteres alfanuméricos, pontos, sublinhados e hifens
  • Comprimento: 1–32 caracteres
  • Diferenciação entre maiúsculas e minúsculas: Os caminhos diferenciam maiúsculas de minúsculas para atender aos requisitos dos sistemas operacionais móveis
  1. Confirme que suas URLs de rastreamento envolvidas incluem o segmento de caminho personalizado. Sem o atributo, os 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 seu domínio de rastreamento de cliques para que os caminhos correspondam a /CL1/{customPath}/.

iOS (Apple App Site Association):




{
  "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):




[{
  "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 filtro de intent do seu AndroidManifest.xml para cada caminho personalizado que seu app deve lidar.

Certifique-se de que seu app está configurado para lidar com esses links envolvidos. Adicione seu domínio de rastreamento de cliques aos domínios associados do app (iOS) ou filtros de intent (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 à mensagem de e-mail para o editor de HTML ou a um bloco HTML para o 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 desta forma:

<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" desta forma:

<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 desta forma:

<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 para e-mail, insira seu código HTML como um atributo personalizado se o seu 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:

  • Name: clicktracking
  • Value: off

SparkPost

Selecione o seguinte para o atributo personalizado:

  • Name: data-msys-clicktrack
  • Value: 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:

  • Name: clicktracking
  • Value: off
  • Type: Link

SparkPost

Selecione o seguinte para o atributo personalizado:

  • Name: data-msys-clicktrack
  • Value: 0
  • Type: Link

Um atributo personalizado para um botão.

Se seus links universais não estão funcionando como esperado nos seus e-mails, como navegar o destinatário do app de e-mail para o navegador web antes de finalmente redirecionar para o app, consulte estas dicas para solucionar problemas com sua configuração de links universais.

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

O Outlook pode exibir texto de call-to-action como [?it= ou 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 exibe o texto do atributo em vez disso. Confirme que cada botão, link de imagem e URL rastreada usa um destino https:// (ou http://) completo. Isso se aplica tanto a links universais quanto a links web padrão.

Certifique-se de que o arquivo AASA (iOS) ou Digital Asset Links (Android) está no local 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 ser que tenha pulado uma etapa na configuração dos links universais para e-mail.

Verifique as definições de domínio

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

  • iOS: Revise os Associated Domains configurados no Xcode para o seu app (Etapa 1c: ativar 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 toque 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 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 estão correspondendo ao domínio inteiro (por exemplo, * ou /*).

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

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

Em alguns casos, 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 apontem diretamente para o seu domínio principal (onde você pode hospedar o arquivo AASA ou Digital Asset Links). Note que esse método pode causar perda de análise de dados de cliques para esses links específicos. Consulte Desativando o rastreamento de cliques link a link para instruções.
  • Colocar uma CDN à frente do subdomínio de rastreamento: Se você precisa de cobertura total de rastreamento de cliques e deep linking, é possível colocar uma rede de distribuição de conteúdo (CDN) (como Cloudflare ou CloudFront) à frente do seu subdomínio de rastreamento. Configure a CDN para servir os arquivos .well-known localmente e redirecionar 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ção inconsistente entre espaços de trabalho pode fazer com que os links se comportem de forma diferente, mesmo ao usar os mesmos modelos de e-mail e arquivos AASA ou Digital Asset Links.

Para verificar sua 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 em que os links não estão funcionando.

Se o domínio de envio é diferente entre os 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.

Os atributos de desativação por link se aplicam apenas às tags de âncora HTML específicas onde você os adiciona. Causas comuns quando um link ainda aparece rastreado:

  • Atributo ausente no código-fonte HTML — Confirme que clicktracking=off (SendGrid), data-msys-clicktrack="0" (SparkPost) ou ses:no-track (Amazon SES) está na tag <a> no código-fonte do editor de HTML, não apenas na prévia.
  • Atributos personalizados do editor de arrastar e soltar — Para o editor de arrastar e soltar, verifique se o nome e o valor do atributo personalizado do link correspondem ao seu provedor de serviços de e-mail (consulte Desativando o rastreamento de cliques link a link).
  • URLs no corpo em texto simples — Se você testa links na parte de texto simples da mensagem, essas URLs podem não herdar os atributos de desativação exclusivos do HTML. Envie uma mensagem de teste e inspecione o e-mail bruto para confirmar qual parte contém o link envolvido.

Documentação da plataforma de engajamento do cliente Braze.

Recursos
Jurídico
Empresa
© 2026 Braze, Inc. Todos os direitos reservados.
Verificando o status do Braze
New Stuff!