서버 투 서버(S2S) 연동 가이드

Note: 서버 투 서버 연동은 SDK연동이 불가한 경우에 한해 활용하시기 바랍니다. 기술 지원이 필요한 경우 담당 고객성공매니저 또는 싱귤러 서포트팀(support@singular.net)에 문의해 주세요.

 

Singular는 SDK의 대안으로 활용가능한 REST API를 제공합니다. 고객사는 해당 API를 이용하여 고객사 - 싱귤러 서버간 통합 연동이 가능하도록 구현할 수 있습니다.

이 가이드에서는 Singular와 기본 S2S 연동을 구축하고 다양한 옵션 기능을 구현하는 방법에 관해 설명합니다.

S2S API 엔드 포인트, 해당 파라미터 및 샘플 호출에 관한 목록은 S2S 엔드포인트 레퍼런스를 참고하세요.

기본 연동

Singular와의 가장 기본적인 연동은 새로운 세션이 발생 시 (앱이 오픈될 때) Singular에게 알리는 것입니다.  

Singular에 새로운 유저 세션에 관하여 알리려면, 세션 알림 엔드포인트(Session Notification Endpoint)를 호출하세요.

세션 알림은 Singular에게 다음과 같은 동작들을 허용합니다.

  • 만약 특정 디바이스의 앱에 대한 최초 세션이면, Singular는 새 인스톨을 인지하여 인스톨 어트리뷰션 과정을 발동 시킵니다. 
  • 만약 세션이 리인게이지먼트 세션으로서 부합하다면, Singular는 리인게이지먼트 어트리뷰션 과정을 발동 시킵니다. (더 많은 정보를 원하시면, 리인게이지먼트 FAQ를 참고하세요)
  • 이 외의 경우, Singular는 유저 활동과 리 텐션을 트래킹하는 세션으로 표시합니다. 

세션 알림 엔드포인트(Session notification Endpoint)에는 몇 가지 필수 파라미터가 있습니다. 세션으로 리포트하기 위해 필요한 모든 데이터를 얻기 위해서는, 레퍼런스: iOS 인스톨 영수증 가져오기세션 데이터를 참고하세요.

팁: 세션으로 리포트하기 위해 데이터를 수집할 때, 비동기 함수(asynchronous functions)가 다양한 에지 케이스(edge cases)를 반환하고 해결할 때까지 기다리세요. 이는 데이터 누락 또는 부분적 어트리뷰션을 야기할 수 있는 일반적인 이슈입니다.  

옵션: 유저 ID 전송

Singular에 새 세션에 대해 알릴 때, 유저 ID를 추가할 수 있습니다. 이 유저 ID가 될 수 있는 것에는 유저 이름, 이메일 주소, 임의로 생성된 문자열, 또는 귀사가 앱의 유저 ID로써 사용하는 식별자가 해당합니다. Singular는 유저 레벨 데이터 추출 및 내부 BI 포스트 백 (만약 있다면)의 유저 ID을 사용할 것입니다. 

유저 ID를 전송하시려면, 세션 알림 엔드포인트(Session Notification Endpoint)를 설정하실 때 "custom_user_id" 파라미터를 추가하세요.

예시

Python HTTP cURL
import requests
import json

API_KEY = 'api_key_from_sdk_page'
LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'

params = {
  'a': API_KEY,
  'p': 'Android',
  'i': 'com.singular.app',
  'ip': '10.1.2.3',
  've': '9.2',
  'ma': 'samsung',
  'mo': 'SM-G935F',
  'lc': 'en_US',
  'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
  'andi': 'fc8d449516de0dfb',
  'utime': 1483228800,
  'dnt': 0,
  'install':'true',
  'n': 'MyCoolApp',
  'c': 'wifi',
  'cn': 'Comcast',
  'bd': 'Build/13D15',
  'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
  'app_v':'1.2.3',
  'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
  'ddl_enabled':'false',
  'install_source': 'com.android.vending',
  'install_time': 1510040127,
  'update_time': 1510090877,
  'custom_user_id': 'player_id_1234'
}

result = requests.get(LAUNCH_URL, params=params)
print result.json()

