iOS SDK 기본 연동

Singular iOS SDK
다운로드 Singular iOS SDK version 10.3.0
호환성 iOS 8+
샘플 앱

Singular SDK를 전체적으로 연동한 샘플 앱을 확인해주세요. 베스트 프랙티스에 기반하여 여러 연동 부분이 어떻게 결합될 수 있는지 확인하세요.

연동 가이드

 

SDK 설치

Singular SDK를 가장 간편하게 연동하는 방법으로 CocoaPods 사용을 강력히 권장합니다.

CocoaPods 사용

  • 앱의 podfile에 Singular pod를 다음처럼 추가하세요.
  • podfile의 디렉터리에서 `pod install`을 실행하세요.
...
target 'APP' do
  pod 'Singular-SDK'
end

Singular 스태틱 라이브러리 사용

  • SDK를 다운로드하고 압축 해제합니다.
  • App Name > Add Files To <Your Project Name>를 클릭합니다.
  • 대화 창에서 Options > Create Groups를 선택하고 SDK 압축을 해제한 폴더를 선택합니다.
  • 프로젝트에 다음 파일이 포함됩니다: libSingular.a, Singular.h, SingularLinkParams.h, and Singular.js
  • App Name > Build Phases를 클릭하고 Link Binary With Libraries를 확장합니다.
  • + 아이콘을 클릭하고 다음 라이브러리를 추가합니다.
    • libsqlite3.0.tbd
    • SystemConfiguration.framework
    • Security.framework
    • libz.tbd
    • AdSupport.framework
    • iAd.framework
    • StoreKit.framework
    • AdServices.framework (iOS 14.3 이상의 디바이스에서만 사용 가능합니다. 또한 Build Settings 하단의 Other Linker Flags에 `-weak_framework AdServices`를 추가해야 합니다.

주의: 빌드에 실패한 경우 libSingular.a가 위치한 디렉터리를 프로젝트의 "Library Search Paths" (Build Settings > Search Paths > Library Search Paths)에 명시적으로 추가하세요.

Singular 라이브러리 임포트

AppDelegate 파일에 다음 코드를 추가하여 Singular 클래스 라이브러리를 임포트합니다

Objective-C:

// Cocoapods로 설치한 경우
#import <Singular.h>

// 수동으로 설치한 경우
#import "Singular.h"

SDK 초기화

주의: Singular SDK를 연동할 때, GDPR, CCPA 및 COPPA 등 비즈니스를 수행하는 지역에서 제정된 다양한 개인 정보 보호법 준수에 유의하세요. 더 자세한 내용은 SDK Opt-In and Opt-Out Practices 문서에서 확인할 수 있습니다.

SDK 초기화 코드는 앱이 열릴 때마다 호출돼야 합니다. 이는 Singular의 어트리뷰션 기능이 동작하기 위한 전제 조건이자, Singular에 새 세션을 보내서 유저 리텐션을 계산하는 기준으로 사용됩니다.

주의: 앱에 Swift를 사용하는 경우, 아래의 "Swift 사용" 항목에서 브리징 헤더를 만드는 방법과 예제 코드를 참조하세요.

대부분에 앱에서는 다음 예제처럼 applicationDidBecomeActive 메서드에서 초기화를 할 수 있습니다.

Objective-C:

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [Singular startSession:@"yourAPIKey" withKey:@"yourSecret"];
}

Swift (requires bridging header):

func applicationDidBecomeActive(_ application: UIApplication) {
    Singular.startSession("yourAPIKey", withKey: "yourSecret")
}

선택 사항: Session 타임아웃 설정

기본적으로 만약 앱이 포그라운드로 되돌아오기 전 백그라운드에서 60초 이상 머무른 경우, Singular SDK는 새로운 세션을 등록합니다. 이 기본 타임아웃 값은 setSessionTimeout  메서드를 사용하여 변경할 수 있습니다.

setSessionTimeout 메서드
정의 세션 타임아웃 값 변경
메서드 +(void)setSessionTimeout:(int)timeout
사용예

Objective-C:

[Singular setSessionTimeout:120];

Swift (requires bridging header):

Singular.setSessionTimeout(120)

Singular로 유저 ID 전송

선택 사항으로 Singular SDK를 사용하여 앱에서 Singular로 유저 ID를 전달할 수 있습니다. 유저 ID는 유저네임, 이메일 주소, 랜덤 생성 문자열 등 유저를 식별하는 어떤 값이라도 가능합니다. Singular로 전달한 유저 ID는 유저레벨 데이터를 추출하거나 고객사가 내부 BI 포스트백을 설정한 경우 포스트백 내의 데이터 형태로 전달될 수 있습니다.

Singular에 유저 ID를 보내려면 setCustomUserId 메서드를 호출하세요. ID 설정을 해제하려면 unsetCustomUserId 메서드를 사용합니다. 예를 들어 유저가 로그아웃하는 경우 사용할 수 있습니다.

주의:
  • 유저 ID는 unsetCustomUserId 호출을 통해 설정을 해제하거나 앱이 삭제되기 전까지 유지됩니다. 앱을 닫거나 재시작하는 것으로는 유저 ID 설정이 해제되지 않습니다.
  • 앱이 열리는 시점에 유저 ID를 이미 식별할 수 있고 첫 세션부터 Singular에 이를 포함해서 보내고자 한다면 Singular SDK 초기화를 하기 전에 유저 ID를 먼저 설정하세요.
setCustomUserId 메서드
정의 Singular에 유저 ID 전송
메서드 +(void)setCustomUserId:(NSString*)customUserId
사용예

Objective-C:

