시작 전 단계: SDK 전제 조건 확인

Singular SDK 연동: 계획과 전제조건의 단계를 따르세요.

다음은 모든 Singular SDK 연동의 전제 조건들에 대한 단계입니다.  

1. SDK 설치

CocoaPods, Swift Package Manager, 또는 Static Library를 사용하여 Singular SDK를 설치할 수 있습니다.

2. 기본 SDK 연동 설정

2.1. Singular 라이브러리를 가져오기

SceneDelegate, AppDelegate, 또는 Singular가 사용될 모든 파일에, Singular 클래스 라이브러리를 가져와서 Singular SDK를 사용하세요.

// If installed with Cocoapods or Swift Package Manager
    #import Singular
          
    // If installed manually in Objective-C
    #import "Singular.h"

2.2. 구성 오브젝트 생성

코드에서 Singular 기능을 초기화하기 전에, Singular 구성 오브젝트를 반드시 생성하고 구성 옵션을 설정하세요. 이 코드 블록은 SceneDelegate에 추가해야합니다. (SceneDelegate를 사용하지 않는다면, AppDelegate에 추가하세요).

다음 코드 예시는 구성 오브젝트를 생성하고, SKAdNetwork의 Managed Mode를 활성화하거나 ATT응답을 대기하는 타임아웃 설정과 같은 공통적인 구성 옵션을 설정합니다. 

다음은 각 옵션과 커스텀 방법에 대한 자세한 설명입니다. 

예시: 오브젝트 구성과 특정 공통 옵션 생성 

func getConfig() -> SingularConfig? {
          print(Date(), "-- Scene Delegate getConfig")
          // Create the config object with the SDK Key and SDK Secret
          guard let config = SingularConfig(apiKey: Constants.APIKEY, andSecret:
          Constants.SECRET) else {
              return nil
          }
              
          // Enable SKAdNetwork in Managed Mode
          config.skAdNetworkEnabled = true
              
          // Set a 300 sec delay before initialization to wait for the user's ATT response
          // Remove this if you are not displaying an ATT prompt!
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
              
          // Support non-Singular Universal Links
          config.supportedDomains = ["www.your-website-domain.com"]
              
          // Support custom ESP domains
          config.espDomains = ["links.your-website-domain.com"]
              
          // Set a handler method for deep links
          config.singularLinksHandler = { params in
              self.processDeeplink(params: params)
          }
              
          return config
      }

- (SingularConfig *)getConfig {
          NSLog(@"-- Scene Delegate getConfig");
          
          // Create the config object with the SDK Key and SDK Secret
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY andSecret:SECRET];
          
          // Enable SKAdNetwork in Managed Mode 
          config.skAdNetworkEnabled = YES;
      
          // Set a 300 sec delay before initialization to wait for the user's ATT response
          // Remove this if you are not displaying an ATT prompt!
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
          // Support non-Singular Universal Links
          config.supportedDomains = @[@"www.your-website-domain.com"];
      
          // Support custom ESP domains
          config.espDomains = @[@"links.your-website-domain.com"];
      
          // Set a handler method for deep links
          config.singularLinksHandler = ^(SingularLinkParams * params) {[self processDeeplink:params];};
          
          return config;
      }

2.3. SKAdNetwork 옵션 커스텀

SKAdNetwork는 유저 프라이버시를 저해하지 않고 모바일 인스톨 어트리뷰션을 알아내는 Apple의 신규 프레임워크입니다. SKAdNetwork는 유저 개인의 신원을 확인할 수 있는 정보를 공유하지 않고 앱의 마케팅 캠페인에 대한 성과를 측정할 수 있게 합니다.  

Singular의 신규 iOS SDK 버전을 사용하면 최소한의 엔지니어 도움으로 완벽히 SKAdNetwork를 구현할 수 있습니다. 자세한 내용은, Singular SKAdNetwork 솔루션 소개를 참고하세요.

SKAdNetwork 활성화

SKAdNetwork 추적을 앱에서 활성화하려면, 2.2. 구성 오브젝트 생성에 보여지는 대로 Singular Config에 skAdNetworkEnabled 플래그를 추가하세요.

Managed Mode에서 SKAdNetwork 사용 (권장)

기본적으로, SKAdNetwork는 Managed Mode에서 활성화되며, 이는 서버 측으로부터 Singular에 의해 컨버전 값이 직접 관리되는 것을 의미합니다. Managed Mode를 사용하면, 앱이 SKAdNetwork를 다루는 데 있어 다른 코드를 추가하지 않아도 됩니다. 

이를 통해 고객 측 코드를 변경하지 않고도 Singular 웹 앱을 통해 컨버전 값들을 설정 및 변경할 수 있는 최대한의 유연성을 갖게 됩니다.  