추가적인 어트리뷰션 처리

Google Play 인스톨 리퍼러 (Android) 전송

인스톨 리퍼러는 누가 유저를 Google Play Store에 보냈는지를 포함하는 정보입니다. 인스톨 리퍼러가 Singular에서 조회 가능할 때, 이는 인스톨을 어트리뷰션 하는 가장 정확한 방법을 제공합니다. 저희는 첫 세션 알림 호출 이후 이 값을 가져오시고 바로 Singular에 전달하시기를 권고드립니다.

Google Play는 유저가 스토어에 도달했을 때의 리퍼러 정보를 수집합니다. 만약 후에 유저가 다이렉트 된 앱을 설치한다면, Google Play는 해당 정보를 앱에서 조회할 수 있게 합니다. 더 많은 정보를 원하시면, Google 개발자 도큐먼트를 참고하세요.

Singular와 인스톨 리퍼러를 공유하시려면 다음 단계를 따르세요.

  1. 앱에 처음 오픈되었을 때, 플레이 인스톨 리퍼러 API(Play Install Referrer API)를 사용해서 인스톨 리퍼러를 가져오세요.
  2. 세션 알림 엔드포인트(Session notification Endpoint)를 사용해서, 일반적인 방법으로 Singular에게 세션을 리포트하세요.
  3. 그 후, 이벤트 알림 엔드포인트(Event Notification Endpoint)를 실행하시고 예약된 이벤트 이름(reserved event name)인 _InstallReferrer로 리포트하세요. (커스텀 이벤트 어트리뷰트를 추가하는데 사용되었던) e 파라미터에서 다음 어트리뷰트들을 추가하세요. 
    • referrer: 플레이 인스톨 리퍼러 API(Play Install Referrer API)에서 가져온 리퍼러 값입니다. 이는 JSON 오브젝트이니 문자열로 인코딩하세요. 
    • referrer_source: 리퍼러 소스입니다. 이를 위한 "서비스"를 명시하세요.
    • clickTimestampSeconds: 플레이 인스톨 리퍼러 API(Play Install Referrer API) (예, "1550420123")에서 받은 클릭 타임스템프입니다.  
    • installBeginTimestampSeconds: 인스톨이 시작한 시간으로 플레이 인스톨 리퍼러 API(Play Install Referrer API)로부터 받습니다. 
    • current_device_time: 밀리세컨드 기준으로, 현재 디바이스의 시간입니다. (예, "1550420454906").

다음은 인스톨 리퍼러 이벤트(Install Referrer Event)를 리포팅하기 위한 샘플 코드입니다.  

Python HTTP
import requests
    import json

    API_KEY = 'api_key_from_sdk_page'
    EVENT_URL = 'https://s2s.singular.net/api/v1/evt'

    referrer_values = {
      "referrer": "tracking_id%3D123456789&utm_source%3Dmdotm%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign",
      "referrer_source" : "service",
      "clickTimestampSeconds" : 1550420123,
      "installBeginTimestampSeconds" : 1550420123,
      "current_device_time" : 1550420454906
    }

    params = {
        'n': '__InstallReferrer',
        'e': json.dumps(referrer_values),
        'a': API_KEY,
        'p': 'Android',
        'i': 'com.singular.app',
        'ip': '10.1.2.3',
        've': '9.2',
        'ma': 'samsung',
        'mo': 'SM-G935F',
        'lc': 'en_US',
        'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
        'andi': 'fc8d449516de0dfb',
        'utime': 1483228800,
        'bd': 'Build/13D15'
    }

    result = requests.get(EVENT_URL, params=params)
    print result.json()

Apple Search Ads 캠페인의 어트리뷰션 (iOS)

Apple Search Ads는 자가 기여 네트워크(SAN)입니다. iOS 14.3 버전 부로, Apple Search Ads 연동은 다음 두 iOS 프레임워크 모두를 통해 지원합니다.

  • iOS 14.2 또는 그 이하 버전에서는, Apple Search Ads는 iAd 프레임워크를 통해 지원합니다.
  • iOS 14.3 또는 그 이상 버전에서는, Apple Search Ads는 AdServices 프레임워크를 통해 지원합니다.

