Agregar soporte para deep links

Los deep links dirigen a los usuarios a contenido específico dentro de tu aplicación. Cuando los usuarios tocan un deep link en un dispositivo con tu aplicación instalada, la aplicación se abre directamente en el contenido previsto, como una página de producto o una experiencia específica.

Los tracking links de Singular admiten tanto el deep linking estándar (para aplicaciones instaladas) como el deep linking diferido (para nuevas instalaciones). Para obtener información completa, consulta las FAQ de deep linking y las FAQ de Singular Links .

Requisitos

Requisitos previos

Completa los Requisitos previos de Singular Links para habilitar el deep linking de tu aplicación.

Implementar el handler de Singular Links

SingularLinkHandler proporciona un mecanismo de callback para recuperar los parámetros de deep link, deep link diferido y passthrough de los tracking links de Singular cuando se abre la aplicación.

Parámetros disponibles:

• Deep link (_dl): URL de destino dentro de tu aplicación para los usuarios que hacen clic en el link
• Deep link diferido (_ddl): URL de destino para los usuarios que instalan la aplicación después de hacer clic en el link
• Passthrough (_p): Datos personalizados pasados a través del tracking link para contexto adicional

Configuración del SDK

Configurar AndroidManifest

Antes de que el SDK pueda resolver un deep link, tu actividad debe declarar un filtro de intent para que Android enrute los intents ACTION_VIEW entrantes a ella. Agrega el filtro a la actividad de inicio (o a la actividad que deba recibir los deep links) en AndroidManifest.xml y sustituye tu propio scheme y host.

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Custom URI scheme deep link -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="yourapp" />
    </intent-filter>

    <!-- HTTPS Singular Link (replace with your branded subdomain) -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="yourcompany.sng.link" />
        <data android:pathPrefix="/A"/>
        <data android:pathPrefix="/B"/>
        <data android:pathPrefix="/E"/>
        <data android:pathPrefix="/F"/>
    </intent-filter>
</activity>

Agregar SingularLinkHandler a la Config

Configura SingularLinkHandler durante la inicialización del SDK para procesar los datos de deep link y deep link diferido entrantes.

private fun initSingularSDK() {
    val config = SingularConfig("SDK_KEY", "SDK_SECRET")
        .withSingularLink(intent) { params ->
            val deeplink = params.deeplink
            val passthrough = params.passthrough
            val isDeferred = params.isDeferred

            Log.d("SingularLink", "Deeplink: ${deeplink ?: "null"}")
            Log.d("SingularLink", "Passthrough: ${passthrough ?: "null"}")
            Log.d("SingularLink", "Is Deferred: $isDeferred")

            // Handle deep link routing
            deeplink?.let { url ->
                handleDeepLink(url, isDeferred)
            }
        }

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

override fun onNewIntent(intent: Intent?) {
  super.onNewIntent(intent)
  // Configure onNewIntent to handle Warm start deeplinks
  intent?.let {
    setIntent(intent)
    initSingularSDK()
  }
}

private void initSingularSDK() {
    SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
        .withSingularLink(getIntent(), new SingularLinkHandler() {
            @Override
            public void onResolved(SingularLinkParams params) {
                String deeplink = params.getDeeplink();
                String passthrough = params.getPassthrough();
                boolean isDeferred = params.isDeferred();

                Log.d("SingularLink", "Deeplink: " + (deeplink != null ? deeplink : "null"));
                Log.d("SingularLink", "Passthrough: " + (passthrough != null ? passthrough : "null"));
                Log.d("SingularLink", "Is Deferred: " + isDeferred);

                // Handle deep link routing
                if (deeplink != null) {
                    handleDeepLink(deeplink, isDeferred);
                }
            }
        });

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    // Configure onNewIntent to handle Warm start deeplinks
    if (intent != null) {
        setIntent(intent);
        initSingularSDK();
    }
}

Comportamiento del handler

Entender la ejecución de SingularLinkHandler

SingularLinkHandler se comporta de manera diferente según si la aplicación está recién instalada o ya instalada.

Instalación nueva (deep link diferido)

En una instalación nueva, no existe una Open URL cuando se inicia la aplicación. Singular completa la atribución para determinar si el tracking link contenía un valor de deep link o deep link diferido.

Flujo del deep link diferido:

1. El usuario hace clic en un tracking link de Singular configurado con un valor de deep link
2. El usuario instala y abre la aplicación por primera vez
3. El SDK de Singular envía la primera sesión a los servidores de Singular
4. La atribución se completa e identifica el deep link del tracking link
5. El valor del deep link se devuelve a SingularLinkHandler en el parámetro deeplink con isDeferred = true

Ya instalada (deep link inmediato)

Cuando la aplicación ya está instalada, hacer clic en un Singular Link abre la aplicación de forma inmediata usando la tecnología Android App Links.

Flujo del deep link inmediato:

1. El usuario hace clic en un tracking link de Singular
2. El sistema operativo Android proporciona una Open URL que contiene el tracking link completo de Singular
3. Durante la inicialización del SDK, Singular parsea el Intent de Android
4. Singular extrae los valores de deeplink y passthrough
5. Los valores se devuelven a través de SingularLinkHandler con isDeferred = false

Parámetros passthrough

Captura datos adicionales del clic en el tracking link usando los parámetros passthrough.

Si se incluye un parámetro passthrough (_p) en el tracking link, el parámetro passthrough de SingularLinkHandler contiene los datos correspondientes. Úsalo para capturar metadatos de campaña, datos de segmentación de usuarios o cualquier información personalizada que necesites en la aplicación.

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(intent) { params ->
        // Extract passthrough data
        params.passthrough?.let { passthroughData ->
            try {
                // Parse and use custom data
                val jsonData = JSONObject(passthroughData)
                val campaignId = jsonData.optString("campaign_id")
                val userSegment = jsonData.optString("segment")

                Log.d("SingularLink", "Campaign ID: $campaignId")
                Log.d("SingularLink", "User Segment: $userSegment")
            } catch (e: JSONException) {
                Log.e("SingularLink", "Error parsing passthrough data", e)
            }
        }
    }

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Extract passthrough data
            String passthroughData = params.getPassthrough();
            if (passthroughData != null) {
                try {
                    // Parse and use custom data
                    JSONObject jsonData = new JSONObject(passthroughData);
                    String campaignId = jsonData.optString("campaign_id");
                    String userSegment = jsonData.optString("segment");

                    Log.d("SingularLink", "Campaign ID: " + campaignId);
                    Log.d("SingularLink", "User Segment: " + userSegment);
                } catch (JSONException e) {
                    Log.e("SingularLink", "Error parsing passthrough data");
                }
            }
        }
    });

Reenviar todos los parámetros de consulta

Captura todos los parámetros de consulta de la URL del tracking link agregando el parámetro _forward_params=2 .

Cuando se agrega _forward_params=2 al tracking link, todos los parámetros de consulta se incluyen en el parámetro deeplink de SingularLinkHandler, lo que te da acceso a la URL completa con todos sus parámetros.