APIs legadas do Android

Deep linking direto

Overview

O deep link direto direciona os usuários móveis para uma atividade ou conteúdo específico em um aplicativo, quando o aplicativo já está instalado.

Esse roteamento no aplicativo para uma atividade específica no aplicativo é possível devido aos parâmetros passados para o aplicativo quando o sistema operacional abre o aplicativo e o onAppOpenAttribution method is called. AppsFlyer's OneLink ensures that the correct value is passed along with the user's click, thus personalizing the user’s app experience.

Only the deep_link_value is required for deep linking. However, other parameters and values (such as custom attribution parameters) can also be added to the link and returned by the SDK as deep linking data.

O fluxo de deep links diretos funciona da seguinte maneira:

Direct Deep Linking flow

  1. O usuário clica na URL curta do OneLink.
  2. O Android inicia o aplicativo com base na atividade relevante no AndroidManifest.xml.
  3. O SDK da AppsFlyer é engatilhado no aplicativo.
  4. O SDK da AppsFlyer recupera os dados do OneLink.
    • Em uma URL curta, os dados são recuperados da API de resolvedor de URL curta nos servidores da AppsFlyer.
    • Em uma URL longa, os dados são recuperados diretamente da URL longa.
  5. AppsFlyer SDK triggers onAppOpenAttribution() with the retrieved parameters and cached attribution parameters (e.g. install_time).
  6. Asynchronously, onConversionDataSuccess() is called, holding the full cached attribution data. (You can exit this function by checking if is_first_launch is true.)
  7. onAppOpenAttribution() usa o mapa attributionData para enviar outras atividades no aplicativo e passar dados relevantes.
    • Isso cria a experiência personalizada para o usuário, que é o principal objetivo do OneLink.

Procedures

To implement the onAppOpenAttribution e estabelecer os parâmetros de comportamento, a seguinte lista de verificação de procedimentos deve ser completada.

Lista de verificação de procedimentos

  1. Decidir o comportamento do aplicativo e de deep_link_value (and other parameter names and values) - with the marketer
  2. Entrada do método de planejamento, ou seja deep_link_value (and other parameter names and values) - with the marketer
  3. Implementando o onAppOpenAttribution() logic
  4. Implementando o onAttributionFailure() logic

Decidindo o comportamento do aplicativo

Para decidir qual é o comportamento do aplicativo quando o link é clicado:

Obter do profissional de marketing: o comportamento esperado do link quando ele é clicado.

Entrada do método de planejamento

When a OneLink is clicked and the user has the app installed on their device, the onAppOpenAttribution method is called by the AppsFlyer SDK. This is referred to as a retargeting re-engagement.

The onAppOpenAttribution method gets variables as an input like this: Map <String, String>.
A estrutura de dados de entrada é descrita aqui.

Implementando a lógica onAppOpenAttribution()

The deep link opens the onAppOpenAttribution na atividade principal. Os parâmetros do OneLink na entrada do método são usados para implementar a experiência específica do usuário quando o aplicativo é aberto.

Exemplo de código:

@Override
  public void onAppOpenAttribution(Map<String, String> attributionData) {
  if (!attributionData.containsKey("is_first_launch"))
    Log.d(LOG_TAG, "onAppOpenAttribution: This is NOT deferred deep linking");
  for (String attrName : attributionData.keySet()) {
    String deepLinkAttrStr = attrName + " = " + attributionData.get(attrName);
    Log.d(LOG_TAG, "Deeplink attribute: " + deepLinkAttrStr);
  }
  Log.d(LOG_TAG, "onAppOpenAttribution: Deep linking into " + attributionData.get("deep_link_value"));
  goToFruit(attributionData.get("deep_link_value"), attributionData);
}

@Override
  public void onAttributionFailure(String errorMessage) {
  Log.d(LOG_TAG, "error onAttributionFailure : " + errorMessage);
}

private void goToFruit(String fruitName, Map<String, String> dlData) {
    String fruitClassName = fruitName.concat("Activity");
    try {
        Class fruitClass = Class.forName(this.getPackageName().concat(".").concat(fruitClassName));
        Log.d(LOG_TAG, "Looking for class " + fruitClass);
        Intent intent = new Intent(getApplicationContext(), fruitClass);
        if (dlData != null) {
            // Map is casted HashMap since it is easier to pass serializable data to an intent
            HashMap<String, String> copy = new HashMap<String, String>(dlData);
            intent.putExtra(DL_ATTRS, copy);
        }
        startActivity(intent);
    } catch (ClassNotFoundException e) {
        Log.d(LOG_TAG, "Deep linking failed looking for " + fruitName);
        e.printStackTrace();
    }
}

⇲ Links do Github: Java

ℹ️

Observação

