마케터용 iOS SDK 연동 가이드

배경

iOS 14.5부터, IDFA를 수집하려면 사용자의 동의가 필요합니다. 이는 실제로 IDFA 액세스를 앱 추적 투명성(ATT) 프레임워크가 통제한다는 의미입니다. 기기가 iOS 14 이상일 경우, SDK는 ATT 프레임워크를 사용하여 기기 IDFA 액세스 권한을 얻습니다. 

ATT에 대한 소개는 ATT 원칙을 참조하십시오.

IDFA를 이용하여 어트리뷰션을 할 경우, IDFA는 앱 최초 실행 시점에 전송되어야 합니다. 이를 위해, 앱스플라이어 SDK는 waitForATTUserAuthorization 유틸리티를 제공합니다. 

waitForATTUserAuthorization overview

waitForATTUserAuthorization로 앱스플라이어 SDK가 앱스플라이어 서버로 데이터를 전송하기 전 ATT 상태를 위해 대기하는 시간을 설정할 수 있습니다.

사용자가 앱을 실행하는 시점에는 ATT 상태가 결정되지 않습니다. waitForATTUserAuthorization 타임아웃 시간 동안,

• SDK는 앱 실행 이벤트와 연속적인 인앱 이벤트 인메모리(in-memory)를 오프라인 이벤트가 기록되는 방식과 유사하게 순차적으로 기록합니다.
• 사용자가 ATT 프롬프트(IDFA 컬렉션)에 동의하는 경우:
  • SDK가 IDFA를 임시 저장된(cached) 이벤트에 추가합니다.
  • SDK가 (타임아웃을 기다리지 않고) 바로 구동되어 임시 저장된 이벤트를 IDFA와 함께 전송합니다.
• 사용자가 ATT 프롬프트를 거부하는 경우:
  • SDK가 (타임아웃을 기다리지 않고) 바로 구동되어 임시 저장된 이벤트를 IDFA 없이 전송합니다.
• 타임아웃이 되고 ATT 상태가 notDetermined이면
  • SDK가 시작되어 임시 저장한 이벤트를 IDFA 없이 전송합니다.

고려 사항 

• waitForATTUserAuthorization을 설정하지 않고 requestTrackingAuthorization을 호출하면 iOS 14 이상의 기기에 대한 IDFA 없이 실행 및 이벤트가 전송됩니다.
• 사용자가 타임아웃 중간에 앱을 백그라운드로 이동시키면,
  • 앱이 휴대폰 화면(foreground)에 표시될 때까지 타이머가 일시 중지됩니다.
  • 이벤트는 인-메모리에 캐시됩니다.
• 제한 시간 내 앱 사용자가 앱을 닫거나, 앱이 종료되면,
  • 다음 앱 실행 시점에 타이머가 재시작합니다.
  • 캐시 이벤트가 손실됩니다.

ATT 대화 상자를 사용자 정의하도록 선택할 수 있습니다. 요청의 목적을 명확히 설명하는 메시지는 사용자의 선택 비율을 높이는 데 도움이 될 수 있습니다.

메시지를 작성할 때 다음 사항에 유의하십시오.

• 앱이 사용자 동의를 요청하는 이유를 가장 잘 설명하는 표현을 사용합니다.
• 사용자에게 데이터 사용 방법을 알려줍니다. 사용자 개인 정보 보호 및 데이터 사용에 대한 자세한 내용을 보려면 여기를 클릭하십시오.

메시지가 완료되면 개발자에게 텍스트와 해당 지침을 제공합니다.

ATT 대화 상자의 외부 예를 보려면 여기를 클릭하십시오.

SKAdNetwork는 iOS가 사용하는 클래스이며, 앱 설치가 광고에 기인해서 발생했는지 검증합니다. 이 앱 설치 유효성 검증 프로세스에는 소스(source) 앱과 광고 대상 앱이 있습니다. 

