APIs legadas do iOS

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 direto de deep links funciona da seguinte maneira:
Direct Deep Linking flow

  1. O usuário clica na URL curta do OneLink.

  2. O iOS lê os direitos de domínios associados do aplicativo.

  3. O iOS abre o aplicativo.

  4. O SDK da AppsFlyer é acionado dentro do aplicativo.

  5. 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.
  6. AppsFlyer SDK triggers onAppOpenAttribution() with the retrieved parameters and cached attribution parameters (e.g.install_time).

  7. Asynchronously, onConversionDataSuccess() is called, holding the full cached attribution data. (You can exit this function by checking if is_first_launch is true.)

  8. onAppOpenAttribution() use 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 obtém variáveis como uma entrada como esta: AnyHashable: Any.
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:

func onAppOpenAttribution(_ attributionData: [AnyHashable: Any]) {
    //Handle Deep Link Data
    print("onAppOpenAttribution data:")
    for (key, value) in attributionData {
        print(key, ":",value)
    }
    walkToSceneWithParams(params: attributionData)
}

// User logic
fileprivate func walkToSceneWithParams(params: [AnyHashable:Any]) {
    let storyBoard: UIStoryboard = UIStoryboard(name: "Main", bundle: nil)
    UIApplication.shared.windows.first?.rootViewController?.dismiss(animated: true, completion: nil)

    var fruitNameStr = ""

    if let thisFruitName = params["deep_link_value"] as? String {
        fruitNameStr = thisFruitName
    } else if let linkParam = params["link"] as? String {
        guard let url = URLComponents(string: linkParam) else {
            print("Could not extract query params from link")
            return
        }
        if let thisFruitName = url.queryItems?.first(where: { $0.name == "deep_link_value" })?.value {
            fruitNameStr = thisFruitName
        }
    }

    let destVC = fruitNameStr + "_vc"
    if let newVC = storyBoard.instantiateVC(withIdentifier: destVC) {

        print("AppsFlyer routing to section: \(destVC)")
        newVC.attributionData = params

        UIApplication.shared.windows.first?.rootViewController?.present(newVC, animated: true, completion: nil)
    } else {
        print("AppsFlyer: could not find section: \(destVC)")
    }
}

⇲ Links do Github: Swift

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.

func onAppOpenAttributionFailure(_ error: Error) {
    print("\(error)")
}

⇲ Links do Github: Swift

Links diretos adiados

❗️

Importante

Deferred deep linking usando o método legado de onConversionDataSuccess pode não funcionar para iOS 14.5+, pois requer dados de atribuição que podem não estar disponíveis devido à proteção de privacidade.
Recomendamos usar unified deep linking (UDL). O UDL está em conformidade com os padrões de privacidade do iOS 14.5+ e retorna apenas parâmetros relevantes para deep links e deferred deep linking: deep_link_value and deep_link_sub1-10. Parâmetros de atribuição (como media_source, campaign, af_sub1-5, etc.), retorno null e não pode ser usado para fins de deep linking.
Saber mais

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 uma entrada como esta: AnyHashable: Any.

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

// Handle Organic/Non-organic installation
func onConversionDataSuccess(_ data: [AnyHashable: Any]) {

    print("onConversionDataSuccess data:")
    for (key, value) in data {
        print(key, ":", value)
    }

    if let status = data["af_status"] as? String {
        if (status == "Non-organic") {
            if let sourceID = data["media_source"],
                let campaign = data["campaign"] {
                print("This is a Non-Organic install. Media source: \(sourceID)  Campaign: \(campaign)")
            }
        } else {
            print("This is an organic install.")
        }
        if let is_first_launch = data["is_first_launch"] as? Bool,
            is_first_launch {
            print("First Launch")
            if let fruit_name = data["deep_link_value"]
            {
                // The key 'deep_link_value' exists only in OneLink originated installs
                print("deferred deep-linking to \(fruit_name)")
                walkToSceneWithParams(params: data)
            }
            else {
                print("Install from a non-owned media")
            }
        } else {
            print("Not First Launch")
        }
    }
}

⇲ Links do Github: Swift

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:

func onConversionDataFail(_ error: Error) {
    print("\(error)")
}

⇲ Links do Github: Swift