onAppOpenAttribution não é chamado quando o aplicativo está sendo executado em segundo plano e o aplicativo 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 aplicativo não padrão LaunchMode.

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

Implementando a lógica OnAttributionFailure ()

The onAttributionFailure method is called whenever the call to onAppOpenAttribution fails. The function should report the error and create an expected experience for the user.

@Override
public void onAttributionFailure(String errorMessage) {
    Log.d(LOG_TAG, "error onAttributionFailure : " + errorMessage);
}

⇲ Links do Github: Java

Links diretos adiados

Overview

O deferred deep linking direciona os novos usuários primeiro para a loja de aplicativos correta para instalar o aplicativo e, depois da primeira abertura, para uma experiência de aplicativo específica (por exemplo, uma página específica no aplicativo).

When the user first launches the app, the onConversionDataSuccess callback function receives both the conversion data of the new user, and OneLink data. The OneLink data makes in-app routing possible due to the deep_link_value ou outro que é passado para o aplicativo quando o sistema operacional abre o aplicativo.

Only the deep_link_value is required for deep linking. However, other parameters and values (such as custom attribution parameters) can also be added to the link and returned by the SDK as deep linking data. The AppsFlyer OneLink ensures that the correct parameters are passed along with the user's click, thus personalizing the user’s app experience.

The marketer and developer must coordinate regarding desired app behavior and deep_link_value. The marketer uses the parameters to create deep links, and the developer customizes the behavior of the app based on the value received.

É responsabilidade do desenvolvedor garantir que os parâmetros sejam tratados corretamente no aplicativo, tanto para roteamento in-app quanto para personalizar dados no link.

O fluxo de deferred deep linking funciona da seguinte maneira:
Deferred Deep Linking flow!

  1. O usuário clica no OneLink em um dispositivo no qual o aplicativo não está instalado.
  2. A AppsFlyer registra o clique e redireciona o usuário para a loja de aplicativos ou página de destino correta.
  3. O usuário instala o aplicativo e o inicia.
  4. O SDK da AppsFlyer é inicializado e a instalação é atribuída nos servidores AppsFlyer.
  5. The SDK triggers the onConversionDataSuccess method. The function receives input that includes both the deep_link_value, and the attribution data/parameters defined in the OneLink data.
  6. O parâmetro is_first_launch has the value trueque sinaliza o fluxo de deferred deep link.
    O desenvolvedor utiliza os dados recebidos no onConversionDataSuccess para criar uma experiência personalizada para o usuário para a primeira inicialização do aplicativo.

Procedures

To implement the onConversionDataSuccess method and set up the parameter behaviors, the following action checklist of procedures need to be completed.

  1. Decidir o comportamento do aplicativo na primeira inicialização e deep_link_value (and other parameter names and values) - with the marketer
  2. Entrada do método de planejamento, ou seja deep_link_value (and other parameter names and values) - with the marketer
  3. Implementando o onConversionDataSuccess() logic
  4. Implementando o onConversionDataFail() logic

Decidindo o comportamento do aplicativo na primeira inicialização

Para decidir o comportamento do aplicativo na primeira inicialização:

Obter do profissional de marketing: o comportamento esperado do link quando ele é clicado e o aplicativo abre pela primeira vez.

Entrada do método de planejamento

For deferred deep linking, the onConversionDataSuccess method input must be planned and the input decided in the previous section (for deep linking) is made relevant for the first time the app is launched.

The onConversionDataSuccess method gets the deep_link_value e outras variáveis como um input como este: Mapa <String, Objeto>.

O mapa contém dois tipos de dados:

  • Dados de atribuição
  • Data defined by the marketer in the link (deep_link_value and other parameters and values)
    Other parameters can be either:
    • Parâmetros oficiais da AppsFlyer.
    • Parâmetros e valores personalizados escolhidos pelo profissional de marketing e desenvolvedor.
    • A estrutura de dados de entrada é descrita aqui.

The marketer and developers need to plan the deep_link_value (and other possible parameters and values) together based on the desired app behavior when the link is clicked.

To plan the deep_link_value, and other parameter names and values based on the expected link behavior:

  1. Diga ao profissional de marketing quais parâmetros e valores são necessários para implementar o comportamento desejado do aplicativo.
  2. Decide on naming conventions for the deep_link_value and other parameters and values.
    Note:
    • Parâmetros personalizados não aparecerão em dados brutos coletados na AppsFlyer.
    • Os dados de conversão não retornarão um parâmetro personalizado chamado "nome" com um "n" minúsculo.

Implementando a lógica onConversionDataSuccess()

When the app is opened for the first time, the onConversionDataSuccess method is triggered in the main activity. The deep_link_value and other parameters in the method input are used to implement the specific user experience when the app is first launched.