소스(source) 앱은 광고 네트워크가 서명한 광고를 자신의 지면에 게재하여 광고 캠페인에 참여하는 앱입니다. 광고를 게재하도록 앱을 구성하는 작업은 앱스플라이어 SDK 범위 내에 없습니다. 광고 게재를 위한 작업은Apple 가이드를 따르십시오.

(앱스플라이어 SDK가 설치된) 광고주 앱에 대해서, 앱스플라이어의 SKAdNetwork 솔루션은 Apple의 SKAdNetwork 프레임워크를 이용하여 어트리뷰션 포스트백을 제공합니다. 앱스플라이어는 데이터를 수집, 해석, 집약하고 동시에 개인정보를 보호합니다. 앱이 설치된 후 처음 실행되면, 앱스플라이어 플랫폼은 앱 광고주(마케터)가 설정한 상태에 따라 SDK에 SKAdNetwork 전환 값을 설정하는 방식을 지시합니다.

SKAdNetwork 솔루션을 사용하는 방법:

• 마케터는 앱스플라이어에서 SKAdNetwork 측정을 설정해야 합니다. 개발자는 어떠한 작업도 수행할 필요가 없습니다.
• 앱스플라이어 SDK는 필요한 SKAdNetwork API를 자동으로 호출합니다.
• 앱스플라이어에 의존하여 SKAddNetwork 어트리뷰션을 사용하는 경우 다른 SDK에서 SKAdNetwork 호출을 사용하지 않도록 설정해야 합니다.
•  App Store에서 개발자나 마케터가 해야 할 작업이나 등록 절차는 없습니다. 

SKAdNetwork 어트리뷰션을 비활성화하려면 개발사에 SDK에서 비활성화하도록 지시합니다. 

어떤 인앱 이벤트로도 수익 값을 보낼 수 있습니다. 수익을 포함하려면 af_revenue 파라미터를 사용해야 합니다. 앱스플라이어가 대시보드와 로데이터에서 실제 수익으로 계산하는 유일한 이벤트 파라미터입니다. 자세한 사항을 보려면 여기를 클릭하십시오. 

개발사 지침은 수익 기록을 참조하십시오.

앱스플라이어의 SDK는 인앱 구매에 대해서 서버 확인 기능을 제공합니다. 구매 검증을 통과하면 앱스플라이어로 인앱 구매 이벤트가 자동 전송됩니다. 그러므로 이 이벤트를 따로 직접 전송하면 인앱 구매 내역이 이중으로 기록됩니다.

앱이 여행, 게임 또는 이커머스와 같은 수직 구조에 속하는 경우 수직 구조별로 권장되는 인앱 이벤트 목록을 참조하십시오.

앱을 설치하지 않은 사용자의 경우 원링크는 장치 유형을 검색하여 올바른 대상(예를 들어, Google Play, Apple App Store, 타사 앱 스토어 또는 웹 페이지)으로 리디렉션합니다. 이것은 원링크 템플릿 설정에 기반합니다. 더 알아보기

일러두기: 기기 감지 및 리디렉션에는 앱스플라이어 SDK가 필요하지 않습니다. 그러나, 딥링킹에서는 SDK가 필요합니다.

앱을 설치한 사용자에 대해 원링크는 앱을 열어줍니다. 앱을 열 뿐만 아니라 앱 내의 특정 활동이나 페이지로 사용자를 딥링킹할 수도 있습니다. 이렇게 하려면 개발사가 통합 딥링킹(UDL)을 구현해야 합니다.

일러두기:

• UDL은 SDK V6.1 이상을 요구합니다.
• 딥링킹에 원링크를 이미 사용하고 있는 고객은 UDL 대신 레거시 방법을 사용하고 있을 수 있습니다.

원링크로 딥링킹 설정하기 가이드에서 상세 설명을 확인하십시오.

앱을 설치하지 않은 사용자의 경우 원링크는 장치 유형을 검색하여 올바른 대상(예를 들어, Google Play, Apple App Store, 타사 앱 스토어 또는 웹 페이지)으로 리디렉션합니다. 사용자가 앱을 실행하면 디퍼드 딥링킹을 사용하여 앱 내의 특정 활동 또는 페이지로 리디렉션할 수 있습니다.