저희는 iAd 프레임워크의 지원이 중단되기 전까지 iAd 과 AdServices 프레임워크를 모두 구현하시기를 권고드립니다. 왜냐하면 AdServices는 아직 Apple의 새로운 서비스이고, Singular는 두 서비스를 사용할 때 iAd 시그널보다 AdServices를 우선으로 하여 어트리뷰션과 리포팅을 진행할 것이기 때문입니다. 

이에 관한 더 많은 정보를 원하시면, Apple Search Ads 연동 도큐먼트를 참고하세요.

iAd(iOS 14.2 또는 그 이하 버전)를 통한 Apple Search Ads 구현

1. 어트리뷰션 데이터 가져오기

어트리뷰션 데이터를 가져오시려면, Apple Search Ads iAd API를 호출하세요. requestAttributionDetails(_:):를 사용하시고, 어트리뷰션 데이터를 포함한 JSON 오브젝트를 반환하세요. 

예시

Objective-C
#import <iAd/iAd.h>

  Class ADClientClass = NSClassFromString(@"ADClient");

  if (ADClientClass) {
      id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
      
      if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
          [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
              if (attributionDetails && attributionDetails.count > 0) {
                  // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
              }
          }];
      }
  }
주의: 가끔 검색 광고를 클릭하는 유저들은 앱을 다운로드하여 즉시 앱을 엽니다. 만약 통신에 지연이 생긴다면, Singular와 같은 MMP는 앱이 열리기 전 광고를 클릭한 시간과 검색 광고 어트리뷰션 API(Search Ads Attribution API)의 호출을 프로세스 하여 가져오지 못할 수 있습니다. 이를 방지하기 위해서, Apple은 다음과 같이 권고합니다. 
  1. 어트리뷰션 데이터를 가져오기 전 몇 초간의 지연을 설정합니다. 
  2. 만약 응답이 거짓 또는 에러 코드 (0, 2, 3)을 보이는 경우 재시도 로직(retry logic)을 구현하세요. 2초 후 Apple 어트리뷰션 API에 다시 호출하세요. 

2. Singular에 어트리뷰션 데이터를 전송하세요.

SIngular에 어트리뷰션 데이터를 공유하려면, 이벤트 알림 엔드포인트(Event Notification Endpoint)를 사용하시고 예약된 이벤트 명 __iAd_Attribution__를 사용하여 이벤트를 리포팅하세요. 이전 단계에서 e 파라미터의 값으로 가져온 JSON 오브젝트를 하기의 예시와 같이 전달하세요.  

Python HTTP
import requests
import json

API_KEY = 'api_key_from_sdk_page'
EVENT_URL = 'https://s2s.singular.net/api/v1/evt'

# !!! REPLACE WITH COLLECTED VALUE FROM APP !!!
apple_attribution_data = {
  u'Version3.1': {
      u'iad-adgroup-id': u'1234567',
      u'iad-adgroup-name': u'Ad Group Name',
      u'iad-attribution': u'true',
      u'iad-campaign-id': u'1234567',
      u'iad-campaign-name': u'Search Campaign',
      u'iad-click-date': u'2016-05-21T12:19:31Z',
      u'iad-conversion-date': u'2016-05-21T12:19:41Z',
      u'iad-keyword': u'ballon',
      u'iad-lineitem-id': u'1234567',
      u'iad-lineitem-name': u'Line Item Name',
      u'iad-org-name': u'Cool Company',
      u'iad-purchase-date': u'2016-05-21T12:19:41Z'
  }
}

params = {
  'n': '__iAd_Attribution__',
  'e': json.dumps(apple_attribution_data),
  'a': API_KEY,
  'p': 'iOS',
  'i': 'com.singular.app',
  'ip': '10.1.2.3',
  've': '9.2',
  'mo': 'iPhone9%2C4',
  'lc': 'en_US',
  'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
  'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
  'utime': 1483228800
}

result = requests.get(EVENT_URL, params=params)
print result.json()

