Adicionando suporte a deep links

Deep links direcionam os usuários para conteúdos específicos dentro do seu aplicativo. Quando os usuários tocam em um deep link em um dispositivo com o seu aplicativo instalado, o aplicativo abre diretamente no conteúdo pretendido, como uma página de produto ou uma experiência específica.

Os tracking links do Singular suportam tanto o deep linking padrão (para aplicativos instalados) quanto o deep linking diferido (para novas instalações). Para obter informações abrangentes, consulte as FAQ de deep linking e as FAQ de Singular Links .

Requisitos

Pré-requisitos

Conclua os Pré-requisitos do Singular Links para habilitar o deep linking no seu aplicativo.

Implementar o handler do Singular Links

O SingularLinkHandler fornece um mecanismo de callback para recuperar os parâmetros de deep link, deep link diferido e passthrough dos tracking links do Singular quando o aplicativo é aberto.

Parâmetros disponíveis:

• Deep link (_dl): URL de destino dentro do seu aplicativo para os usuários que clicam no link
• Deep link diferido (_ddl): URL de destino para os usuários que instalam o aplicativo após clicar no link
• Passthrough (_p): Dados personalizados passados pelo tracking link para contexto adicional

Configuração do SDK

Configurar o AndroidManifest

Antes que o SDK possa resolver um deep link, sua atividade precisa declarar um filtro de intent para que o Android encaminhe os intents ACTION_VIEW de entrada para ela. Adicione o filtro à atividade do launcher (ou à atividade que deve receber deep links) no AndroidManifest.xml e substitua pelo seu próprio scheme e 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>

Adicionar o SingularLinkHandler à Config

Configure o SingularLinkHandler durante a inicialização do SDK para processar os dados de deep link e deep link diferido recebidos.

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();
    }
}

Comportamento do handler

Entendendo a execução do SingularLinkHandler

O SingularLinkHandler se comporta de maneira diferente dependendo se o aplicativo acabou de ser instalado ou já está instalado.

Nova instalação (deep link diferido)

Em uma nova instalação, não há Open URL quando o aplicativo é iniciado. O Singular conclui a atribuição para determinar se o tracking link continha um valor de deep link ou deep link diferido.

Fluxo do deep link diferido:

1. O usuário clica em um tracking link do Singular configurado com um valor de deep link
2. O usuário instala e abre o aplicativo pela primeira vez
3. O SDK do Singular envia a primeira sessão para os servidores do Singular
4. A atribuição é concluída e identifica o deep link do tracking link
5. O valor do deep link é retornado ao SingularLinkHandler no parâmetro deeplink com isDeferred = true

Já instalado (deep link imediato)

Quando o aplicativo já está instalado, clicar em um Singular Link abre o aplicativo imediatamente usando a tecnologia Android App Links.

Fluxo do deep link imediato:

1. O usuário clica em um tracking link do Singular
2. O sistema operacional Android fornece uma Open URL contendo o tracking link completo do Singular
3. Durante a inicialização do SDK, o Singular faz o parsing do Intent do Android
4. O Singular extrai os valores de deeplink e passthrough
5. Os valores são retornados por meio do SingularLinkHandler com isDeferred = false

Parâmetros passthrough

Capture dados adicionais a partir do clique no tracking link usando os parâmetros passthrough.

Se um parâmetro passthrough (_p) estiver incluído no tracking link, o parâmetro passthrough do SingularLinkHandler conterá os dados correspondentes. Use isso para capturar metadados de campanha, dados de segmentação de usuário ou qualquer informação personalizada que você precisar no aplicativo.

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");
                }
            }
        }
    });

Encaminhar todos os parâmetros de consulta

Capture todos os parâmetros de consulta da URL do tracking link adicionando o parâmetro _forward_params=2 .

Quando _forward_params=2 é adicionado ao tracking link, todos os parâmetros de consulta são incluídos no parâmetro deeplink do SingularLinkHandler, dando-lhe acesso à URL completa com todos os seus parâmetros.