Deep linking unificado para Android

Visão geral: Unified deep linking (UDL) permite enviar usuários novos e existentes para uma atividade in-app específica (por exemplo, uma determinada página no aplicativo) assim que o aplicativo for aberto.

📘

Proteção de privacidade do UDL

For new users, the UDL method only returns parameters relevant to deferred deep linking: deep_link_value and deep_link_sub1-10. If you try to get any other parameters (media_source, campaign, af_sub1-5, etc.), eles retornam null.

Fluxo

Android UDL flow!

O fluxo funciona da seguinte maneira:

  1. O usuário clica em um link do OneLink.
    • Se o usuário tiver o aplicativo instalado, o esquema de URI ou Android App Links abrirá o aplicativo.
    • Se o usuário não tiver o aplicativo instalado, ele será redirecionado para a loja de aplicativos e, após o download, o usuário abrirá o aplicativo.
  2. O aplicativo aberto aciona o SDK da AppsFlyer.
  3. O SDK da AppsFlyer executa a API UDL.
  4. A API UDL recupera dados do OneLink dos servidores AppsFlyer.
  5. The UDL API calls back the onDeepLinking() método no DeepLinkingListener class.
  6. The onDeepLinking() method gets a DeepLinkResult object.
  7. The DeepLinkResult object includes:
    • Status (Encontrado/Não encontrado/Erro)
    • A DeepLink object that carries the deep_link_value and deep_link_sub1-10 parâmetros, que o desenvolvedor utiliza para encaminhar o usuário para uma atividade específica no sistema, que é o objetivo principal da OneLink.

Pré-requisitos

  • O UDL requer o SDK Android da AppsFlyer V6.1+.

Planejamento

Ao configurar o OneLink, o profissional de marketing usa parâmetros para criar os links, e o desenvolvedor personaliza o comportamento do aplicativo com base nos valores recebidos. É responsabilidade do desenvolvedor garantir que os parâmetros sejam tratados corretamente no aplicativo, tanto para roteamento no aplicativo quanto para personalização de dados no link.

Para planejar o OneLink:

  1. Obtenha do profissional de marketing o comportamento desejado e a experiência pessoal que um usuário obtém ao clicar na URL.
  2. Based on the desired behavior, plan the deep_link_value and other parameters that are needed to give the user the desired personal experience.
    • The deep_link_value is set by the marketer in the URL and used by the developer to redirect the user to a specific place inside the app. For example, if you have a fruit store and want to direct users to apples, the value of deep_link_value can be apples.
    • The deep_link_sub1-10 parameters can also be added to the URL to help personalize the user experience. For example, to give a 10% discount, the value of deep_link_sub1 can be 10.

Implementação

Implemente a lógica da API UDL com base nos parâmetros e valores escolhidos.

  1. Use o subscribeForDeepLink() método (de AppsFlyerLib) para registrar o DeepLinkListener ouvinte da interface.
  2. Certifique-se de substituir a função de retorno de chamada onDeepLinking().
    onDeepLinking() aceita como argumento um DeepLinkResult object.
  3. Use getStatus() to query whether the deep linking match is found.
  4. For when the status is an error, call getError() and run your error flow.
  5. For when the status is found, use getDeepLink() to retrieve the DeepLink object.
    The DeepLink contém as informações de deep linking e funções de ajuda para recuperar facilmente valores das conhecidas chaves OneLink, por exemplo, getDeepLinkValue().
  6. Use getDeepLinkValue() to retrieve the deep_link_value.
  7. Use getStringValue("deep_link_sub1") to retrieve deep_link_sub1. Do the same for deep_link_sub2-10 parameters, changing the string value as required.
  8. Once deep_link_value and deep_link_sub1-10 are retrieved, pass them to an in-app router and use them to personalize the user experience.

📘

Observação

onDeepLinking não é chamado quando o aplicativo está sendo executado em segundo plano e Application LaunchMode não é padrão. Para corrigir isso, chame o método setIntent(intent) para definir o valor de intent dentro do método substituído onNewIntent se o aplicativo estiver usando um LaunchMode não padrão.

       import android.content.Intent;
       ...
       ...
       ...
       @Override
       protected void onNewIntent(Intent intent) 
       { 
          super.onNewIntent(intent);     
          setIntent(intent);
       }

Supporting legacy OneLink links

Legacy OneLink são links que não contêm os parâmetros recomendados para UDL: deep_link_value and deep_link_sub1-10.
Normalmente, esses são links que já existem e estão em uso ao migrar de métodos legados para UDL.
Os usuários de notícias que usam links legados são manipulados por onConversionDataSuccess no contexto do Deep Deferred Deep Linking.
UDL lida com deep linking para usuários existentes. Nesse caso, é recomendável adicionar suporte no retorno de chamada UDL onDeepLinking para parâmetros legados.
exemplo de código Java

