Adição de suporte para Deep Linking

Os linksdirecionam os usuários para um conteúdo específico dentro do seu aplicativo. Quando os utilizadores tocam numa ligação direta num dispositivo com a sua aplicação instalada, a aplicação abre-se diretamente para o conteúdo pretendido, como uma página de produto ou uma experiência específica.

Os links de rastreamento singulares suportam links diretos padrão (para aplicativos instalados) e links diretos adiados (para novas instalações). Para obter informações abrangentes, consulte as Perguntas frequentes sobre links diretose as Perguntas frequentes sobre links singulares.

Requisitos

Pré-requisitos

Preencha os Pré-requisitos de Links singularespara habilitar o deep linking para seu aplicativo.

Implementar o manipulador de links singulares

O SingularLinkHandler fornece um mecanismo de retorno de chamada para recuperar parâmetros de deep link, deferred deep link e passthrough de links de rastreamento Singular quando o aplicativo é aberto.

Parâmetros disponíveis:

• Deep Link (_dl): O URL de destino dentro do seu aplicativo para usuários que clicam no link
• Deep Link diferido (_ddl): O URL de destino para os utilizadores que instalam a aplicação depois de clicarem no link
• Passthrough (_p): Dados personalizados passados através do link de rastreamento para contexto adicional

Configuração do SDK

Adicionar SingularLinkHandler à configuração

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

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 manipulador

Entendendo a execução do SingularLinkHandler

O SingularLinkHandler se comporta de maneira diferente, dependendo se o aplicativo foi instalado recentemente ou se já está instalado.

Instalação recente (Deep Link diferido)

Em uma instalação recente, não existe uma URL aberta quando o aplicativo é iniciado. A Singular completa a atribuição para determinar se o link de rastreamento contém um valor de deep link ou de deferred deep link.

Fluxo de Deep Link Diferido:

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

Já instalado (ligação direta imediata)

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

Fluxo de Deep Link Imediato:

1. O usuário clica em um link de rastreamento Singular
2. O sistema operacional Android fornece um URL aberto contendo todo o link de rastreamento Singular
3. Durante a inicialização do SDK, Singular analisa a intenção do Android
4. Singular extrai os valores deeplink e passthrough
5. Os valores retornam através do SingularLinkHandler com isDeferred = false

Parâmetros de passagem

Capture dados adicionais do clique no link de rastreamento usando parâmetros de passagem.

Se um parâmetro passthrough (_p) for incluído no link de rastreamento, o parâmetro passthrough do SingularLinkHandler conterá os dados correspondentes. Utilize-o para capturar metadados de campanha, dados de segmentação de utilizadores ou qualquer informação personalizada de que necessite na aplicação.

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(intent) { params ->
        // Extract passthrough data
        params.passthrough?.let { passthroughData ->
            // 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")
        }
    }

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 do URL do link de rastreamento anexando o parâmetro _forward_params=2.

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