주의 사항:

  • iOS 13 또는 그 이상 버전에서, 인스톨 또는 재 인스톨 이후의 첫번째 세션 후 __iAd_Attribution__ 이벤트를 바로 전송하셔야 합니다. 그렇지 않으면, Apple Search Ads 데이터가 어트리뷰션으로 고려되지 않을 것입니다. 
  • iOS 14 또는 그 이상 버전에서는, Apple Search Ads 어트리뷰션 응답은 여기에 명시된 조건하에 조회가 가능하며 만약 AppTrackingTransparency 상태가 ATTrackingManager.AuthorizationStatus.denied인 경우 조회할 수 없습니다.

AdServices (iOS 14.3 이상)을 통한 Apple Search Ads 구현

1. 어르티뷰션 토큰 가져오기

앱이 인스톨 또는 재 인스톨 후 처음 초기화되자마자 attributionToken()을 사용하여 어트리뷰션 토큰을 가져옵니다.

예시

Objective-C
#import <AdServices/AdServices.h> 

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
if (!error && attributionToken) {
// Handle attributionToken
}
}

주의 사항

  • 어트리뷰션 토큰은 디바이스에서 생성됩니다.
  • 생성 후, 해당 토큰은 디바이스에서 5분 동안 캐시(cached) 됩니다. 5분 후, 만약 attributionToken()이 호출된다면 새 토큰이 생성됩니다.
  • 생성된 토큰은 24시간 동안 유효합니다.

2. Singular에 어트리뷰션 토큰 전송

URL에서 토큰을 인코딩하고 세션 알림 엔드포인트(Session notification Endpoint)를 통하여 Singular로 해당 토큰을 전송한 후,  &attribution_token= 파라미터에 첨부합니다. 이 토큰은 Singular가 Apple Search Ads의 다운로드 또는 재다운로드를 트래킹할 수 있도록 매번 인스톨 또는 재 인스톨 후 첫 번째 세션에서 전송되어야 합니다.    

이벤트 트래킹

Singular는 마케팅 캠페인의 퍼포먼스 분석을 위해 인앱 이벤트들의 데이터를 수집할 수 있습니다. 이 이벤트들은 로그인과 회원가입부터 게임 앱의 레벨 업에 따른 모든 유저 상호작용을 포함할 수 있습니다. 

Singular와 SDK/S2S 연동을 구현하기 전, 트래킹하고 싶은 이벤트 목록을 준비해야 합니다. (인 앱 이벤트 정의를 참고하세요)

앱 내 이벤트가 일어났을 때 Singular에게 알리려면, 이벤트 알림 엔드포인트(Event Notification Endpoint)를 호출하세요. 이벤트 이름은 Singular 리포트, 추출, 포스트백에 이벤트가 어떻게 나타날지를 포함합니다.

주의 사항

  • 모든 써드 파티 파트너(Third-party partners)와 사용하고자 하는 분석 솔루션과의 호환을 위해 이벤트 명과 어트리뷰트를 영문으로 전달하세요. 
  • 이벤트 명은 ASCII 32자로 제한됩니다. ASCII가 아닌 경우, UTF-8로 전환 시 32바이트로 제한됩니다.
  • 모든 이벤트 어트리뷰트와 값은 ASCII 500자로 제한됩니다.

매출 트래킹

Singular는 캠페인의 퍼포먼스와 ROI 분석을 위해 앱으로부터 얻어진 매출에 관한 데이터를 수집할 수 있습니다. Singular는 리포트, 로그 추출, 포스트 백에서 해당 데이터를 조회할 수 있도록 할 것입니다. 

매출 이벤트를 트래킹하기 위해서는, 모든 이벤트에 사용된 같은 이벤트 알림 엔드포인트(Event Notification Endpoint)를 사용하시고, 다음 정보를 추가하세요.

  • is_revenue_event=true: 이 표시는 이벤트를 매출 이벤트로써 표시합니다. 만약 이벤트 명이 __iap__ 또는 0보다 큰 값인 경우 이 파라미터를 스킵할 수 있습니다.
  • Purchase receipt: 이것은 Android 또는 iOS의 인앱 구매 (IAP) 과정에서 반환된 오브젝트입니다. 저희는 귀사가 Singular 거래에 관한 완전한 세부사항을 제공하고 Singular 리포트에 데이터를 채우셔서 전달하시기를 권고드립니다.  
  • Purchase signature (Android만 해당): 저희는 Singular가 거래를 입증하고 인앱 프러드에도 맞설 수 있도록 이 데이터를 전송하시기를 권고드립니다.  
  • Revenue amount (예시, "amt=1.99").
  • Currency (ISO 4217 통화 코드를 사용하세요, 예시 "cur=USD").