Payloads de amostra do iOS

Consulte os seguintes payloads de exemplo para Links Universais, 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.

Universal Links

Entrada para onAppOpenAttribution(_ attributionData: [AnyHashable: Any])

{
   "af_ad": "my_adname",
   "af_adset": "my_adset",
   "af_android_url": "https://isitchristmas.com/",
   "af_channel": "my_channel",
   "af_click_lookback": "20d",
   "af_cost_currency": "USD",
   "af_cost_value": 6,
   "af_dp": "afbasicapp://mainactivity",
   "af_ios_url": "https://isitchristmas.com/",
   "af_sub1": "my_sub1",
   "af_sub2": "my_sub2",
   "c": "fruit_of_the_month",
   "campaign": "fruit_of_the_month",
   "fruit_amount": 26,
   "fruit_name": "apples",
   "is_retargeting": true,
   "link": "https://onelink-basic-app.onelink.me/H5hv/6d66214a",
   "media_source": "Email",
   "pid": "Email"
}
{
   "path": "/H5hv",
   "af_android_url": "https://my_android_lp.com",
   "af_channel": "my_channel",
   "host": "onelink-basic-app.onelink.me",
   "af_adset": "my_adset",
   "pid": "Email",
   "scheme": "https",
   "af_dp": "afbasicapp://mainactivity",
   "af_sub1": "my_sub1",
   "fruit_name": "apples",
   "af_ad": "my_adname",
   "af_click_lookback": "20d",
   "fruit_amount": 16,
   "af_sub2": "my_sub2",
   "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",
   "c": "fruit_of_the_month",
   "af_ios_url": "https://my_ios_lp.com",
   "af_cost_value": 6
}

URI scheme

Entrada para onAppOpenAttribution(_ attributionData: [AnyHashable: Any])

{
  "af_click_lookback ": "25d",
  "af_sub1 ": "my_sub1",
  "shortlink ": "9270d092",
  "af_deeplink ": true,
  "media_source ": "Email",
  "campaign ": "my_campaign",
  "af_cost_currency ": "NZD",
  "host ": "mainactivity",
  "af_ios_url ": "https://my_ios_lp.com",
  "scheme ": "afbasicapp",
  "path ": "",
  "af_cost_value ": 5,
  "af_adset ": "my_adset",
  "af_ad ": "my_adname",
  "af_android_url ": "https://my_android_lp.com",
  "af_sub2 ": "my_sub2",
  "af_force_deeplink ": true,
  "fruit_amount ": 15,
  "af_dp ": "afbasicapp://mainactivity",
  "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=56441f02-377b-47c6-9648-7a7f88268130-o&campaign=my_campaign&fruit_amount=15&fruit_name=apples&is_retargeting=true&media_source=Email&shortlink=9270d092",
  "af_channel ": "my_channel",
  "is_retargeting ": true,
  "af_web_id ": "56441f02-377b-47c6-9648-7a7f88268130-o",
  "fruit_name ": "apples"
}
{
  "af_ad ": "my_adname",
  "fruit_name ": "apples",
  "host ": "mainactivity",
  "af_channel ": "my_channel",
  "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=56441f02-377b-47c6-9648-7a7f88268130-o&campaign=my_campaign&fruit_amount=15&fruit_name=apples&is_retargeting=true&media_source=Email",
  "af_deeplink ": true,
  "campaign ": "my_campaign",
  "af_sub1 ": "my_sub1",
  "af_click_lookback ": "25d",
  "af_web_id ": "56441f02-377b-47c6-9648-7a7f88268130-o",
  "path ": "",
  "af_sub2 ": "my_sub2",
  "af_ios_url ": "https://my_ios_lp.com",
  "af_cost_value ": 5,
  "fruit_amount ": 15,
  "is_retargeting ": true,
  "scheme ": "afbasicapp",
  "af_force_deeplink ": true,
  "af_adset ": "my_adset",
  "media_source ": "Email",
  "af_cost_currency ": "NZD",
  "af_dp ": "afbasicapp://mainactivity",
  "af_android_url ": "https://my_android_lp.com"
}

Deferred deep linking

Entrada para onConversionDataSuccess(_ data: [AnyHashable: Any])

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