이렇게 하려면 개발사가 통합 딥링킹(UDL)을 구현해야 합니다.

일러두기:

• UDL은 SDK V6.1 이상을 요구합니다.
• 디퍼드 딥링킹에 원링크를 이미 사용하고 있는 고객은 UDL 대신 레거시 방법을 사용하고 있을 수 있습니다.

자세한 내용은 디퍼드 딥링킹에 대한 가이드를 참고하십시오.

앱스플라이어는 모든 벤더의 푸시 알림 캠페인 측정을 지원하며 Google 클라우드 메시징 또는 Apple 푸시 알림 서비스를 직접 사용하는 개발사도 지원할 수 있습니다. 앱으로 정의된 전환은 푸시 알림 메시지에서 시작하여 리타게팅 대시보드에 표시됩니다.

원링크를 사용하여 푸시 알림을 통해 사용자 리인게이지먼트를 측정할 수 있습니다. 푸시 알림 리인게이지먼트 캠페인 측정에 대한 안내서를 참조하십시오.

앱 삭제 측정을 셋팅하는 방법에 대해서는 여기를 읽어보십시오.

SDK가 정상적으로 구동되어 앱스플라이어 서버가 어트리뷰션 확인 요청을 수신했다는 확인 메시지를 받기 위해서,startWithCompletionHandler 핸들러를 구현하십시오. 이 논리를 적용하여 SDK 구동 성공 또는 실패를 처리할 수 있습니다.

구현 예시

[[AppsFlyerLib shared] startWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
    }];

 AppsFlyerLib.shared()?.start(completionHandler: { (dictionnary, error) in
            if (error != nil){
                print(error ?? "")
                return
            } else {
                print(dictionnary ?? "")
                return
            }
        })

Request Listner에서 에러가 발생하면, 다음과 같은 에러 코드와 설명이 제공됩니다.

setAdditionalData API를 사용하면 SDK에서 보낸 이벤트에 사용자정의 데이터를 추가할 수 있습니다. 일반적으로 SDK 수준에서 Segment, Adobe 및 Airship을 비롯한 여러 외부 파트너 플랫폼과 통합하는 데 사용됩니다.

setAdditionalData 코드 예시:

NSDictionary* customDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
[[AppsFlyerLib shared] setAdditionalData:customDataMap];

let customDataMap: [AnyHashable: Any] = [
  "custom_param_1" : "value_of_param_1"
]
AppsFlyerLib.shared().customData = customDataMap

앱 소유주가 원링크 없이 유니버설 링크를 사용하고 앱과 연과된 도메인이 있으면, appendParametersToDeepLinkingURL 메서드를 사용하여 앱 세션을 어트리뷰션 할 수 있습니다.

예를 들어 엔드유저가 구글 검색을 통해 광고주의 도메인, www.example.com을 클릭합니다.

• 이 때, 엔드유저의 기기에 앱이 설치되지 않았으면 웹사이트(www.example.com)으로 리디렉션 됩니다.
• 앱이 설치되어 있으면, www.example.com와 연관된 앱으로 딥링킹됩니다. 이 앱 세션(앱 오픈)은 appendParametersToDeepLinkingURL에 정의된 미디어 소스(pid 파라미터)에 어트리뷰션 됩니다.

상세 내용은 iOS SDK 참고를 확인하세요.

일러두기: 스마트 배너는 앱 소유주가 웹사이트 방문객을 앱 사용자로 전환시키도록 지원합니다.

기본 설정으로는, 앱을 실행할 때의 간격이 적어도 5초 이상이 되어야 두 개의 별도 세션으로 집계합니다(세션 집계에 대해 알아보기).

다음 API를 사용하여 세션 사이의 최소 필요시간을 설정합니다:

[AppsFlyerLib shared].minTimeBetweenSessions = <your_custom_time_in_seconds>;