구매 영수증 가져오기

다음은 매출 이벤트가 일어난 후, Singular에게 구매 영수증을 전달하는 방법입니다. 

  • Android: Google Play는 구매 영수증("In-App Purchase Data")과 구매 서명("In-App Data Signature")을 가져올 수 있는 API와 제공합니다. getBuyIntent() 메서드를 사용하세요.
  • iOS: 아래 예시에서 보이는 Apple의 인앱 구매 API (In-App Purchases API)를 사용하세요. (더 많은 정보를 원하시면, Apple 인앱 구매 API를 참고하세요).
Objective-C Python HTTP cURL
// SKPaymentTransactionObserver
  + (void)paymentQueue:(id)queue updatedTransactions:(NSArray *)skTransactions {
     NSString *transactionReceipt = nil;

     if ([skTransaction respondsToSelector:@selector(transactionReceipt)]) {
        NSData *transactionReceiptRaw = [skTransaction performSelector:@selector(transactionReceipt)];
        if (transactionReceiptRaw) {
           transactionReceipt = [ApUtils base64Encode:transactionReceiptRaw];
        }
     }
  }

딥링크 지원

딥링크란 앱 내 특정 내용으로 인도하는 링크입니다. 유저가 앱이 인스톨된 디바이스의 딥링크를 클릭하면, 앱은 특정 상품이나 경험을 보여줍니다. 

Singular 트래킹 링크는 딥링크와 디퍼드 딥링크(deferred deep linking)를 포함할 수 있습니다. (더 많은 정보를 원하시면, 딥링크 FAQ싱귤러 링크 FAQ를 참고하세요)

딥링크 필요조건

iOS

Android

딥링크 지원

딥링크를 사용하여 앱을 오픈할 때마다, openuri 파라미터를 사용하여 Singular에 세션을 보고할 때 URL을 추가하세요. 이 단계는 Singular 링크를 사용하는데 필수적인 부분입니다. 

디퍼드 된 딥링크 활성화

인스톨 후 처음 앱이 오픈 되었을 때, Singular에 세션을 리포트할 때 사용하는 다음 파라미터들을 추가하여 디퍼드된 딥링크 플로우를 이용하세요.  

  • install=true
  • ddl_enabled=true

Singular는 디퍼드 된 딥링크를 포함하는 트래킹 링크를 통해 앱이 인스톨 되었을 경우를 주시합니다. 이 경우, 해당 호출은 다음 값과 같이 반환합니다. 

  • deferred_deeplink - 딥링크 주소입니다. 이는 유저에게 제품이나 경험(experience)에 관한 권한을 보여줄 때 파스(parse)에 필요합니다. 
  • deferred_passthrough - 딥링크에 추가된 모든 패스 스루 파라미터입니다. 

샘플 세션 알림 호출(Session Notification Call)과 디퍼드 된 딥링크 지원

Python
import requests
    import json

    API_KEY = 'api_key_from_sdk_page'
    LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'

    params = {
        'a': API_KEY,
        'p': 'iOS',
        'i': '162738612',
        'ip': '10.1.2.3',
        've': '9.2',
        'mo': 'iPhone9%2C4',
        'lc': 'en_US',
        'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
        'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
        'utime': 1483228800,
        'dnt': 0,
        'n': 'MyCoolApp',
        'c': 'wifi',
        'cn': 'Comcast',
        'bd': 'Build/13D15',
        'openuri':'https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue',
        'install':'true',
        'ddl_enabled':'true'
    }

    result = requests.get(LAUNCH_URL, params=params)
    print result.json()

샘플 응답

{
  "deferred_deeplink":"myapp://deferred-deeplink",
  "status":"ok",
  "deferred_passthrough":"passthroughvalue"
}