서버 측 managed mode는 또한 SKAdNetwork 타이머를 다루는 데 도움이 됩니다. SKAdNetwork는 SKAdNetwork를 등록한 시간으로부터 24시간 이내 컨버전 값을 업데이트하도록 허용합니다. 컨버전 값을 업데이트하는 모든 호출은 타이머를 24시간 더 연장합니다. 그러므로, 컨버전 이벤트를 선택할 때, 이벤트들이 해당 업데이트 윈도우 내 발생하는 이벤트인지 확인해야 합니다. Managed mode에서 앱의 신규 버전을 출시하지 않고도 언제든 컨버전 이벤트 설정을 변경할 수 있습니다. 

Manual Mode에서 SKAdNetwork 사용 (고급)

func getConfig() -> SingularConfig? {
          // Singular Config Options
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
                  andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.skAdNetworkEnabled = true
          config.manualSkanConversionManagement = true
          ...
          return config
      }

- (SingularConfig *)getConfig {
          // Singular Config Options
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.skAdNetworkEnabled = YES;
          config.manualSkanConversionManagement = YES;
          ...
          return config;
      }

// Sending a Standard Event for Login
    Singular.event(EVENT_SNG_LOGIN)
      
    // Manually updating the conversion value to 7 after the Event
    Singular.skanUpdateConversionValue(7)

// Sending a Standard Event for Login
    [Singular event:EVENT_SNG_LOGIN];
      
    // Manually updating the conversion value to 7 after the Event
    [Singular skanUpdateConversionValue:7];

let conversionValue = Singular.skanGetConversionValue()

NSNumber* conversionValue = [Singular skanGetConversionValue]; 

func getConfig() -> SingularConfig? {
          // Singular Config Options
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET)
          else {         
              return nil     
          }     
          ...     
          config.conversionValueUpdatedCallback = { onversionValue in
              // Here you have access to the latest conversion value
          }
          ...
          return config
      } 

- (SingularConfig *)getConfig {
          // Singular Config Options
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.conversionValueUpdatedCallback=^(NSInteger conversionValue) {
              // Here you have access to the latest conversion value
          };
          ...
          return config;
      }

2.4. ATT 동의 처리 (초기화 지연 설정)

ATT (App Tracking Transparency) 프롬프트 표시

iOS 14.5 부로, 앱들은 디바이스의 IDFA를 포함하여 유저 데이터에 접근하여 추적에 필요한 일부 데이터를 공유하기 전 유저 동의를 구해게 되어있습니다. (App Tracking Transparency 프레임워크 사용) 

IDFA 없이 어트리뷰션을 수행하는 여러 방법들이 존재하나, Singular의 디바이스 및 유저 인스톨 성과 식별에 있어 IDFA 존재 여부는 매우 중요합니다. 그러므로, 유저의 동의를 얻어 IDFA를 획득하는 것을 강력히 권장합니다.

ATT 응답을 위해 초기화를 지연

기본적으로, Singular SDK는 초기화가 되면 유저 세션을 전송합니다. 세션이 신규 디바이스로부터 전송이 되면, Singular 어트리뷰션 과정을 바로 발생시키게 되는데, 어트리뷰션 과정은 Singular에 존재하는 데이터만을 기반으로 수행됩니다. 그러므로, Singular SDK가 첫 세션을 전송하기 전에 동의를 구하여 IDFA를 얻는 것이 중요합니다.  

유저 세션 전송을 지연시키기 위해서는, Config 오브젝트 내 waitForTrackingAuthorizationWithTimeoutInterval 옵션을 통해 Singular SDK를 초기화하세요. 이 옵션에는 2.2. 컨피규레이션 오브젝트 생성의 코드 샘플이 포함되어 있습니다.

func getConfig() -> SingularConfig? {
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
          ...
          return config
      }

- (SingularConfig *)getConfig {
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
          ...
          return config;
      }

2.5. 딥링크 처리

유저가 앱이 설치된 디바이스에서 딥링크를 클릭하면, 앱이 오픈되어 특정 제품을 표시하거나 특정 경험을 보여주는 것을 의미합니다.

Singular 트래킹 링크는 딥링크 기능과 디퍼드 딥링크를 포함할 수 있습니다. (see our 딥링크 FAQ와 Singular 링크 FAQ를 통해 더 자세한 내용을 확인하세요).

이전 단계에서 구현된 Singular SDK 구성은 콜 백 기능을 의미합니다. ("processDeeplink"). "processDeeplink" 기능은 Singular SDK를 통해 딥링크와 디퍼드 딥링크를 활성화하는데 필요합니다.

딥링크 구현의 필요 조건

다음 단계들을 반드시 수행하세요.

• Singular 링크 필요 조건을 수행.
• Xcode에서, Signing & Capabilities > Associated Domains에 Singular Custom Subdomain 을 추가.
• 앱 스킴을 Info > URL Types의 URL에 추가.
• Singular 웹 앱의 Apps 페이지에서 Team ID와 Scheme을 Apple Developer에 추가.   

핸들러에 대한 콜 백 메서드를 생성