AppsFlyerLib.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>

너무 높은 값을 세션 간격 시간으로 설정하면 딥링킹과 같이 세션 데이터를 사용하는 API에 문제가 생길 수 있습니다.

iOS에서는 사용할 수 없습니다.

이메일 서비스 제공 업체들 과 같은 몇몇 외부 업체 서비스 사는 이메일 내의 링크를 자체 클릭 기록 도메인으로 래핑(wrapping)합니다. 어떤 업체는 자신의 클릭 기록 도메인을 직접 설정하도록 허용하기도 합니다. 만약 원링크가 이런 도메인들에서 래핑된다면, 원링크의 기능이 제한될 수 있습니다.

이 문제를 해결하기 위해 setResolveDeepLinkURLs API를 사용할 수 있습니다. 이 API를 사용하여 앱을 시작하는 클릭 도메인에서 원링크를 가져 오십시오. 반드시 SDK 초기화 전에 이 API를 호출해야합니다.

예를 들어, 당신의 원링크(https://mysubdomain.onelink.me/abCD)로 리다이렉션되는 세 개의 클릭 도메인이 있습니다. 이 API를 사용하여 클릭 도메인이 리다이렉션하는 원링크를 가져오십시오. 이 API 메서드는 SDK가 분석하는 도메인 목록을 수신합니다.

[AppsFlyerLib shared].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

AppsFlyerLib.shared().resolveDeepLinkURLs = ["example.com", "click.example.com"]

위의 코드를 사용하면 원링크 기능을 유지하면서 자체 클릭 도메인을 사용할 수 있습니다. 여기에서 클릭 도메인은 앱 실행을 담당합니다. 대신 API가 이 클릭 도메인에서 원링크를 가져오고, 이 원링크에서 데이터를 확보하여 맞춤식 콘텐츠로 딥링크 하는데 사용할 수 있습니다.

앱스플라이어를 사용하여, 리타겟팅 캠페인 중 일부인 푸시 알림 성과를 측정할 수 있습니다.

이 기능을 사용하려면 AppDelegate.m 내에서 handlePushNotificationData 메서드를 호출하십시오.

-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[[AppsFlyerLib shared] handlePushNotification:userInfo];
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    AppsFlyerLib.shared().handlePushNotification(userInfo)
}

푸쉬 알림 측정에 대한 더 자세한 내용은 여기에서 확인하실 수 있습니다.

기존 사용자가 친구나 아는 사람을 앱의 신규 사용자로 초대하도록 하는 것은 앱 사용자를 늘리는데 크게 기여할 수 있습니다. 앱스플라이어를 사용하면 앱 내 사용자 초대에서 발생한 설치를 어트리뷰트하고 기록할 수 있습니다.

더 자세한 내용은 사용자 초대 어트리뷰션 안내를 참조하십시오.

주의! IDFV를 사용한 크로스 프로모션 성과 측정은 SDK 6.0.2부터 지원됩니다. IDFV는 자동 수집되며 개발자가 별도로 할 작업은 없습니다.

앱스플라이어 고유 ID는 앱이 새로 설치될 때마다 생성됩니다. 이 ID는 다양한 목적으로 사용할 수 있습니다.

• 서버 간 인앱 이벤트(server-to-server in-app events) 보내기.
• AppsFlyer ID와 백엔드 시스템의 사용자 기록을 맞추기.
• Pull API 또는 Push API로 수신한 데이터 병합하기

앱스플라이어의 고유 ID를 얻기 위해서 다음 API를 사용하십시오.

NSString *appsflyerId = [AppsFlyerLib shared].getAppsFlyerUID;

let appsflyerId = AppsFlyerLib.shared().getAppsFlyerUID()

다음을 통해 고객 사용자 ID를 설정하세요:

[AppsFlyerLib shared].customerUserID = @"my user id";

AppsFlyerLib.shared().customerUserID = "my user id"