다이나믹 패스 스루 파라미터(Dynamic Passthrough Parameters) 지원

Singular 트래킹 링크는 다이나믹 패스 스루 파라미터를 포함할 수 있습니다. (더 보기) 만약 귀사가 링크를 위한 다이나믹 패스스루 파라미터를 위한 설정을 하셨다면, 딥링크 URL은 URL 인코딩된 JSON 값 또는 유저에게 적합한 내용이나 경험을 보여주는 구조화되지 않은 문자열 뒤에 수반되는 _p 파라미터를 포함합니다.  

고급 옵션

Singular S2S 연동은 다음 고급 기능들을 지원합니다. 이 기능들은 상단에서 언급된 같은 API 엔드포인트들을 사용하여 구현되지만, 특수 파라미터와 필수 조건들이 사용됩니다. 

트래킹 언인스톨

Singular는 디바이스의 무소음 푸시 알림(Silent Push Notifications)을 사용하여 언인스톨을 트래킹할 수 있습니다. 이를 활성화하려면, 매 세션 알림과 함께 디바이스의 푸시 토큰(push token)을 Singular 서버로 전송해야 합니다.

Android에서 언인스톨 트래킹

Android에서 언인스톨 트래킹을 활성화하려면, 첫 번째로 앱으로부터 FirebaseInstanceId.getInstance().getToken()를 호출해서 FCM 토큰을 얻으세요. 만약 토큰이 아직 생성되지 않았다면 이 메서드는 null을 반환합니다. 더 많은 정보를 원하시면, 구글 파이어 베이스 도큐먼트(Google Firebase Documentation)를 참고하세요.

그 후 세션을 Singular에 리포팅할 때 fcm 파라미터 내 디바이스 토큰을 다음 예시와 같이 전달하세요.

Python HTTP cURL
import requests
import json

API_KEY = 'api_key_from_sdk_page'
LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'

params = {
  'a': API_KEY,
  'p': 'Android',
  'i': 'com.singular.app',
  'ip': '10.1.2.3',
  've': '9.2',
  'ma': 'samsung',
  'mo': 'SM-G935F',
  'lc': 'en_US',
  'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
  'andi': 'fc8d449516de0dfb',
  'utime': 1483228800,
  'dnt': 0,
  'n': 'MyCoolApp',
  'c': 'wifi',
  'cn': 'Comcast',
  'bd': 'Build/13D15',
  'fcm': 'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1'
}

result = requests.get(LAUNCH_URL, params=params)
print result.json()

iOS 내 언인스톨 트래킹

Singular는 Apple의 푸시 알림을 사용해 iOS의 언인스톨을 트래킹할 수 있습니다. 만약 앱이 푸시 알림을 지원하지 않는다면, 이 Apple 가이드를 참고하세요. 앱이 푸시 알림을 지원하면, Singular에게 세션을 리포트 할 때 APNS로 부터 반환되는 디바이스 토큰을 전달하세요. 

주의 사항

  • 저희는 귀사가 디바이스 토큰을 가져오는 곳에서 이미 푸시 알림을 구현했을 것이라 가정합니다. 
  • APNS 토큰은 보통 2진법 데이터 형식입니다. APNS로부터 받은 것처럼 Singular에게 전달하세요. 만약 앱이 다른 목적을 위해 토큰 데이터를 변경한다면, 그것을 hex로 인코딩된 문자열로 전달하시기를 권고드립니다. 예시:  encodedb0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
Python HTTP cURL
import requests
import json

API_KEY = 'api_key_from_sdk_page'
LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'

params = {
  'a': API_KEY,
  'p': 'iOS',
  'i': '162738612',
  'ip': '10.1.2.3',
  've': '9.2',
  'mo': 'iPhone9%2C4',
  'lc': 'en_US',
  'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
  'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
  'utime': 1483228800,
  'dnt': 0,
  'n': 'MyCoolApp',
  'c': 'wifi',
  'cn': 'Comcast',
  'bd': 'Build/13D15',
  'apns_token': 'b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052'
}

result = requests.get(LAUNCH_URL, params=params)
print result.json()

데이터 개인 정보 보호법 준수