하단의 예시는 processDeeplink라는 콜 백 메서드를 생성합니다. (이 메서드는 상단의 구성 샘플에서도 언급되어  있습니다.

블록 사인은 void(^)(SingularLinkParams*) 입니다. SingularLinkParams는 딥링크 데스티네이션, 패스 스루 파라미터와 링크가 디퍼드 되는지의 여부를 포함합니다.  

func processDeeplink(params: SingularLinkParams!) {
          // Get Deeplink data from Singular Link
          let deeplink = params.getDeepLink()
          let passthrough = params.getPassthrough()
          let isDeferredDeeplink = params.isDeferred() ? "Yes" : "No"
          // Add deep link handling code here
      }

- (void)processDeeplink:(SingularLinkParams*)params{
          // Get Deeplink data from Singular Link
          NSString* deeplink = [params getDeepLink];
          NSString* passthrough = [params getPassthrough];
          NSString* isDeferredDeeplink = [params isDeferred] ?@"Yes": @"No"
          // Add deep link handling code here
      }

다른 링크 옵션

func getConfig() -> SingularConfig? {
          // Singular Config Options
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.supportedDomains = ["subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"]
          ...
          return config
      }

- (SingularConfig *)getConfig {
          // Singular Config Options
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.supportedDomains = @[@"subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"];
          ...
          return config;
      }

func getConfig() -> SingularConfig? { 
          // Singular Config Options 
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else { 
              return nil 
          } 
          ... 
          config.espDomains = ["links.mywebsite.com"] 
          ... 
          return config 
      } 

- (SingularConfig *)getConfig { 
          // Singular Config Options 
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET]; 
          ... 
          config.espDomains = @[@"links.mywebsite.com"]; 
          ... 
          return config; 
      } 

2.6. Singular 초기화

Singular SDK는 앱이 오픈될 때마다 초기화 되어야 합니다. 이는 모든 Singular 어트리뷰션 기능의 전제 조건이며, 이를 통해 신규 유저 세션을 Singular로 전송합니다. (세션들은 유저 리텐션을 계산하는데 사용됩니다). SDK는 2.2. 구성 오브젝트 생성에서 생성한 config 오브젝트를 사용하여 초기화됩니다.

어디에 초기화 코드를 추가할까요?

앱의 모든 엔트리 포인트에서 Singular SDK를 초기화해야 합니다. 

• iOS 13 이상 버전, 다음 SceneDelegate 기능에서 Singular SDK를 초기화하세요: willConnectTo session, continue userActivity, openURLContexts URLContexts.

• SceneDelegate를 지원하지 않는 구 iOS 버전에서는, 다음 AppDelegate 기능에서 SDK를 초기화하세요: didFinishLaunchingWithOptions, continueUserActivity, openURL.

초기화 코드 예시

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS
              
      // willConnectTo session
                  
      func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
          options connectionOptions: UIScene.ConnectionOptions) {
          let userActivity = connectionOptions.userActivities.first
          // Print IDFV to Console for use in Singular SDK Console
          print(Date(), "-- Scene Delegate IDFV:", 
              UIDevice().identifierForVendor!.uuidString as Any)
          //Initialize the Singular SDK here:
          if let config = self.getConfig() {
              config.userActivity = userActivity
              Singular.start(config)
          }
      }
                  
      // continue userActivity
                  
      func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
          // Starts a new Singular session on continueUserActivity
          if let config = self.getConfig() {
                  config.userActivity = userActivity
                  Singular.start(config)
          }
      }
               
      //openURLContexts URLContexts
                  
      func scene(_ scene: UIScene, openURLContexts URLContexts: 
          Set<UIOpenURLContext>) {
          // Starts a new Singular session on cold start from deeplink scheme
          if let config = self.getConfig() {
              config.openUrl = openurlString
              Singular.start(config)
          }
          // Add custom code here to Redirect to non-Singular deep links
          // ...
      }

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS// willConnectToSession

      - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
          NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] firstObject];
          // Print identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console
          NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
          // Start a new Singular session from a backgrounded app
          SingularConfig *config = [self getConfig];
          config.userActivity = userActivity;
          [Singular start:config];
      }
      
      // continueUserActivity

      - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{
          // Starts a new Singular session from a backgrounded App
          SingularConfig *config = [self getConfig];
          config.userActivity = userActivity;
          [Singular start:config];
      }
      
      // openURLContexts

      - (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts {
          // Starts a new Singular session on cold start from deeplink scheme
          SingularConfig *config = [self getConfig];
          config.openUrl = url;
          [Singular start:config];
          
          // Add custom code here to Redirect to Non-Singular deep links
          // ....
      }

// INITIALIZE THE SDK IN THE FOLLOWING APPDELEGATE FUNCTIONS// didFinishLaunchingWithOptions

      - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
          // Starts  new session when  user opens the app if session timeout passed/opened using Singular Link
          SingularConfig *config = [self getConfig];
          config.launchOptions = launchOptions;
          [Singular start:config];
          return YES;
      }
      
      // continueUserActivity

      - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
       restorationHandler:(void (^)(NSArray<id> *restorableObjects))restorationHandler {
          // Starts a new session when the user opens the app using a Singular Link while it was in the background
          SingularConfig *config = [self getConfig];
          config.userActivity = userActivity;
          [Singular start:config];
          return YES;
      }
      
      // openURL

      - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url 
          options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{
          // Starts new session when user opens the app using a non-Singular link, like a traditional app scheme.
          SingularConfig *config = [self getConfig];
          config.openUrl = url;
          [Singular start:config];
          // Add custom code here to Redirect to non-Singular deep links
          // ,,,
          return YES;
      }