Para implementar a lógica:

  1. Implemente a lógica com base nos parâmetros e valores escolhidos. Veja o exemplo de código a seguir.
  2. Uma vez concluído, envie a confirmação ao profissional de marketing de que o aplicativo se comporta da maneira desejada.

Código de amostra

@Override
 public void onConversionDataSuccess(Map<String, Object> conversionData) {
     for (String attrName : conversionData.keySet())
         Log.d(LOG_TAG, "Conversion attribute: " + attrName + " = " + conversionData.get(attrName));
     String status = Objects.requireNonNull(conversionData.get("af_status")).toString();
     if(status.equals("Non-organic")){
         if( Objects.requireNonNull(conversionData.get("is_first_launch")).toString().equals("true")){
             Log.d(LOG_TAG,"Conversion: First Launch");
             if (conversionData.containsKey("deep_link_value")){
                 Log.d(LOG_TAG,"Conversion: This is deferred deep linking.");
                 //  TODO SDK in future versions - match the input types
                 Map<String,String> newMap = new HashMap<>();
                 for (Map.Entry<String, Object> entry : conversionData.entrySet()) {
                         newMap.put(entry.getKey(), String.valueOf(entry.getValue()));
                 }
                 onAppOpenAttribution(newMap);
             }
         } else {
             Log.d(LOG_TAG,"Conversion: Not First Launch");
         }
     } else {
         Log.d(LOG_TAG,"Conversion: This is an organic install.");
     }
 }

⇲ Links do Github: Java

Implementando a lógica onConversionDataFailure()

The onConversionDataFailure method is called whenever the call to onConversionDataSuccess fails. The function should report the error and create an expected experience for the user.

To implement the onConversionDataFailure método:

@Override
public void onConversionDataFail(String errorMessage) {
    Log.d(LOG_TAG, "error getting conversion data: " + errorMessage);
}

⇲ Links do Github: Java

Payloads de amostra do Android

Consulte os payloads de exemplo a seguir para links de aplicativos, esquemas de URI e deferred deep linking. As amostras contêm um payload completo, relevante para quando todos os parâmetros na página de configuração do link personalizado do Onelink contêm dados.

Observação: os payloads retornam como um mapa. No entanto, para maior clareza, os payloads de amostra a seguir são exibidos no formulário JSON.

Android App Links

Entrada para onAppOpenAttribution(Map<String, String> attributionData)

{
    "af_dp": "afbasicapp://mainactivity",
    "af_ios_url": "https://isitchristmas.com/",
    "fruit_name": "apples",
    "c": "fruit_of_the_month",
    "media_source": "Email",
    "link": "https://onelink-basic-app.onelink.me/H5hv/6d66214a",
    "pid": "Email",
    "af_cost_currency": "USD",
    "af_sub1": "my_sub1",
    "af_click_lookback": "20d",
    "af_adset": "my_adset",
    "af_android_url": "https://isitchristmas.com/",
    "af_sub2": "my_sub2",
    "fruit_amount": 26,
    "af_cost_value": 6,
    "campaign": "fruit_of_the_month",
    "af_channel": "my_channel",
    "af_ad": "my_adname",
    "is_retargeting": "true"
}
{
    "af_dp": "afbasicapp://mainactivity",
    "install_time": "2020-08-06 06:56:02",
    "fruit_name": "apples",
    "af_ios_url": "https://my_ios_lp.com",
    "media_source": "Email",
    "scheme": "https",
    "link": "https://onelink-basic-app.onelink.me/H5hv?pid=Email&c=fruit_of_the_month&af_channel=my_channel&af_adset=my_adset&af_ad=my_adname&af_sub1=my_sub1&af_sub2=my_sub2&fruit_name=apples&fruit_amount=16&af_cost_currency=USD&af_cost_value=6&af_click_lookback=20d&af_dp=afbasicapp%3A%2F%2Fmainactivity&af_ios_url=https%3A%2F%2Fmy_ios_lp.com&af_android_url=https%3A%2F%2Fmy_android_lp.com",
    "af_cost_currency": "USD",
    "af_sub1": "my_sub1",
    "af_click_lookback": "20d",
    "path": "/H5hv",
    "af_adset": "my_adset",
    "af_android_url": "https://my_android_lp.com",
    "af_sub2": "my_sub2",
    "fruit_amount": 16,
    "af_cost_value": 6,
    "host": "onelink-basic-app.onelink.me",
    "campaign": "fruit_of_the_month",
    "af_channel": "my_channel",
    "af_ad": "my_adname"
}

URI schemes

Entrada para onAppOpenAttribution(Map<String, String> attributionData)

