Descripción general

Implementa el deep linking y el deferred deep linking para los tracking links de Singular de modo que los usuarios pasen sin interrupciones de una campaña a una pantalla específica de tu app.

Un deep link es un enlace en el que se puede hacer clic y que abre contenido específico dentro de una app. Hay dos escenarios que debes admitir:

• Deep link (directo): el usuario ya tiene la app instalada. Toca un Singular Link y la app se abre directamente en el contenido correcto.
• Deferred deep link (DDL): el usuario aún no tiene la app. Toca el enlace, instala desde la tienda y, en la primera apertura, la app igualmente lo dirige al contenido previsto.

Con una integración de SDK, Singular gestiona la mayor parte de esto automáticamente. En una integración server-to-server (S2S) no hay SDK en el dispositivo, por lo que tu equipo se encarga de dos tareas adicionales: pasar a Singular el deep link que recibió tu app y leer el deferred deep link que devuelve Singular para dirigir al usuario. Ambas fluyen a través del endpoint SESSION:

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

Recursos: FAQ de Deep Linking | FAQ de Singular Links

Las tres configuraciones de un vistazo

Paso 1: Configuración a nivel de app

Antes de que cualquier deep link pueda funcionar, el sistema operativo debe reconocer los Singular Links como iOS Universal Links y Android App Links, de modo que al tocar un enlace se abra tu app en lugar de un navegador. Los esquemas de URI de app tradicionales se admiten como alternativa.

Sigue las guías de configuración canónicas para conocer los pasos detallados de cada plataforma y, luego, confirma que cada elemento a continuación esté completo. Los pasos detallados se encuentran en Requisitos previos de Singular Links y Cómo configurar Deep Links . La lista de verificación aquí te indica el orden requerido y los puntos que los equipos suelen pasar por alto.

Lista de verificación de la configuración:

1. Agrega un subdominio de enlace en Attribution > Manage Links > Manage Link Domains (por ejemplo yourbrand.sng.link ). Este es el host que usan tus Singular Links.
2. iOS — Universal Links: habilita la capacidad Associated Domains para applinks:yourbrand.sng.link y, luego, copia tu App Prefix / Team ID del Apple Developer Portal en Settings > Apps > [iOS app] > Show Advanced Settings . De forma opcional, registra un esquema de app alternativo como URL Type en Xcode.
3. Android — App Links: genera tus huellas de firma SHA-256 (Play Console para producción, keytool para depuración), agrega un filtro de intent autoVerify para tu dominio de Singular a AndroidManifest.xml y, luego, pega la huella en Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints .
4. Define los deep links en Attribution > Manage Links > Create Link (consulta el mapeo de campos a continuación).

Mapeo de los campos de redirección de Manage Links

Cuando creas el enlace, tres campos de redirección se corresponden directamente con los tres conceptos de deep link que se usan más adelante en la API:

Traspaso al desarrollador: ingeniería debe proporcionar el/los esquema(s) de deep link por plataforma y la lista de URLs de destino (por ejemplo myapp://autumnfashion ).

Paso 2: SESSION (entrante) — envía el deep link a Singular

Cuando la app se abre desde un Singular Link, captura la URL de apertura completa y envíala a Singular en la solicitud SESSION mediante el parámetro openuri (con codificación de URL). Así es como Singular atribuye la sesión al enlace e informa el resultado del deep link. Obligatorio cuando se usan Singular Links.

Parámetros de Singular Link incluidos en la URL

Captura la URL de apertura en la app

La app necesita código de controlador que reciba la URL de apertura y la reenvíe a tu servidor para incluirla en la solicitud 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()) }
}

Envía la solicitud SESSION con openuri

Desde tu servidor, incluye la URL capturada (con codificación de URL) 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"

Resolución de enlaces cortos

Si el usuario abrió un Singular Link acortado, envía también singular_link_resolve_required=true . Singular devuelve el enlace largo expandido para que puedas analizar el deep link y los valores de passthrough.

Respuesta de ejemplo:

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

Si tu organización configuró el passthrough dinámico para un enlace, la URL del deep link incluye el parámetro _p con una cadena JSON con codificación de URL o una cadena no estructurada para el enrutamiento de contenido. Consulta Parámetros de passthrough dinámico .

Referencia: Referencia de la API del endpoint SESSION (Parámetros de Deep Linking).

Paso 3: SESSION (saliente) — retransmite el deferred deep link a la app

Para un usuario que instala la app después de tocar el enlace, Singular devuelve el deferred deep link en la respuesta SESSION en la primera sesión después de la instalación. Tu servidor debe retransmitir ese valor de vuelta a la app para que pueda dirigir al usuario.

Solicita el DDL en la primera sesión

En la primera solicitud SESSION después de una instalación, agrega estos dos parámetros:

Solicitud SESSION de ejemplo (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"

Lee la respuesta y retransmítela a la app

Si la instalación provino de un tracking link que lleva un deferred deep link, Singular devuelve:

Respuesta SESSION de ejemplo:

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

Pruebas y validación

• Deferred deep link: en un dispositivo sin la app, toca el enlace y confirma que llegas a la tienda. Instala y abre, y la app debería mostrar el contenido previsto.
• Deep link directo: con la app instalada, toca el enlace y confirma que la app se abre directamente en el contenido previsto.
• Orden de SESSION: confirma que se recibe una única SESSION antes de cualquier evento y que la respuesta SESSION se analiza y se pasa al cliente (fundamental para los deferred deep links).
• openuri completado: verifica que las aperturas por deep link envíen una SESSION con openuri establecido, sin importar la ventana de tiempo de espera.

Guías de pruebas: Prueba tu integración | Prueba un tracking link