2.7. 유저 ID를 Singular로 전송 (선택 사항)

Singular SDK는 앱의 내부 유저 ID를 Singular로 전송할 수 있습니다.

• PII (Personally Identifiable Information) 외, 어떤 식별자든 전송할 수 있습니다. 예를 들어, 유저의 이메일 주소와 같은 정보는 전송하지 마세요. 
• 이 식별자는 모든 플랫폼(웹/모바일)에 걸쳐 포획되는 내부 유저 ID와 동일해야 합니다.  
• 만약 Singular의 크로스 디바이스 측정을 사용하고 있다면, 유저 ID는 모든 플랫폼에서 반드시 수집되어야 합니다. 
• 구성된 경우, Singular는 유저 레벨 추출과 내부 BI 포스트 백의 유저 ID를 노출합니다. 유저 ID는 첫 파티 데이터이며 다른 파티들과 공유되지 않습니다.  
• 유저 ID는 unsetCustomUserId를 사용하여 설정을 해제하거나 또는 앱이 삭제되기 전까지 잔존합니다. 앱을 종료하거나/다시 시작하는 동작은 유저 ID의 설정을 해제하지 않습니다.   

유저 ID를 설정하려면, setCustomUserId 메서드를 사용하세요. 설정을 해제하려면 (예를 들어, 유저가 계정을 로그아웃하는 경우), unsetCustomUserId를 호출하세요. 만약 다수의 유저가 단일 디바이스를 사용하는 경우, 로그아웃 플로우와 설정를 구현하고 각 로그인과 로그 아웃시 유저 ID 설정을 해제하는 것을 권장합니다. 

아시다시피, 앱이 오픈될 때마다 유저 ID는 setCustomUserIdbefore를 호출하여 Singular SDK를 초기화합니다. 이 과정을 통해, Singular는 매 첫 세션마다 유저 ID를 획득할 수 있습니다. 하지만, 일반적으로, 유저 ID는 유저가 회원 가입이나 로그인 동작을 하기 전까지는 제공되지 않습니다. 이 경우, 회원 가입 동작 이후 setCustomUserId를 호출하세요.

// Set the User ID in Singular.
    setCustomUserId("custom_user_id")
      
    // Unset the User ID in Singular
    unsetCustomUserId() 

// Set the User ID
    [Singular setCustomUserId:@"a_user_id"];
      
    // UnSet the User ID
    [Singular unsetCustomUserId];

2.8. 글로벌 속성 구현 (선택 사항)

Singular SDK에서는 앱의 모든 세션, 이벤트, Singular 서버에 전송되는 커스텀 속성들을 정의할 수 있습니다. 이 속성들은 앱 모드/현황, 유저로부터 원하는 정보나 그 이외의 속성들을 의미할 수도 있습니다. 

최대 5개의 글로벌 속성을 정의할 수 있습니다. 이 속성들은 앱 실행(과 가장 최근 전달한 값)으로부터 설정 해제 전까지나 앱을 삭제하기 전까지 유효합니다.  

활용 사례

글로벌 속성의 활용 사례는 다음과 같습니다. 

• 써드파티 측에서 인식할 수 있는 고유 식별자를 통해 Singular가 측정한 이벤트를 전달받는 경우.
  
• 게임 앱의 경우, "레벨" 속성을 정의하여 "0"부터 시작하도록 설정할 수 있습니다. 이 경우, 앱에서 전송되는 모든 세션과 이벤트는 "레벨":"0"부터 전송됩니다. 유저가 레벨 업하면, 해당 특성을 "1"로 초기화하는 식으로 설정하는 경우.

Config 오브젝트를 통해 글로벌 속성 설정

SDK 초기화 전에 글로벌 속성을 설정하려면, Config 오브젝트의 setGlobalProperty 메서드를 사용하세요.

