Android App Links

Filtros de Intent, assetlinks.json e links verificados - o guia do Android para abrir URLs https:// diretamente no seu app Expo SDK 57 sem a folha de desambiguação "Abrir com".

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// app.config.ts
export default {
  expo: {
    android: {
      package: "com.example.shopapp",
      intentFilters: [
        {
          action: "VIEW",
          autoVerify: true,
          data: [
            {
              scheme: "https",
              host: "shop.example.com",
              pathPrefix: "/orders",
            },
          ],
          category: ["BROWSABLE", "DEFAULT"],
        },
      ],
    },
  },
};

// https://shop.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.shopapp",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:10:D4:4A:8F:D8:00:6F:8F:95:34:E7:6B:58"
      ]
    }
  }
]

Quando usar isso:

• Links de marketing do Android devem pular o seletor de app/navegador.
• Você já hospeda o AASA do iOS no mesmo domínio - adicione assetlinks.json ao lado dele.
• Notificações push e e-mails usam caminhos https://shop.example.com/....
• Você precisa de paridade com os Universal Links do iOS no Android.

Exemplo de Trabalho

Configuração completa de verificação para https://shop.example.com/orders/*.

Passo 1 - Filtros de Intent em app.config.ts

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  scheme: "shopapp",
  android: {
    package: "com.example.shopapp",
    intentFilters: [
      {
        action: "VIEW",
        autoVerify: true,
        data: [
          {
            scheme: "https",
            host: "shop.example.com",
            pathPrefix: "/orders",
          },
          {
            scheme: "https",
            host: "shop.example.com",
            pathPrefix: "/product",
          },
        ],
        category: ["BROWSABLE", "DEFAULT"],
      },
    ],
  },
  ios: {
    bundleIdentifier: "com.example.shopapp",
    associatedDomains: ["applinks:shop.example.com"],
  },
};
 
export default config;

Passo 2 - Hospede assetlinks.json

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.shopapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

Sirva em: https://shop.example.com/.well-known/assetlinks.json

Passo 3 - Obtenha a impressão digital SHA-256

# Play Console → Integridade do App → Certificado da chave de assinatura do app → SHA-256
# Keystore de depuração local (apenas builds de desenvolvimento):
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

• A verificação de produção usa o certificado do Play App Signing - não sua chave de upload.
• Adicione as impressões digitais de depuração e de lançamento ambas durante o desenvolvimento para que os builds internos verifiquem.

Passo 4 - Construa e teste

npx expo prebuild --platform android
npx expo run:android
adb shell am start -a android.intent.action.VIEW -d "https://shop.example.com/orders/42" com.example.shopapp

Passo 5 - Verifique o status da verificação

adb shell pm get-app-links com.example.shopapp

Procure por shop.example.com: verified - none ou legacy_failure significa que o host ou a impressão digital precisam ser corrigidos.

O que isso demonstra:

• autoVerify: true dispara a verificação de domínio no momento da instalação.
• pathPrefix limita quais URLs o app reivindica.
• assetlinks.json vincula o nome do pacote ao certificado de assinatura.
• Comandos adb para testes rápidos em emuladores.
• pm get-app-links para diagnósticos de verificação.

Mergulho Profundo

Como Funciona

• Na instalação/atualização, o Android busca o assetlinks.json para cada host nos filtros de intent com autoVerify.
• O sistema compara o SHA-256 do certificado de assinatura do seu app com a entrada JSON.
• Links verificados abrem seu app diretamente; falha na verificação exibe um seletor ou navegador.
• Vários apps podem declarar o mesmo host - o app verificado vence; caso contrário, o usuário escolhe.
• Esquemas personalizados (shopapp://) ignoram a verificação - ainda úteis para desenvolvimento e OAuth.

Campos de intentFilters

Valores de Status de Verificação

Notas do Android

# Reexecuta a verificação após corrigir assetlinks.json (Android 12+)
adb shell pm verify-app-links --re-verify com.example.shopapp

• Redirecionamentos HTTP em assetlinks.json quebram a verificação - sirva 200 na URL exata.
• Content-Type deve ser application/json.
• android:launchMode na atividade principal afeta o back-stack - singleTask é comum para apps de deep-link.

Armadilhas

• Impressão digital SHA-256 incorreta - falha mais comum; o certificado do Play App Signing difere da chave de upload local. Correção: copie a impressão digital do Play Console → Integridade do App.
• Build de depuração em assetlinks de produção - certificado de depuração não listado. Correção: adicione a impressão digital de depuração ao array JSON durante o desenvolvimento.
• autoVerify: true ausente - o filtro funciona, mas exibe o seletor. Correção: defina autoVerify e reinstale o app.
• pathPrefix muito amplo - / reivindica o site inteiro, incluindo o blog. Correção: restrinja para /orders, /product.
• Configuração do Expo não aplicada - editou app.config.ts, mas executou um APK antigo. Correção: npx expo prebuild --clean e depois reconstrua.
• Testando apenas com shopapp:// - App Links são apenas HTTPS. Correção: teste URLs https:// com o comando de intent adb.

Alternativas

FAQs

Relacionados

• Noções Básicas de Deep Linking - visão geral de esquemas e hosts
• Universal Links do iOS - AASA no mesmo domínio
• API expo-linking - análise de URL após entrega de intent
• Matriz de Teste de Deep Link - matriz de emuladores e dispositivos Android
• ../expo-router/expo-router-basics/expo-router-basics.md - mapeamento de rotas
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - checklist de revisão de roteamento

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).