Visão geral

Implemente deep linking e deferred deep linking para os tracking links da Singular, para que os usuários passem de forma fluida de uma campanha para uma tela específica do seu app.

Um deep link é um link clicável que abre um conteúdo específico dentro de um app. Há dois cenários a serem suportados:

• Deep link (direto): o usuário já tem o app instalado. Ele toca em um Singular Link e o app abre diretamente no conteúdo certo.
• Deferred deep link (DDL): o usuário ainda não tem o app. Ele toca no link, instala pela loja e, na primeira abertura, o app ainda o direciona para o conteúdo pretendido.

Com uma integração via SDK, a Singular cuida da maior parte disso automaticamente. Em uma integração server-to-server (S2S) não há SDK no dispositivo, então sua equipe fica responsável por duas tarefas extras: passar para a Singular o deep link que seu app recebeu e ler o deferred deep link que a Singular retorna e direcionar o usuário. Ambos passam pelo endpoint SESSION:

GET https://s2s.singular.net/api/v1/launch

Recursos: FAQ de Deep Linking | FAQ de Singular Links

As três configurações em resumo

Etapa 1: Configuração no nível do app

Antes que qualquer deep link possa funcionar, os Singular Links precisam ser reconhecidos pelo SO como iOS Universal Links e Android App Links, para que tocar em um link abra seu app em vez de um navegador. Esquemas de app URI tradicionais são suportados como fallback.

Siga os guias de configuração canônicos para os passos detalhados de cada plataforma e, em seguida, confirme que cada item abaixo está concluído. Os passos detalhados estão em Pré-requisitos de Singular Links e Como configurar Deep Links . O checklist aqui fornece a ordem obrigatória e os pontos que as equipes mais costumam esquecer.

Checklist de configuração:

1. Adicione um subdomínio de link em Attribution > Manage Links > Manage Link Domains (por exemplo yourbrand.sng.link ). Este é o host que seus Singular Links usam.
2. iOS — Universal Links: habilite a capability Associated Domains para applinks:yourbrand.sng.link e, em seguida, copie seu App Prefix / Team ID do Apple Developer Portal para Settings > Apps > [iOS app] > Show Advanced Settings . Opcionalmente, registre um fallback de app-scheme como um URL Type no Xcode.
3. Android — App Links: gere seus fingerprints de assinatura SHA-256 (Play Console para produção, keytool para debug), adicione um intent filter autoVerify para seu domínio Singular ao AndroidManifest.xml e, em seguida, cole o fingerprint em Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints .
4. Defina os deep links em Attribution > Manage Links > Create Link (consulte o mapeamento de campos abaixo).

Mapeando os campos de redirecionamento do Manage Links

Quando você cria o link, três campos de redirecionamento mapeiam diretamente para os três conceitos de deep link usados depois na API:

Repasse ao desenvolvedor: a engenharia deve fornecer o(s) esquema(s) de deep link por plataforma e a lista de URLs de destino (por exemplo myapp://autumnfashion ).

Etapa 2: SESSION (entrada) — envie o deep link para a Singular

Quando o app abre a partir de um Singular Link, capture a URL de abertura completa e envie-a para a Singular na requisição SESSION no parâmetro openuri (URL-encoded). É assim que a Singular atribui a sessão ao link e reporta o resultado do deep link. Obrigatório ao usar Singular Links.

Parâmetros do Singular Link carregados na URL

Capture a URL de abertura no app

O app precisa de um código handler que receba a URL de abertura e a encaminhe para seu servidor, para inclusão na requisição SESSION.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

Envie a requisição SESSION com openuri

A partir do seu servidor, inclua a URL capturada (URL-encoded) como openuri :

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

Resolução de short link

Se o usuário abriu um Singular Link encurtado, envie também singular_link_resolve_required=true . A Singular retorna o link longo expandido para que você possa fazer o parse do deep link e dos valores de passthrough.

Resposta de exemplo:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Parâmetros de passthrough dinâmico

Se sua organização configurou passthrough dinâmico para um link, a URL do deep link inclui o parâmetro _p com uma string JSON URL-encoded ou uma string não estruturada para roteamento de conteúdo. Consulte Parâmetros de Passthrough Dinâmico .

Referência: Referência da API do Endpoint SESSION (Parâmetros de Deep Linking).

Etapa 3: SESSION (saída) — repasse o deferred deep link para o app

Para um usuário que instala o app após tocar no link, o deferred deep link é retornado pela Singular na resposta SESSION na primeira sessão após a instalação. Seu servidor deve repassar esse valor de volta ao app para que ele possa direcionar o usuário.

Solicite o DDL na primeira sessão

Na primeira requisição SESSION após uma instalação, adicione estes dois parâmetros:

Requisição SESSION de exemplo (install + DDL habilitado):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

Leia a resposta e repasse-a para o app

Se a instalação veio de um tracking link que carrega um deferred deep link, a Singular retorna:

Resposta SESSION de exemplo:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

Testes e validação

• Deferred deep link: em um dispositivo sem o app, toque no link e confirme que você chega à loja. Instale e abra, e o app deve exibir o conteúdo pretendido.
• Deep link direto: com o app instalado, toque no link e confirme que o app abre diretamente no conteúdo pretendido.
• Ordenação de SESSION: confirme que uma única SESSION é recebida antes de qualquer evento, e que a resposta SESSION é processada e passada ao cliente (crítico para deferred deep links).
• openuri preenchido: verifique que as aberturas por deep link enviam uma SESSION com openuri definido, independentemente da janela de timeout.

Guias de teste: Teste sua integração | Teste um Tracking Link