[Singular setCustomUserId:@"a_user_id"];

Swift (bridging header 필요):

Singular.setCustomUserId("custom_user_id")
unsetCustomUserId 메서드
정의 Unset the user ID that has been sent to Singular.
메서드 +(void)unsetCustomUserId;
사용예 Objective-C:
[Singular unsetCustomUserId];

Swift (bridging header 필요):

Singular.unsetCustomUserId()

[NEW] AppTrackingTransparency 동의 처리

주의: Apple은 발표를 통해 iOS 14.5부터 디바이스 IDFA에 접근하기 위해서는 앱 추적 투명성(App Tracking Transparency, ATT) 팝업창이 요구된다고 밝혔습니다. iOS 14.5의 공식 릴리즈 전에는 AppTrackingTransprency 팝업창을 구현하지 않기를 권장합니다.

Starting with iOS 14.5부터 앱이 디바이스의 IDFA 값을 포함한 유저 데이터 일부에 접근하기 전에 앱 추적 투명성(App Tracking Transparency) 프레임워크를 통해 유저 동의를 받아야 합니다.

Singular는 인스톨 어트리뷰션을 수행한 디바이스를 식별하기 위해 IDFA를 사용해 왔습니다. (물론 IDFA 없이도 어트리뷰션을 수행하는 방법도 있었습니다.) IDFA를 얻으려면 유저 동의를 구하는 것을 적극적으로 권장합니다.

또한 유저 세션을 Singular로 보내기 전에 SDK가 대기하도록 해야합니다. Singular SDK는 기본적으로 유저 세션을 초기화 시점에 전송하며, 세션이 신규 디바이스에서 발송되면 이는 즉시 Singular의 어트리뷰션 절차를 시작합니다. 이 프로세스는 Singular가 해당 시점에 사용할 수 있는 데이터에 의존하게 됩니다.

따라서 Singular SDK가 세션을 발송하기 전에 유저 동의를 구하고 IDFA를 확인할 수 있도록 해야 합니다.

유저 세션 전송을 지연하려면 아래 샘플 코드를 참조해서 waitForTrackingAuthorizationWithTimeoutInterval 옵션과 함께 Singular SDK를 초기화하세요.

  1. SDK가 세션 및 유저 이벤트를 기록을 시작하지만 Singular 서버에는 보내지 않습니다.
  2. App Tracking Transparency 동의가 수집되거나 거부되는 즉시, 혹은 타이머가 끝나는 시점에 SDK가 세션과 큐에 담긴 이벤트를 Singular 서버에 보냅니다. (해당 시점에 IDFA가 있으면 있는 상태로, 없으면 없는 상태로 보내집니다.)
  3. Singular에서 어트리뷰션 절차를 진행합니다. IDFA가 수집 가능한 상태이면 ID 기반으로 어트리뷰션을, 가능하지 않다면 확률론적 어트리뷰션을 수행합니다.

예제 코드:

SingularConfig* config = 
[[SingularConfig alloc] initWithApiKey:apiKey andSecret:secretKey];
// SKAdNetwork 트래킹 등록 config.skAdNetworkEnabled = YES
// 이벤트를 보내기 전 트래킹 권한 획득을 5분간 기다립니다. config.waitForTrackingAuthorizationWithTimeoutInterval = 300
// 시작 [Singular start:config];
// 유저 동의 절차를 시작하기 위해
// ATTrackingManager로부터 requestTrackingAuthorizationWithCompletionHandler 호출 [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:
^(ATTrackingManagerAuthorizationStatus status){     // 권한 핸들러를 여기에 둡니다     // 주의: Singular SDK는 자동으로 권한 획득 혹은 거부 상태를 파악하고
// 초기화됩니다. }];

다음 표에서 본 연동시 발생 가능한 시나리오를 확인할 수 있습니다.

시나리오 IDFA 사용 가능성
유저가 동의 대화상자를 보고 타이머가 끝나기 전 동의 수행 IDFA 사용 가능
유저가 동의 대화상자를 보고 타이머가 끝나기 전 동의 거부 IDFA 사용 불가
타이머가 끝난 이후 유저가 동의 대화상자를 보고 동의 수행 동의를 획득한 이후 발생한 유저 이벤트에만 IDFA 사용 가능
타이머가 끝난 이후 유저가 동의 대화상자를 보고 동의 거부 IDFA 사용 불가
유저가 동의 대화상자를 보았지만 선택하지 않고 앱을 종료한 후 앱을 재실행해서 타이머가 끝난 이후 동의 수행 앱이 재실행될 때 큐에 담긴 모든 이벤트가 Singular 서버로 전송되며 IDFA는 해당 이벤트에 사용 불가. 동의 획득 이후 트래킹된 이벤트는 IDFA 사용 가능.
유저가 동의 대화상자를 보았지만 선택하지 않고 앱을 종료한 후 앱을 재실행해서 타이머가 끝난 이후 동의 거부 앱이 재실행될 때 큐에 담긴 모든 이벤트가 Singular 서버로 전송되며 해당 이벤트와 이후 트래킹된 모든 이벤트에서 IDFA 사용 불가

Swift 사용

Swift 앱에서 Objective-C 코드를 사용하려면 브리징 헤더를 생성해야 합니다.

  • Objective-C 브리징 헤더 파일을 생성하는 방법은 Apple의 영문 공식 문서(Swift documentation on language interoperability)를 참조하세요.
  • "*-Bridging-Header.h" 파일에 다음 예제처럼 Singular 라이브러리를 임포트하세요.
//  *-Bridging-Header.h
#import "Singular.h"
도움이 되었습니까?