글로벌 특성들과 값들은 앱이 수행되는 동안에도 남는 값이기 때문에, 설정하려는 특성이 다른 값으로 설정될 수 있습니다. 그러므로 overrideExisting 파라미터를 사용하여 기존에 존재하는 특성을 새 값으로 오버라이드하게 할 것인지 SDK에 알리세요. 

 func getConfig() -> SingularConfig? {         
          // (Optional) Get 3rd-party identifiers to set in Global Properties:     
          // If 3rd-party SDKs are providing any identifiers to Singular, the
          // respective SDK must be initialized before Singular.     
          let thirdPartyKey = "anonymousID"     
          let thirdPartyID = "2ed20738-059d-42b5-ab80-5aa0c530e3e1"     
      
          // Singular Config Options     
          guard let config = SingularConfig(apiKey: Constants.APIKEY, 
              andSecret: Constants.SECRET)
          else {         
              return nil
          }     
          ...     
          // Using Singular Global Properties feature to capture third party identifiers
          config.setGlobalProperty(thirdPartyKey, withValue:
              thirdPartyID, overrideExisting: true)     
          ...
          return config 
      }

- (SingularConfig *)getConfig {     
          // (Optional) Get 3rd-party identifiers to set in Global Properties:     
          // If 3rd-party SDKs are providing any identifiers to Singular, the
          // respective SDK must be initialized before Singular.     
          NSString* thirdPartyKey = @"anonymousID";
          NSString* thirdPartyID = @"2ed20738-059d-42b5-ab80-5aa0c530e3e1";     
          
          // Singular Config Options     
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
              andSecret:SECRET];
          ...
          
          // Using Singular Global Properties feature to capture 3rd-party identifiers     
          [config setGlobalProperty:thirdPartyKey withValue:thirdPartyID
              overrideExisting:YES];
          ...
          return config;
      }

초기화 이후 글로벌 특성 설정 

다음 메서드를 설정, 설정 해제하거나, 앱 실행하는 도중 언제든 글로벌 특성을 철회하는 데 사용하세요. 

var result = Singular.setGlobalProperty("propertyName",
          andValue: "propertyValue", overrideExisting: true)

BOOL result = [Singular setGlobalProperty:@"propertyName"
          andValue:@"propertyValue" overrideExisting:YES];

var globalProperties = Singular.getGlobalProperties()

NSDictionary* globalProperties = [Singular getGlobalProperties];

Singular.unsetGlobalProperty("propertyName")

[Singular unsetGlobalProperty:@"propertyName"];

Singular.clearGlobalProperties()

[Singular clearGlobalProperties];

2.9. 세션 타임아웃 수정 (선택 사항)

기본적으로, 포 그라운드로 돌아오기 전 앱이 백그라운드에서 60초 이상 실행되면, SDK는 이를 신규 세션으로 기록합니다. 타임아웃 값을 설정하려면, setSessionTimeout 메서드를 사용하여 Config에 추가하세요.

 func getConfig() -> SingularConfig? {       
          // Singular Config Options     
          guard let config = SingularConfig(apiKey: Constants.APIKEY, andSecret:
              Constants.SECRET) else {         
              return nil     
          }     
          ...     
          Singular.setSessionTimeout(120)      
          ...     
          return config
      } 

 - (SingularConfig *)getConfig {
          // Singular Config Options     
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
              andSecret:SECRET];
          ...     
          [Singular setSessionTimeout:120];
          ...     
          return config;
      }

3. 이벤트 추적과 매출 

3.1. 이벤트 추적

Singular는 캠페인의 성과를 분석하는 데 도움이 되는 인 앱 이벤트에 관한 데이터를 수집할 수 있고 KPI를 측정할 수 있습니다. 예를 들어, 유저 로그인, 회원가입, 튜토리얼 완료, 게임 앱에서의 레벨 업에 관한 데이터를 수집할 수 있습니다.  

Singular로 보내는 이벤트 목록(과 수반되는 어트리뷰트들)은 마케팅 KPI에 기반하여 UA/마케팅/비즈니스팀이 작성하세요. 

유저 이벤트를 계획하는 방법에 대한 자세한 내용은, SDK 계획과 전제조건 가이드의 앱이 유저 이벤트를 추적할까요?를 참고하세요.

코드에서 event 또는 eventWithArgs 메서드를 사용하여 Singular에 표준 이벤트를 전송하세요.

Singular.event(EVENT_SNG_LOGIN);

[Singular event:EVENT_SNG_LOGIN];

dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
      dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0"
      dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options"
      Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
      [dic setValue:@"PrivacyController" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
      [dic setValue:@"0" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
      [dic setValue:@"GDPR and CCPA Opt-Out Options" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
      [Singular event:EVENT_SNG_CONTENT_VIEW withArgs:dic];

3.2. 매출 추적

Singular는 앱을 통해 캠페인의 성과와 ROI 분석에 도움이 되는 매출에 관한 데이터를 수집할 수 있습니다. Singular는 이 데이터를 리포트, 로그 추출, 포스트 백에 제공합니다.   

IAP 추적을 통한 매출 보고 (권장)

매출 이벤트를 Singular에 보고하기 위해서는, iapComplete SDK method 메서드를 사용하세요. 이 메서드는 IAP (Apple 인 앱 구매) 매출 이벤트를 다음의 내용과 함께 Singular에 전송합니다.

• Singular에서 리포트를 채우는 데 사용하는 세부 거래 내역. 
• 거래 확인 및 분석에 사용되거나 프러드 시도를 방지하는 데 사용될 수 있는 거래 영수증. 

// *** Get the SKPaymentTransaction* transaction object ***
      let transaction:SKPaymentTransaction = ...
      
      // Send a transaction event to Singular without a custom event name
      Singular.iapComplete(transaction)
      
      // Send a transaction event to Singular with a custom event name
      Singular.iapComplete(transaction, withName:"MyCustomRevenue")

// *** Get the SKPaymentTransaction* transaction object ***
      SKPaymentTransaction* transaction = ...;
      
      // Send a transaction event to Singular without a custom event name
      [Singular iapComplete:transaction];
      
      // Send a transaction event to Singular with a custom event name
      [Singular iapComplete:transaction withName:@"MyCustomRevenue"];

대안 매출 이벤트 보고

Singular가 iapComplete 사용을 권장하는 반면, 고객의 앱이 App Store IAP 추적을 사용하지 않을 경우를 위해 매출 이벤트를 Singular로 보고하는 다른 두 메서드를 대안으로 제공합니다.  

// Revenue with no product details
      Singular.revenue("USD",amount:1.99)
      
      // Revenue with product details
      Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", 
          productName:"Reservation Fee",productCategory:"Fee", productQuantity:1, productPrice:5.00)
      
      // Send a Revenue Event with attributes in a dictionary
      var dic: [AnyHashable : Any] = [:]
      dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
      dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
      dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
      dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
      Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Revenue with no product details
      [Singular revenue:@"USD" amount:1.99];
      
      // Revenue with product details
      [Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
          productName:@"Reservation Fee" productCategory:@"Fee" productQuantity:1 productPrice:5.00];
      
      // Send a Revenue Event with attributes in a dictionary
      NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
      [dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
          forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
      [dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
      [dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
      [dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
      [Singular revenue:@"USD" amount:19.99 withAttributes:dic];

// Revenue with a custom name and no product details
      Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
      
      // Revenue with a custom name and product details
      Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00, productSKU:"SKU1928375",
          productName:"Reservation Fee", productCategory:"Fee", 
          productQuantity:1, productPrice:5.00)
      
      // Send a Custom Revenue Event with attributes in a dictionary
      var dic: [AnyHashable : Any] = [:]
      dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
      dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
      dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
      dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
      Singular.customRevenue("CustomRevenueWithArgsDic", currency: "USD",
          amount: 44.99, withAttributes: dic)

// Revenue with a custom name and no product details
      [Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];
      
      // Revenue with a custom name and product details
      [Singular customRevenue:@"MyCustomRevenue" currency:@"EUR" amount:5.00 productSKU:@"SKU1928375"
          productName:@"Reservation Fee" productCategory:@"Fee"  productQuantity:1 productPrice:5.00];
      
      // Send a Custom Revenue Event with attributes in a dictionary
      NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
      [dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
      [dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
      [dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
      [dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
      [Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:44.99 withAttributes:dic];

3.3. 하이브리드 이벤트 추적 (고급)

Singular는 모든 이벤트와 매출을 앱에 연동된 Singular SDK를 통해 전달하는 것을 권장합니다. 하지만, 필요한 경우, Singular는 다른 소스로부터 아벤트와 매출을 수집할 수 있습니다. 

특정 파티가 전송하는 데이터는 반드시 Singular의 서버-투-서버 이벤트 도큐먼트 필수 사항을 준수해야 하며 이벤트에 올바르게 어트리뷰트할 수 있도록 일치하는 디바이스 식별자를 제공해야 합니다.  

만약 제공자 또는 서버가 이벤트 또는 매출을 올바르지 않은 식별자와 데이터 포인트로 전송하는 경우, Singular에서 데이터 불일치가 초래될 수 있습니다.  

하이브리드 이벤트 추적 가이드

https://s2s.singular.net/api/v1/evt?a=<SDK KEY>&i=com.myapp&p=iOS&use_ip=true&idfa131B7AF2-52E5-41A1-AA0B-C036037575AC&idfv230F6839-290B-4BF9-8C4E-F165FE5980CF&custom_user_id=user123456789&n=s2sPurchase&e=%7B%27sampleKey1%27%3A%27sampleValue1%27%2C%27sampleKey2%27%3A%27sampleValue2%27%2C%27sampleKey3%27%3A%27sampleValue3%27%7D&is_revenue=true&amt=2.99&cur=USD

4. 고급 옵션

짧은 레퍼러 링크 생성

createReferrerShortLink 메서드를 사용하여 유저가 친구들과 앱을 공유할 수 있는 짧은 공유 링크를 생성하세요. 링크가 생성될 때 앱 코드에서 사용자 세부 정보를 참조하도록 정의하세요. 이 작업은 리포팅시 레퍼러 어트리뷰션을 추적할 수 있게 합니다. 

짧은 링크를 생성하려면 다음 단계를 따르세요.

1. Singular 커스텀 소스 링크와 앱을 다운로드하도록 유도하는 정의한 딥링크를 빌드하세요 (Singular 링크 FAQ 참고). 이 링크는 하단 코드 내 기본 링크로써 참조됩니다. 
2. 모든 캠페인은 동적으로 링크에 추가하는 파라미터들을 오버라이드 합니다. (트래킹 링크 파라미터를 통해 옵션 목록을 확인하세요).
3. 신규 앱 인스톨의 링크를 공유한 유저의 이름과 ID를 추적합니다. 

하단의 예시와 같이 짧은 링크를 생성하기 위해 createReferrerShortLink 메서드를 사용하세요. 

// 1. Define variables for the referrer short link
            
    // Define your Singular tracking link to be used as a base link:
    let referrerBaseLink = "https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
    
    // Add your Referrer ID and Name
    let referrerID = referrerIDField.text;
    let referrerName = referrerNameField.text;
    
    // Customize any Passthrough Parameters
    let passthroughParams = [
        "channel": "sms"
    ]
        
    // 2. Call  ReferrerShortLink to get your shortlink to share on social media
    Singular.createReferrerShortLink(referrerBaseLink, referrerName: referrerName, 
        referrerId: referrerID, passthroughParams: passthroughParams, completionHandler: {(shortLink, error) in
        if error != nil {
            // Logic to retry/abort/modify the params passed to the function, based on the cause of the error
        }
        if (shortLink != nil || shortLink != "") {
            // Add your share logic here:
            ....
        }
    })

 
    // 1. Define variables for the referrer short link
    
    // Define your Singular tracking link to be used as a base link.
    // Include any override parameters in the string as query string parameters.
    NSString* referrerBaseLink = @"https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
    
    // Add your Referrer ID and Name
    NSString* referrerID = self.referrerIDField.text;
    NSString* referrerName = self.referrerNameField.text;
    
    // Customize any Passthrough Parameters
    NSDictionary* passthroughParams = @{@"channel": @"sms"};
    
    // 2. Call the ReferrerShortLink Method to get the shortlink to share on social media
    [Singular createReferrerShortLink:referrerBaseLink
        referrerName:referrerName
        referrerId:referrerID
        passthroughParams:passthroughParams
        completionHandler:^(NSString *shortLink, NSError *error) {
            if (error) {
                // Logic to retry/abort/modify the params passed to the function, based on the cause of the error
            }
            if (shortLink) {
                // Add your share logic here:
                ...
            }
        }
    ];

광고 매출 어트리뷰션 지원을 추가

Signular SDK에서 광고 매출 어트리뷰션 지원을 추가하려면 다음을 완료하세요. 

1. Singular 고객 성공 매니저에게 문의하여 계정의 광고 매출 어트리뷰션 활성화하세요. 
2. 최신 Singular SDK 버전을 사용하세요. 
3. 광고 매출 데이터에 대한 매개 플랫폼에 기반하여, Singular SDK 연동에 올바른 코드 스니핏을 추가하세요. 

// 참고: 본 기능은 베타 기능으로 Admob에 문의하여 활성화하세요.

GADRewardedAd* rewardedAd;

[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
  if (error) {
    NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
    return;
  }

   self.rewardedAd = ad;

   self.rewardedAd.paidEventHandler = ^void(GADAdValue *_Nonnull adValue){
   GADAdValue* impressionData = adValue;

   SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"Admob" withCurrency:[impressionData currencyCode] withRevenue:[impressionData value]];

   [data setAdUnitId:[rewardedAd adUnitID]];
   [data setNetworkName:rewardedAd.responseInfo.adNetworkClassName];

   }
}];

// The object received from AppLovin MAX's event, didReceivedMessage
      ALCMessage* message;
      
      SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"AppLovin" withCurrency:@"USD" withRevenue:message.data[@"revenue"] doubleValue];
      
      [data setAdUnitId:message.data[@"max_ad_unit_id"]];
      [data setNetworkName:message.data[@"network_name"]];
      [data setAdType:message.data[@"ad_format"]];
      
      [Singular adRevenue:data];

// The object received from IronSource's event, impressionDataDidSucceed
      ISImpressionData* impressionData;
      
      SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"IronSource" withCurrency:@"USD" withRevenue:impressionData.revenue];
      
      [data setAdUnitId:[impressionData instanceId]];
      [data setAdUnitName:[impressionData instanceName]];
      [data setImpressionId:[impressionData auctionId]];
      [data setNetworkName:[impressionData adNetwork]];
      [data setAdPlacementName:[impressionData placement]];
      [data setAdType:[impressionData adUnit]];
      
      [Singular adRevenue:data];

// Ensure that the ARM SDK Postbacks Flag (click here) in IronSource is turned on

// Initialize the SingularAdData object with the relevant data
      SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"YOUR_AD_PLATFORM" withCurrency:@"CURRENCY_CODE" withRevenue:[NSNumber numberWithDouble:9.90]];
      
      // The more ad data you add, the greater the granularity
      [data setAdGroupId:@"AD_GROUP_ID"];
      [data setNetworkName:@"AD_NETWORK_NAME"];
      
      // Report the data to Singular
      [Singular adRevenue:data];

언인스톨 추적

언인스톨 추적 설정 방법:

1. 다음 가이드에 따라 Singular에서 앱을 활성화하세요: iOS 인스톨 추적 설정.
2. 앱에서, Apple 푸시 알림 서비스(APNS)로 부터 디바이스 토큰을 Singular에 전송하세요. Singular에게 디바이스 토큰을 전달하려면 registerDeviceTokenForUninstall 또는 registerDeviceToken 메서드 사용하세요. 이 작업을 Singular SDK가 초기화되기 전에 하세요. 해당 작업은 AppDelegate의 didRegisterForRemoteNotificationsWithDeviceToken 메서드로부터 호출되어야 합니다 

func application(_ application: UIApplication, 
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Send the deviceToken to Singular for uninstall tracking     
        Singular.registerDeviceToken(forUninstall: deviceToken) 
    } 

 - (void)application:(UIApplication*)application
        didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {     
        // Send the deviceToken to Singular for uninstall tracking      
        [Singular registerDeviceTokenForUninstall:deviceToken];
    }

Singular SDK 자바스크립트 인터페이스

Singular는 앱에서 Singular를 호출하는 데 사용하는 자바스크립트 인터페이스를 제공합니다.  

예를 들어, 자바스크립트 인터페이스를 설정하면, 다음과 같은 자바스크립트 코드로부터 이벤트를 Singular에 전송할 수 있습니다. 

Singular.event('event');
Singular.event('test', JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

자바스크립트에서 지원되는 메서드

인터페이스는 다음 SDK 메서드를 지원합니다:

• setCustomUserID
• unsetCustomUserID
• event
• revenue

자바스크립트 인터페이스 활성화

WKWebView를 사용할 때 자바스크립트 인터페이스를 활성화하려면, 어떤 코드를 WKNavigationDelegate 프로토콜(웹 뷰가 네비게이션 리퀘스트를 처리할 때 발생하는 커스텀 동작을 구현하는데 도움 되는 프로토콜)의 webView 메서드에 추가해야 합니다.  

extension ViewController: WKNavigationDelegate { 
    func webView(_: WKWebView, decidePolicyFor: WKNavigationAction, 
      decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { 
      // Singular handler 
      let js = "typeof(Singular)" 
       webView.evaluateJavaScript(js) { (result, error) -> Void in 
         if let resultString = result as? String { 
           if resultString.isEqual("undefined") { 
             do { 
               let contents = try String(contentsOfFile: 
               Bundle.main.path(forResource: "Singular", ofType: "js")!) 
               self.webView.evaluateJavaScript(contents, completionHandler: nil) 
             } catch { } 
           }
           else { 
             print(decidePolicyFor.request) 
             Singular.processJSRequestWK(self.webView, withURL:decidePolicyFor.request) 
           } 
         }  
       } 
       // rest of your code goes here   
    }
  }

5. 데이터 프라이버시 정책 준수 

Singular의 개인 정보 보호 기능을 통해 GDPR과 CCPA (California Consumer Privacy Act)와 같은 고객 프라이버시 법을 준수하는 파트너와 협업할 수 있습니다. 해당 파트너들은 개인 정보 제공에 동의한 유저들이 있는 경우 이에 대한 알림 받기를 희망합니다. 

데이터 공유 제한

유저에게 개인 정보를 공유할지 동의 여부를 묻는 방법을 구현하려면, limitDataSharing 메서드를 사용하여 Singular에게 유저의 선택에 대해 보고하세요.

• limitDataSharing:NO를 사용하면 유저가 정보 제공에 동의(옵트 인)했는지를 나타냅니다. 
• 유저가 정보 제공에 동의하지 않았다면 limitDataSharing:YES 를 사용하세요.

Singular는 관련 법안을 준수하기 위해 이를 필요로 하는 파트너들에게 이 정보를 전달합니다. 

// User has opted into sharing
      data Singular.limitDataSharing(false) 

// User has opted into sharing data
[Singular limitDataSharing:NO];

GDPR 준수하는 다른 추가 메서드들

Singular SDK는 SDPR 정책을 준수할 수 있도록 몇 가지 메서드를 제공하고, 유저의 추적 동의에 대한 여부를 Singular에 보고합니다. 

Singular.trackingOptIn() 

[Singular trackingOptIn]; 

Singular.stopAllTracking() 

[Singular stopAllTracking]; 

Singular.resumeAllTracking() 

[Singular resumeAllTracking]; 

Singular.isAllTrackingStopped()
      // returns true/false 

[Singular isAllTrackingStopped];
      // returns true/false 

자주묻는 질문과 이슈 

이 구간에 대한 설명은 테스트 앱을 빌드하는데 이슈나 에러가 있는 경우에 참조하세요.