Code example

appsflyer.subscribForDeepLink(new DeepLinkListen
    @Override
    public void onDeepLinking(@NonNull DeepLinkResult deepLinkResult) {
        DeepLinkResult.Status dlStatus = deepLinkResult.getStatus();
        if (dlStatus == DeepLinkResult.Status.FOUND) {
            Log.d(LOG_TAG, "Deep link found");
        } else if (dlStatus == DeepLinkResult.Status.NOT_FOUND) {
            Log.d(LOG_TAG, "Deep link not found");
            return;
        } else {
            // dlStatus == DeepLinkResult.Status.ERROR
            DeepLinkResult.Error dlError = deepLinkResult.getError();
            Log.d(LOG_TAG, "There was an error getting Deep Link data: " + dlError.toString());
            return;
        }
        DeepLink deepLinkObj = deepLinkResult.getDeepLink();
        try {
            Log.d(LOG_TAG, "The DeepLink data is: " + deepLinkObj.toString());
        } catch (Exception e) {
            Log.d(LOG_TAG, "DeepLink data came back null");
            return;
        }
        // An example for using is_deferred
        if (deepLinkObj.isDeferred()) {
            Log.d(LOG_TAG, "This is a deferred deep link");
        } else {
            Log.d(LOG_TAG, "This is a direct deep link");
        }
        
        // ** Next if statement is optional **
        // Our sample app's user-invite carries the referrerID in deep_link_sub2
        // See the user-invite section in FruitActivity.java
        if (dlData.has("deep_link_sub2")){
            referrerId = deepLinkObj.getStringValue("deep_link_sub2");
            Log.d(LOG_TAG, "The referrerID is: " + referrerId);
        } else {
            Log.d(LOG_TAG, "deep_link_sub2/Referrer ID not found");
        }
        // An example for using a generic getter
        String fruitName = "";
        try {
            fruitName = deepLinkObj.getDeepLinkValue();
            Log.d(LOG_TAG, "The DeepLink will route to: " + fruitName);
        } catch (Exception e) {
            Log.d(LOG_TAG, "Custom param fruit_name was not found in DeepLink data");
            return;
        }
        goToFruit(fruitName, deepLinkObj);
    }
});
AppsFlyerLib.getInstance().subscribeForDeepLink(object : DeepLinkListener{
    override fun onDeepLinking(deepLinkResult: DeepLinkResult) {
        when (deepLinkResult.status) {
            DeepLinkResult.Status.FOUND -> {
                Log.d(
                    LOG_TAG,"Deep link found"
                )
            }
            DeepLinkResult.Status.NOT_FOUND -> {
                Log.d(
                    LOG_TAG,"Deep link not found"
                )
                return
            }
            else -> {
                // dlStatus == DeepLinkResult.Status.ERROR
                val dlError = deepLinkResult.error
                Log.d(
                    LOG_TAG,"There was an error getting Deep Link data: $dlError"
                )
                return
            }
        }
        var deepLinkObj: DeepLink = deepLinkResult.deepLink
        try {
            Log.d(
                LOG_TAG,"The DeepLink data is: $deepLinkObj"
            )
        } catch (e: Exception) {
            Log.d(
                LOG_TAG,"DeepLink data came back null"
            )
            return
        }

        // An example for using is_deferred
        if (deepLinkObj.isDeferred == true) {
            Log.d(LOG_TAG, "This is a deferred deep link");
        } else {
            Log.d(LOG_TAG, "This is a direct deep link");
        }

        try {
            val fruitName = deepLinkObj.deepLinkValue
            Log.d(LOG_TAG, "The DeepLink will route to: $fruitName")
        } catch (e:Exception) {
            Log.d(LOG_TAG, "There's been an error: $e");
            return;
        }
    }
})

⇲ Links do Github: Java

Testando deferred deep linking

Before you begin

  • Integração UDL completa
  • Registre seu dispositivo de teste
  • Ative o modo de depuração no aplicativo
  • Verifique se o aplicativo não está instalado no seu dispositivo
  • Peça ao seu profissional de marketing um template do OneLink.
    • Vai parecer algo assim: https://onelink-basic-app.onelink.me/H5hv.
    • Este exemplo usa o subdomínio OneLink onelink-basic-app.onelink.me e o ID do template do OneLink H5hv

The test link

Você pode usar um link do OneLink existente ou pedir ao seu profissional de marketing para criar um novo para teste. Podem ser usadas URLs curtas e longas do OneLink.

