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`를 추가해야 합니다.

Singular 라이브러리 임포트

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

Objective-C:

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

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

SDK 초기화

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

대부분에 앱에서는 다음 예제처럼 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  메서드를 사용하여 변경할 수 있습니다.

[Singular setSessionTimeout:120];

Singular.setSessionTimeout(120)

Singular로 유저 ID 전송

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

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

[Singular setCustomUserId:@"a_user_id"];

Singular.setCustomUserId("custom_user_id")

[Singular unsetCustomUserId];

Singular.unsetCustomUserId()

[NEW] AppTrackingTransparency 동의 처리

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는 자동으로 권한 획득 혹은 거부 상태를 파악하고
    // 초기화됩니다.
}];

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

Swift 사용

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

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

//  *-Bridging-Header.h
#import "Singular.h"