Singular는 개인 정보를 보호하는 기능을 제공하여 귀사가 GDPR과 CCPA와 같은 개인 정보 보호법을 준수하는 모든 파트너와 협동할 수 있도록 합니다. 만약 유저(end-user)가 그들의 개인 정보를 공유하는 데 동의했다면 해당 파트너들은 이에 대해 알림 받기를 원할 것입니다. 

만약 유저들의 정보를 공유받는데 동의하는 방법을 구현하셨다면, data_sharing_options 파라미터를 사용하여 Singular에게 유저의 결정에 대하여 알려주세요. 

  • 유저가 (옵트인에 동의함으로) 그들의 정보 공유에 동의했는지를 나타내기 위해 "limit_data_sharing":false를 전달하세요. 
  • 만약 유저가 동의하지 않았다면 "limit_data_sharing":true를 전달하세요.

Singular는 관련 조항들을 준수하기 위해 이 정보가 필요한 파트너들에게 전달할 것입니다.

주의 사항

  • 해당 메서드의 사용은 필수는 아니지만, 유저가 구체적으로 옵트인(opt-in) 했다고 알렸을 때만 파트너가 Singular와 공유하는 어트리뷰션 정보가 있을 수 있습니다.  
  • JSON 오브젝트를 URL 인코딩하려면 GET 리퀘스트로 전달해야 함을 유념하세요.
필드 종류 설명 사용법
limit_data_sharing 불리안(boolean)

유저의 선호 사항을 나타내기 위해 모든 설치 또는 evt 리퀘스트에 이 선택사항을 전달하세요. 

data_sharing_options=
%7B%22limit_data_sharing%22%3Atrue%7D

레퍼런스: iOS 인스톨 영수증 가져오기

세션 알림 엔드포인트 레퍼런스(Session notification Endpoint Reference)에서 볼 수 있다시피, iOS 앱에 대한 세션을 리포팅할 때, install_receipt 파라미터 내 인스톨 영수증을 전달해야 합니다. 

이 값을 가져오려면, 앱에서 다음 코드를 추가하세요.

Objective-C
+ (NSString*)installReceipt {
    // install receipts are iOS 7.0+
    if (NSFoundationVersionNumber < NSFoundationVersionNumber_iOS_7_0) {
        return nil;
    }
    
    NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
    
    if (receiptURL) {
        NSData *receipt = [NSData dataWithContentsOfURL:receiptURL];
        
        if (receipt) {
            return [receipt base64EncodedStringWithOptions:0];
        }
    }
    
    return nil;
}

레퍼런스: 디바이스 식별자와 세션 데이터 가져오기

 이 부분에서는 어떻게 REST API 내 필수 값들을 가져올 수 있는지 구체적으로 설명합니다. 이 값들은 업계 표준을 기준으로, Apple과 Google도 이에 관한 도큐먼트를 갖고 있습니다. 편의를 위해 저희는 레퍼런스할 수 있는 몇몇 구현을 제공했습니다.  

Google 광고 ID/광고 트래킹 제한(Android 식별자) 가져오기  

앱 내 광고 ID를 얻기 위해서는 Google Play Services SDK가 필요합니다. AndroidManifest.xml 내 앱 요소의 차일드(child)로서 다음 태그를 추가하세요. 

XML
<meta-data android:name="com.google.android.gms.version"
           android:value="@integer/google_play_services_version" />

Google Advertising ID/Limit Ad Tracking 파라미터를 얻기 위한 샘플 코드는 다음과 같습니다.

Java
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
import com.google.android.gms.common.GooglePlayServicesAvailabilityException;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import java.io.IOException;

// Do not call this function from the main thread. Otherwise, 
// an IllegalStateException will be thrown.
public void getIdAndLAT() {
    Info adInfo = null;
    try {
        adInfo = AdvertisingIdClient.getAdvertisingIdInfo(mContext);
    } catch (IOException e) {
        // Unrecoverable error connecting to Google Play services (e.g.,
        // the old version of the service doesn't support getting AdvertisingId).
    } catch (GooglePlayServicesAvailabilityException e) {
        // Encountered a recoverable error connecting to Google Play services. 
    } catch (GooglePlayServicesNotAvailableException e) {
        // Google Play services is not available entirely.
    }

final String GAID = adInfo.getId(); final boolean limitAdTracking = adInfo.isLimitAdTrackingEnabled(); }