{
    "scheme": "afbasicapp",
    "link": "afbasicapp://mainactivity?af_ad=my_adname&af_adset=my_adset&af_android_url=https%3A%2F%2Fmy_android_lp.com&af_channel=my_channel&af_click_lookback=25d&af_cost_currency=NZD&af_cost_value=5&af_deeplink=true&af_dp=afbasicapp%3A%2F%2Fmainactivity&af_force_deeplink=true&af_ios_url=https%3A%2F%2Fmy_ios_lp.com&af_sub1=my_sub1&af_sub2=my_sub2&af_web_id=367f81fb-59a4-446a-ac6c-a68d2ee9447c-p&campaign=my_campaign&fruit_amount=15&fruit_name=apples&is_retargeting=true&media_source=Email&shortlink=9270d092",
    "af_cost_currency": "NZD",
    "af_click_lookback": "25d",
    "af_deeplink": true,
    "path": "",
    "af_android_url": "https://my_android_lp.com",
    "af_force_deeplink": true,
    "fruit_amount": 15,
    "host": "mainactivity",
    "af_channel": "my_channel",
    "shortlink": "9270d092",
    "af_dp": "afbasicapp://mainactivity",
    "install_time": "2020-08-06 06:56:02",
    "af_ios_url": "https://my_ios_lp.com",
    "fruit_name": "apples",
    "af_web_id": "367f81fb-59a4-446a-ac6c-a68d2ee9447c-p",
    "media_source": "Email",
    "af_status": "Non-organic",
    "af_sub1": "my_sub1",
    "af_adset": "my_adset",
    "af_sub2": "my_sub2",
    "af_cost_value": 5,
    "campaign": "my_campaign",
    "af_ad": "my_adname",
    "is_retargeting": true
}
{
    "af_dp": "afbasicapp://mainactivity",
    "install_time": "2020-08-06 06:56:02",
    "af_ios_url": "https://my_ios_lp.com",
    "fruit_name": "apples",
    "af_web_id": "367f81fb-59a4-446a-ac6c-a68d2ee9447c-p",
    "scheme": "afbasicapp",
    "media_source": "Email",
    "link": "afbasicapp://mainactivity?af_ad=my_adname&af_adset=my_adset&af_android_url=https%3A%2F%2Fmy_android_lp.com&af_channel=my_channel&af_click_lookback=25d&af_cost_currency=NZD&af_cost_value=5&af_deeplink=true&af_dp=afbasicapp%3A%2F%2Fmainactivity&af_ios_url=https%3A%2F%2Fmy_ios_lp.com&af_sub1=my_sub1&af_sub2=my_sub2&af_web_id=367f81fb-59a4-446a-ac6c-a68d2ee9447c-p&campaign=my_campaign&fruit_amount=15&fruit_name=apples&is_retargeting=true&media_source=Email",
    "af_cost_currency": "NZD",
    "af_status": "Non-organic",
    "af_click_lookback": "25d",
    "af_sub1": "my_sub1",
    "af_deeplink": true,
    "path": "",
    "af_android_url": "https://my_android_lp.com",
    "af_adset": "my_adset",
    "fruit_amount": 15,
    "af_sub2": "my_sub2",
    "host": "mainactivity",
    "af_cost_value": 5,
    "campaign": "my_campaign",
    "af_channel": "my_channel",
    "af_ad": "my_adname",
    "is_retargeting": true
}

Deferred deep linking

Entrada para onConversionDataSuccess(Map<String, Object> conversionData)

{
    "redirect_response_data": null,
    "adgroup_id": null,
    "engmnt_source": null,
    "retargeting_conversion_type": "none",
    "orig_cost": 6.0,
    "af_cost_currency": "USD",
    "is_first_launch": true,
    "af_click_lookback": "20d",
    "af_cpi": null,
    "iscache": true,
    "click_time": "2020-08-12 16:04:50.605",
    "af_android_url": "https://isitchristmas.com/",
    "fruit_amount": 26,
    "is_branded_link": null,
    "match_type": "probabilistic",
    "adset": null,
    "af_channel": "my_channel",
    "campaign_id": null,
    "shortlink": "6d66214a",
    "af_dp": "afbasicapp://mainactivity",
    "install_time": "2020-08-12 16:05:33.750",
    "af_ios_url": "https://isitchristmas.com/",
    "fruit_name": "apples",
    "media_source": "Email",
    "agency": null,
    "af_siteid": null,
    "af_status": "Non-organic",
    "af_sub1": "my_sub1",
    "cost_cents_USD": 600,
    "af_sub5": null,
    "af_adset": "my_adset",
    "af_sub4": null,
    "af_sub3": null,
    "af_sub2": "my_sub2",
    "adset_id": null,
    "esp_name": null,
    "af_cost_value": 6,
    "campaign": "fruit_of_the_month",
    "http_referrer": "android-app://com.slack/",
    "af_ad": "my_adname",
    "is_universal_link": null,
    "is_retargeting": true,
    "adgroup": null
}