iOS에서는 앱을 시작할 때마다 매번 Customer User ID를 설정해야합니다. Customer User ID를 설정한 이후에만 인앱 이벤트 기록이 연결되어 보고되므로, 앱 사용 과정 초기에 CUID를 설정할 것을 추천드립니다

• 만약, setCustomerUserId 가 startTracking을 호출하기 이전에 호출된다면, 인스톨 및 이벤트 로데이터 리포트에 CUID(Customer User ID) 정보가 포함되어 표시됩니다.
• CUID(Customer User ID)를 나중에 설정하면, CUID는 CUID를 설정한 이후에 기록된 이벤트만 연결됩니다.

첫 번째 앱 실행 후 고객 사용자 ID 값이 다시 설정되지 않도록 하기 위하고, 고객 사용자 ID를 얻기 위한 서버 호출을 줄이기 위해서, 다음 구문을 사용하여 값이 비어 있는지 여부를 확인할 수 있습니다:

NSString *customerUserID = [AppsFlyerLib shared].customerUserID;

let customerUserID = AppsFlyerLib.shared().customerUserID

고객 사용자 ID에 대해 더 자세히 알아보려면 여기를 클릭하세요.

CUID가 설정될 때까지 SDK 동작을 지연시킬 수 있습니다. 앱 설치 및 이벤트 데이터에 고객 사용자 ID가 포함되는 것이 중요한 경우에 유용하게 사용될 수 있습니다.

다음 코드를 구현하십시오:

- (void)applicationDidBecomeActive:(UIApplication *)application {
    NSString *customUserId = [[NSUserDefaults standardUserDefaults] stringForKey:@"customerUserId"]; // Your custom logic of retrieving CUID
    if (customUserId != nil && ![customUserId  isEqual: @""]) {
        [AppsFlyerLib shared].customerUserID = customUserId; // Set CUID in AppsFlyer SDK for this session
        [[AppsFlyerLib shared] start]; // Start
    }
}

func applicationDidBecomeActive(_ application: UIApplication) {
        let customUserId = UserDefaults.standard.string(forKey: "customUserId")  //  your logic to retrieve CUID
        if(customUserId != nil && customUserId != ""){
            AppsFlyerLib.shared().customerUserID = customUserId // Set CUID in AppsFlyer SDK for this session
            AppsFlyerLib.shared().start() // Start
        }
    }

고객 사용자 ID가 가능할 때까지 SDK 초기화를 지연시키는 것에 대해 더 자세한 내용을 보시려면 여기로 이동하십시오.

사용자의 동의(예: GDPR 또는 COPPA가 요하는 개인 정보 공유 동의)를 얻을 때까지, SDK 실행과 데이터 전송을 지연시킬 수 있습니다.

일러두기: 이는 iOS 14에 도입된 앱 추적 투명성(ATT, App Tracking Transparency)과 관련이 없습니다. 

SDK 시행을 지연시키려면:

1. 세션이 배경(background)-전경(foreground) 전환 시 전송되지 않도록 합니다. sendLaunch() 메서드 (위 3.3번 참조, applicationDidBecomeActive마다 호출됨)에서, start 와 컨디션 체크로 호출을 래핑(wrapping)합니다. 예:
   
   

   -(void)sendLaunch:(UIApplication *)application {
       if (consent_given) { // check the condition
           [[AppsFlyerLib shared] start]; // Start
       }
   }

2. SDK 실행을 지연할 이유가 사라지면, 즉, 컨디션이 변경되면 바로 세션을 전송합니다. 첫 번째 세션 데이터를 전송할 준비가 되었으면,  start 를 호출합니다. 예:
   
   

   ...
   consent_given = YES; // change the condition
   [[AppsFlyerLib shared] start]; // Start
   ...

간혹, 법률 및 개인 정보 보호 준수를 위해서 모든 SDK 데이터 기록(logging)을 중단해야 하는 경우가 있을 수 있습니다. 데이터 기록 중단 작업은 isStopped 속성을 설정하여 수행할 수 있습니다. 이 속성이 true로 세팅되면, 앱스플라이어 SDK 작동이 중단되고 더 이상 애스플라이어 서버와 통신하지 않습니다.