로케일(Locale), 디바이스, Android 빌드 가져오기

Java
// Locale - lc= query parameter
String locale = Locale.getDefault();

// Model - mo= query parameter
String device = Build.MODEL;

// Build - bd= query parameter
String build = "Build/" + Build.ID;

앱 추적 투명성 증명 상태(App Tracking Transparency Authorization Status) 가져오기 (iOS)

iOS 14.5 버전 부로, 디바이스의 IDFA를 가져오려면 앱 추적 투명성 (App Tracking Transparency)은 필수입니다. 만약 앱 추적 투명성 팝업 표시(App Tracking Transparency prompt)를 나타내려면, IDFA를 가져오기 전에 해당 팝업과 핸들러(handler)를 구현하세요.

다음은 ATT 팝업을 구현하는 방법(선택 사항)과 ATT 허가 상태 (ATT authorization status) (필수 사항)를 가져오는 방법에 관한 방법입니다 :

Objective-C
#import <AppTrackingTransparency/ATTrackingManager.h>

// OPTIONAL if you decide to show the ATT prompt // Show prompt and handle the value. Will only appear once even if called multiple times [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status){ // your authorization handler here }];
// REQUIRED // Reading the current ATT authorization status ATTrackingManagerAuthorizationStatus status = [ATTrackingManager trackingAuthorizationStatus];

IDFA/광고 추적 제한 (iOS 식별자) 가져오기

iOS 14.5 부로, 앱 추적 투명성(App Tracking Transparency)은 IDFA를 회수하는 데 있어 필수입니다. 만약 앱 추적 투명성 팝업(App Tracking Transparency prompt)을 나타내려면, IDFA를 가져오기 전에 해당 팝업과 핸들러(handler)를 구현하세요.

만약 앱 추적 투명성(App Tracking Transparency)을 나타내지 않을 계획이라면, 계속하여 IDFA를 가져올 수 있습니다. (하지만 해당 값은 제로가 됩니다) Singular는 IDFA를 사용할 수 없거나 모든 값이 제로인 경우 IDFV를 사용하는 만큼, 이 IDFV는 어떤 상황에서도 회수되어야 합니다. 

광고 추적 제한 (isAdvertisingTrackingEnabled) 플래그는 iOS 13 또는 그 이하 버전부터 요구됐으며 유저가 광고 추적에서 옵트아웃(opt-out) 하는 것을 표시하기 위해 사용되었습니다. iOS 14 또는 그 이상의 버전부터, 이 플래그는 지원이 중단되며, 만약 가져온다면 고정값을 나타냅니다. Singular와 파트너들은 개인 정보 플로우에 대한 데이터를 다루기 위해 새 ATT authorization status 값에 의존할 것입니다.

다음은 IDFA, IDFV, 광고 추적 제한 상태(limit-ad-tracking-status)에 대해 회수된 값의 예시입니다.  

Objective-C Swift
//Import the AdSupport class at the top of your file
@import AdSupport;

다음은 IDFA/앱 트래킹 파라미터 제한을 가져오는 샘플 코드입니다.

Objective-C Swift
NSString* IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
NSString* IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];

BOOL isAdvertisingTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];

로케일(Locale), 디바이스, iOS 빌드 가져오기

Objective-C Swift
// Locale - lc= query parameter
NSString *locale = [[NSLocale currentLocale] localeIdentifier];

// Model - mo= query paramter
#import <sys/sysctl.h>
NSString *device() {
    size_t bufferSize = 64;
    NSMutableData * buffer = [[NSMutableData alloc] initWithLength:bufferSize];
    int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0);
    if (status != 0) {
        return nil; 
    }
    return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
}

// Build - bd= query parameter
NSString * build () { 
    size_t bufferSize = 64;
    NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize];
    int status = sysctlbyname("kern.osversion",buffer.mutableBytes, &bufferSize, NULL, 0);
    if (status != 0) {
        return nil;
    }
    return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
}