Adicionando parâmetros ad hoc a um link existente

  • Use apenas o domínio e template do OneLink do seu link, por exemplo: https://onelink-basic-app.onelink.me/H5hv.
  • Adicionar parâmetros do OneLink deep_link_value and deep_link_sub1-10, conforme esperado pelo seu aplicativo. Os parâmetros devem ser adicionados como parâmetros de consulta.
    • Exemplo: https://onelink-basic-app.onelink.me/H5hv?deep_link_value=apples&deep_link_sub1=23

Perform the test

  1. Clique no link no seu dispositivo.
  2. O OneLink redireciona você de acordo com a configuração do link, seja para o Google Play ou para um site.
  3. Instale o aplicativo.

    Importante

    • Se o aplicativo ainda estiver em desenvolvimento e ainda não tiver sido carregado na loja, você verá esta imagem:
      drawing
    • Instale o aplicativo do Android Studio ou qualquer outro IDE que você usa.
  4. O UDL detecta o deferred deep linking, corresponde a instalação ao clique e recupera os parâmetros do OneLink para o callback onDeepLinking .

Expected logs results

📘

Os logs a seguir estão disponíveis apenas quando o modo de depuração está ativado.

  • SDK inicializado:

    D/AppsFlyer_6.9.0: Initializing AppsFlyer SDK: (v6.9.0.126)
    
  • O registro a seguir refere-se a deep links diretos e pode ser ignorado em um cenário de deferred deep linking:

    D/AppsFlyer_6.9.0: No deep link detected
    
  • A API UDL começa:

    D/AppsFlyer_6.9.0: [DDL] start
    
  • UDL envia consulta para a AppsFlyer para consultar uma correspondência com esta instalação:

    D/AppsFlyer_6.9.0: [DDL] Preparing request 1
    ...
    I/AppsFlyer_6.9.0: call = https://dlsdk.appsflyer.com/v1.0/android/com.appsflyer.onelink.appsflyeronelinkbasicapp?af_sig=<>&sdk_version=6.9; size = 239 bytes; body = {
          ...
          TRUNCATED
          ...
    }
    
  • UDL obteve uma resposta e chama o callback onDeepLinking com status=FOUND e dados de link do OneLink:

    D/AppsFlyer_6.9.0: [DDL] Calling onDeepLinking with:
      {"deepLink":"{\"campaign_id\":\"\",\"af_sub3\":\"\",\"match_type\":\"probabilistic\",\"af_sub1\":\"\",\"deep_link_value\":\"apples\",\"campaign\":\"\",\"af_sub4\":\"\",\"timestamp\":\"2022-12-06T11:47:40.037\",\"click_http_referrer\":\"\",\"af_sub5\":\"\",\"media_source\":\"\",\"af_sub2\":\"\",\"deep_link_sub1\":\"23\",\"is_deferred\":true}","status":"FOUND"}
    
    

Testando deep linking (Android App Links)

Before you begin

Create the test link

Use o mesmo método do deferred deep linking.

Perform the test

  1. Clique no link no seu dispositivo.
  2. UDL detecta o Android App Link e recupera os parâmetros do OneLink para onDeepLinking .

Expected logs results

📘

Os logs a seguir estão disponíveis apenas quando o modo de depuração está ativado.

  • Se o link for um link curto do OneLink (por exemplo, https://onelink-basic-app.onelink.me/H5hv/apples)
    D/AppsFlyer_6.9.0: HTTP: [258990367] GET:https://onelink.appsflyer.com/shortlink-sdk/v2/H5hv?id=apples 
    
  • chamadas UDL onDeepLinking com status=FOUND e dados de link do OneLink
    D/AppsFlyer_6.9.0: [DDL] Calling onDeepLinking with:
        {"deepLink":"{\"path\":\"\\\/H5hv\",\"scheme\":\"https\",\"link\":\"https:\\\/\\\/onelink-basic-app.onelink.me\\\/H5hv?deep_link_value=apples&deep_link_sub1=23\",\"host\":\"onelink-basic-app.onelink.me\",\"deep_link_sub1\":\"23\",\"deep_link_value\":\"apples\",\"is_deferred\":false}","status":"FOUND"}
    

📘

Dica

Se, ao clicar em um Android App Link, o sistema operacional mostrar uma caixa de diálogo de desambiguação ou redirecionar para o Google Play ou um site, verifique se a assinatura SHA256 está correta.

  1. Use adb para obter a assinatura do aplicativo no dispositivo:
adb shell pm get-app-links <PACKAGE_NAME>

2. Verifique se o subdomínio foi verified.
adb verified!

  1. Se o subdomínio não tiver sido verificado, ele mostra 1024.
    adb verified!