서로 다른 몇 가지 사용자 옵트아웃 시나리오가 있습니다. 앱과 관련된 각 시나리오에 맞는 정확한 지침을 따르는 것을 권장합니다.

[AppsFlyerLib shared].isStopped = true;

AppsFlyerLib.shared().isStopped = true

어떤 이벤트에서든 이 API에 false를 넘기면서 호출하면 SDK를 다시 활성화할 수 있습니다.

SDK를 초기화하는 동안 다음 API를 사용하면, 사용자의 설치, 이벤트, 세션을 명시적으로 익명처리 할 수 있습니다.

[AppsFlyer shared].anonymizeUser = YES;

AppsFlyerLib.shared().anonymizeUser = true

anonymizeUser 를 false로 설정하여 데이터 로깅을 재시작할 수 있습니다.

앱스플라이어 strict mode SDK를 사용하여 IDFA 수집 기능과 AdSupport 프레임워크 의존성을 완전히 제거합니다. (예를 들어 어린이용 앱 개발 시)

일러두기: IDFV는 계속 사용가능합니다.

Podfile에서 AppsFlyerLib 의존성을 다음으로 대체합니다.

pod 'AppsFlyerFramework/Strict','6.2.3'

AdSupport와 iAd framework를 비활성화하기 위해, 앱스플라이어 SDK는 다음과 같은 setter를 제공합니다.

• disableCollectASA = true. 더 알아보기
• disableAdvertisingIdentifier = true. 더 알아보기

광고 프레임워크 비활성화하기

[AppsFlyerLib shared].disableCollectASA = YES
[AppsFlyerLib shared].disableAdvertisingIdentifier = YES;

AppsFlyerLib.shared().disableCollectASA = true
AppsFlyerLib.shared().disableAdvertisingIdentifier = true

광고주는 특정 사용자들의 사용자 레벨 데이터를 애드 네트워크/파트너사와 공유하지 않을 경우가 있습니다. 사용자 정보를 공유하지 않는 이유는 다음과 같습니다. 

• CCPA나 GDPR과 같은 개인정보 보호 정책 준수
• 사용자 옵트아웃(개인정보 제 3자와의 공유 거부)
• 파트너사(애드 네트워크, 제 3자 기업)가 경쟁사이기도 한 경우

앱스플라이어는 일부 또는 모든 파트너와 데이터 공유를 중단하는 API 메서드를 다음과 같이 두 가지 제공합니다.

• setSharingFilter: 광고주가 하나 이상의 일부 애드 네트워크/연동 파트너와 데이터를 공유할 때 사용합니다.
• setSharingFilterForAllPartners: 광고주가 모든 애드 네트워크/연동 파트너와 데이터 공유를 중단할 때 사용합니다.

이 필터링 메서드는 SDK V5.4.1.에서부터 지원됩니다.

이 필터링 메서드는 SDK가 구동을 시작할 때마다 호출되어야 하고 전체 세션에 영향을 미칩니다. 파트너와의 데이터 공유 필터를 설정해야할지 여부를 판단하는데 시간이 걸리면, SDK 구동 시작을 지연시키십시오. 

이 메서드가 첫 번째 start 호출 이전에 활성화되면

• SRN에서 유입된 사용자들이 오가닉으로 기록되고 사용자 정보는 연동 파트너와 공유되지 않습니다.
• 애드 네트워크(SRN 제외) 클릭으로 유입된 사용자 는 논오가닉으로 기록되지만 사용자 정보는 포스트백, API, 로데이터 리포트 혹은 다른 어떤 방법으로도 애드 네트워크와 공유되지 않습니다.

그런데 앱 삭제 데이터는 이 메서드를 이용하여 필터링할 수 없습니다. 대신, 앱스플라이어 대시보드 설정 화면에서 앱 삭제 이벤트를 파트너사에 전송하는 것을 중단할 수 있습니다.