iOS Legacy APIs

직접 딥링킹

Overview

Direct deep linking directs mobile users into a specific activity or content in an app, when the app is already installed.

This in-app routing to a specific activity in the app is possible due to the parameters passed to the app when the OS opens the app and the 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.

The direct deep linking flow works as follows:
Direct Deep Linking flow

  1. 사용자가 원링크의 짧은 URL을 클릭합니다.
  2. iOS는 앱의 연관된 도메인 권한을 읽습니다.
  3. iOS가 앱을 실행합니다.
  4. 앱스플라이어 SDK가 앱 내에서 트리거됩니다.
  5. 앱스플라이어 SDK가 원링크 데이터를 검색합니다.
  • 짧은 URL에서, 데이터는 앱스플라이어 서버의 짧은 URL 리졸버 API에서 가져옵니다.
  • 긴 URL에서 데이터는 긴 URL에서 바로 가져옵니다.
  1. AppsFlyer SDK triggers onAppOpenAttribution() with the retrieved parameters and cached attribution parameters (e.g.install_time).
  2. Asynchronously, onConversionDataSuccess() is called, holding the full cached attribution data. (You can exit this function by checking if is_first_launch is true.)
  3. onAppOpenAttribution() uses the attributionData map to dispatch other activities in the app and pass relevant data.
    • 이렇게 하면 사용자에게 맞춤 경험을 생성하며, 이는 원링크의 주요 목적입니다.

Procedures

To implement the onAppOpenAttribution 메서드를 구현하고 파라미터 동작을 설정하려면, 다음 절차 체크리스트의 동작을 완료해야 합니다.

절차 체크리스트

  1. Deciding app behavior and deep_link_value (and other parameter names and values) - with the marketer
  2. Planning method input, i.e. deep_link_value (and other parameter names and values) - with the marketer
  3. Implementing the onAppOpenAttribution() logic
  4. Implementing the onAttributionFailure() logic

앱 작동 결정하기

링크를 누를 때 앱 동작을 결정하는 방법:

마케터로부터 링크를 클릭할 때 예상하는 동작을 얻습니다.

메서드 입력 계획

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: AnyHashable: Any.
The input data structure is described here.

onAppOpenAttribution() 로직 구현하기

The deep link opens the onAppOpenAttribution method in the main activity. The OneLink parameters in the method input are used to implement the specific user experience when the application is opened.

Code Example:

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

⇲ Github 링크: Swift

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

⇲ Github 링크: Swift

디퍼드 딥링킹

❗️

중요 정보

Deferred deep linking using the legacy method of onConversionDataSuccess may not work for iOS 14.5+, since it requires attribution data that may not be available due to privacy protection.
We recommend using unified deep linking (UDL). UDL conforms to the iOS 14.5+ privacy standards and only returns parameters relevant to deep linking and deferred deep linking: deep_link_value and deep_link_sub1. Attribution parameters (such as media_source, campaign, af_sub1-5, etc.), return null and can’t be used for deep linking purposes.
Learn more

Overview

디퍼드 딥링킹은 새로운 사용자를 먼저 올바른 앱스토어로 이동시켜 앱을 설치하도록 하고, 처음 앱을 연 후에는 특정 애플리케이션 환경(예: 앱 내의 특정 페이지)으로 이동시킵니다.

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 or other that is passed to the app when the OS opens the app.

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.

앱에서 파라미터를 올바르게 처리하고 인앱 라우팅 및 링크에서 데이터를 맞춤 설정하는 것은 개발자의 책임입니다.

The deferred deep linking flow works as follows:
Deferred Deep Linking flow!

  1. 사용자가 앱을 설치하지 않은 기기에서 원링크를 클릭합니다.
  2. 앱스플라이어가 클릭을 등록하고 사용자를 올바른 앱스토어나 랜딩 페이지로 리디렉션합니다.
  3. 사용자가 애플리케이션을 설치하고 이를 실행합니다.
  4. 앱스플라이어 SDK가 초기화되고, 설치는 앱스플라이어 서버에서 어트리뷰트됩니다.
  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. 파라미터는 is_first_launch has the value true, 이는 디퍼드 딥링크 흐름을 나타냅니다.
    개발자는 함수에 수신된 데이터를 사용하여 onConversionDataSuccess 애플리케이션의 첫 번째 실행을 위해 사용자를 위한 개인화된 환경을 만듭니다.

Procedures

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

  1. Deciding app behavior on first launch, and deep_link_value (and other parameter names and values) - with the marketer
  2. Planning method input, i.e. deep_link_value (and other parameter names and values) - with the marketer
  3. Implementing the onConversionDataSuccess() logic
  4. Implementing the onConversionDataFail() logic

처음 실행 시 앱 작동 결정하기

처음 실행 시 앱 작동을 결정하는 방법:

마케터로부터 링크를 클릭하고 처음으로 앱을 실행할 때 링크의 예상 동작을 얻습니다.

메서드 입력 계획

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 and other variables as an input like this: AnyHashable: Any.

맵에는 다음과 같은 두 가지 유형의 데이터가 있습니다.

  • 어트리뷰션 데이터
  • Data defined by the marketer in the link (deep_link_value and other parameters and values)
    Other parameters can be either:
    • 앱스플라이어 공식 파라미터.
    • 마케터와 개발자가 함께 정한 파라미터와 값.
    • 입력 데이터 구조는 여기에 설명되어 있습니다.

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. 원하는 앱 동작을 구현하려면 필요한 파라미터와 값을 마케터에게 알립니다.
  2. Decide on naming conventions for the deep_link_value and other parameters and values.
    Note:
    • 사용자정의 파라미터는 앱스플라이어에서 수집된 로데이터에 표시되지 않습니다.
    • 전환 데이터는 소문자 "n"을 포함해 "name"으로 명명된 사용자정의 파라미터를 반환하지 않습니다.

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.

로직을 구현하는 방법:

  1. 선택한 파라미터와 값을 기반으로 로직을 구현합니다. 아래 코드 예시를 참고하십시오.
  2. 완료되면 앱이 적절하게 동작하는지 마케터에게 알립니다.

샘플 코드

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

⇲ Github 링크: Swift

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 메서드:

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

⇲ Github 링크: Swift

iOS 샘플 페이로드

유니버설 링크, URI 스킴 및 디퍼드 딥링킹에 대한 다음 샘플 페이로드를 참조하세요. 샘플에는 원링크 사용자정의 링크 설정 페이지의 모든 파라미터에 데이터가 포함되어 있는 경우, 이와 관련된 전체 페이로드가 포함되어 있습니다.

일러두기: 페이로드가 맵으로 반환됩니다. 그러나 명확성을 위해 다음과 같은 샘플 페이로드가 JSON 양식으로 표시됩니다.

Universal Links

다음에 입력합니다. 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

다음에 입력합니다. 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

다음에 입력합니다. 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"
}