Server-to-Server (S2S) API 엔드포인트

이 참조 문서에는 S2S 통합을 위해 Singular에서 제공하는 API 엔드포인트가 나열되어 있습니다.

참고: 서버 간 연동은 Enterprise 고객만 사용할 수있습니다.

업데이트 [2021년 11월]: 이제 이벤트 알림이 아닌 세션 알림 엔드포인트를 통해 Android 인스톨 리퍼러를 보고해야 합니다. 이렇게 하면 사용자가 앱을 열 때 즉시 인스톨 리퍼러를 Singular에서 사용할 수 있으며, Google의 모범 사례를 따릅니다. 자세한 내용은 구글 플레이 인스톨 리퍼러 보내기(안드로이드)를 참조하세요.

 

인증 및 상태 코드

S2S API에 대한 모든 호출에는 SDK 키가 포함되어야 합니다. 이를 검색하려면 Singular에 로그인하여 "개발자 도구 > SDK 통합 > SDK 키"로 이동하세요.

S2S API 호출이 성공하면 반환되는 HTTP 상태 코드는 200입니다. 다른 코드는 호출을 다시 시도해야 함을 의미합니다.

Singular S2S API 엔드포인트 목록

다음 API 엔드포인트를 사용할 수 있습니다:

세션 알림 GET https://s2s.singular.net/api/v1/launch 새 세션을 Singular에 보고합니다.
이벤트 알림 GET https://s2s.singular.net/api/v1/evt 인앱 이벤트를 Singular에 보고합니다.

세션 알림 엔드포인트

GET https://s2s.singular.net/api/v1/launch

세션 알림 엔드포인트를 사용하여 싱귤러에 세션을 보고하세요.

필수 세션 매개변수

파라미터 설명 지원되는 플랫폼 예시
a 단일 SDK 키입니다. iOS, Android,
PC, Console
your_org_name_sh868sdjv
p 다음 플랫폼 중 하나입니다:
Android, iOS, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android,
PC, Console
Android
i 애플리케이션의 패키지 이름(Android) 또는 번들 ID(iOS). iOS, Android,
PC, Console
com.singular.app
ip 기기의 IP. iOS, Android,
PC, Console
172.58.29.235
ve 세션 시점의 장치 OS 버전입니다. iOS, Android,
PC, Console
9.2
install_ref 구글 인스톨 리퍼러 정보 Android 자세히알아보기
meta_ref 메타 인스톨 리퍼러 정보 Android 자세히알아보기
asid 앱 세트 ID(안드로이드 12 이상 기기의 경우) Android 자세히알아보기
ma 디바이스 하드웨어의 제조사, 일반적으로 소비자가 인식할 수 있는 이름(예: 삼성, LG, Apple)입니다. 이 파라미터는 모델 파라미터와 함께 사용해야 합니다. iOS, Android samsung
mo 디바이스 하드웨어의 모델(예: iPhone 4S, Galaxy SIII). 이 파라미터는 make 파라미터와 함께 사용해야 합니다. iOS, Android SM-G935F
lc 밑줄로 구분된 두 글자로 된 언어와 국가 코드를 사용하는 디바이스의 IETF 로컬 태그입니다. iOS, Android en_US
bd 인코딩된 디바이스 빌드, URL iOS, Android Build%2F13D15
openuri 앱이 딥링크/유니버설 링크/앱 링크를 통해 열린 경우 인코딩된 딥링크 URL 값입니다. iOS, Android myapp%3A%2F%2Fhome%2Fpage%3 Fqueryparam1%3D value1%26queryparam2%3 Dvalue2
idfa iOS 앱에만 해당됩니다. 대시를 포함한 대문자 원시 광고 ID. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv iOS 앱에만 해당합니다. 대시를 포함한 대문자 원시 식별자 ForVendor. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa 안드로이드 앱에만 해당. 대시가 포함된 소문자 원시 광고 ID. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
andi 안드로이드 앱에만 해당. 소문자 원시 안드로이드 ID. 기기에서 안드로이드 광고 ID를 사용할 수 없는 경우에만 필요합니다. Android fc8d449516de0dfb
sdid

PC/콘솔: 게임의 고유한 설치를 나타내는 클라이언트 측에서 생성한 UUID입니다.

PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
dnt 추적 금지가 활성화되면 1을, 추적 금지가 비활성화되면 0을 전달합니다. iOS, Android 1
app_v 앱 버전 iOS, Android 1.2.3
install_source

Android의 인스톨 소스 패키지 이름(예: 'com.android.vending'). 이 값을 검색하려면 InstallSourceInfo.getInitiatingPackageName()을 사용합니다.

 

PC의 설치 스토어, 지원/권장 값: steam, epic, microsoftstore, humblestore, gog, selfdistributed

Android, PC

Android:

com.vending.android (Android)

steam (PC)


install_receipt 설치 후 받은 영수증. iOS 설치 영수증에서 검색하는 방법을 알아보세요. iOS MIISqwYJKoZI...cNqts0jvcNvPcK7 yuj0KhJ9nTTQ54kDKfReihzc6aw====
install 설치 플래그. 앱을 설치한 후 첫 번째 세션인 경우 'true'. 그렇지 않으면 'false'. 재설치 추적 기능에 필요합니다. iOS, Android,
PC, Console
false
install_time 첫 번째 앱 설치 시간(UNIX 시간)입니다. 이 값을 검색하려면 플랫폼의 링크를 사용합니다. iOS, Android 1510040127
update_time 마지막 앱 업데이트 시간(UNIX 시간)입니다. 이 값을 검색하려면 플랫폼의 링크를 사용합니다. iOS, Android 1510040127
ddl_enabled 디퍼드 딥링크 플래그. 서버가 디퍼드 딥링크 URL을 반환할 것으로 예상하면 'true'를 반환합니다. 그렇지 않으면 'false'. 자세한 내용은 디퍼드 딥링킹에 대한 섹션을 참조하세요. iOS, Android true
singular_link_resolve_required 단수 쇼트 링크를 해결하는 데 사용됩니다. 단수 쇼트 링크인 "openuri" 값과 함께 전송해야 합니다. 쇼트 링크처리를 참조하세요.

iOS,
Android

true
att_authorization_status *

iOS 14 이상에서 사용 가능. 앱 추적 투명성 인증 상태.

지원되는 값은

  • 0 - Undetermined, ATT 프롬프트가 아직 표시되지 않았습니다. iOS 14.5 이상에서 IDFA를 사용할 수 없습니다.
  • 1 - Restricted 는 사용자가 ATT 프롬프트 표시 옵션을 비활성화했습니다. IDFA를 사용할 수 없습니다.
  • 2 - Denied 사용자가 ATT 프롬프트를 보고 인증을 거부했습니다. IDFA를 사용할 수 없음
  • 3 - Authorized 는 사용자가 ATT 프롬프트를 보고 권한을 부여한 경우입니다. IDFA 사용 가능
iOS 3

*참고: iOS 14.5부터 IDFA에 액세스하려면 ATT(앱 추적 투명성) 프롬프트가 필요합니다. ATT 프롬프트를 구현하지 않더라도 ATT 권한 부여 상태를 "미결정"을 나타내는 "0" 값으로 단수(Singular)로 전달해야 합니다.

선택적 세션 매개변수

파라미터 설명 지원되는 플랫폼 예시
custom_user_id User ID iOS, Android,
PC, Console
 123456789abcd
n UI에 표시되는 애플리케이션의 사람이 읽을 수 있는 이름입니다. iOS, Android,
PC, Console
MyCoolApp
utime 세션의 시간(UNIX 시간)입니다. iOS, Android,
PC, Console
1483228800
umilisec 밀리초 단위의 세션 시간(UNIX 시간)입니다. iOS, Android,
PC, Console
1483228800000
dntoff '추적 안 함'이 활성화된 경우 0을, '추적 안 함'이 비활성화된 경우 1을 전달합니다. iOS, Android 0
c 연결 유형 '와이파이' 또는 '통신사'. iOS, Android wifi
cn 인터넷 제공업체의 통신사 이름입니다. iOS, Android Comcast
use_ip HTTP 요청에서 'ip' 필드 대신 IP 필드를 추출합니다. IP 매개변수와 함께 사용하지 마세요. iOS, Android,
PC, Console
true
fcm 파이어베이스 클라우드 메시징 디바이스 토큰. 안드로이드 제거 추적에 필요 Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvD MExUdFQ3P1
gcm 구글 클라우드 메시징 디바이스 토큰. Android 제거 추적(레거시)에 필요합니다. Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvDM ExUdFQ3P1
apns_token Apple 푸시 알림 서비스 디바이스 토큰. iOS 제거 추적에 필요 iOS b0adf7c9730763f88e1a048e28c68a9f806ed032fb522deb...ff5bfba010a9b052
ua 기기의 사용자 에이전트 iOS, Android,
PC, Console
Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
attribution_token iOS 14.3 이상용 Apple 검색 광고 어트리뷰션에 사용됩니다. 이 값은 애드서비스 프레임워크를 통해 확인할 수 있습니다. 검색 방법은 애드서비스를 통한 Apple 검색 광고 구현하기에서확인하세요. iOS G9i5hC8lQJeGOfmS+MFycll/02...AAABBEQQBQA=
skan_conversion_value 이 세션 알림 시점의 최신 SKAdNetwork 전환 값(SKAdNetwork 구현에 대해 자세히 알아보기). iOS 0 - 63
skan_first_call_timestamp 기본 SKAdNetwork API에 대한 첫 번째 호출의 유닉스 타임스탬프(SKAdNetwork 구현에 대해 자세히 알아보려면 여기를 참조하세요). iOS 1483228800
skan_last_call_timestamp 이 세션 알림 시점에 기반이 되는 SkAdNetwork API에 대한 최신 호출의 유닉스 타임스탬프 (SKAdNetwork 구현에 대해 자세히 알아보려면 여기를 참조하세요). iOS 1483228800
global_properties 글로벌 속성은 최대 5개까지 정의할 수 있습니다. 각 속성 키와 값은 최대 200자까지 입력할 수 있습니다. 더 긴 속성 이름이나 값을 전달하면 200자로 잘립니다. 값은 URLEncoded JSON 객체여야 합니다. iOS, Android,
PC, Console
%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

정보 공유에 대한 최종 사용자의 동의를 표시합니다. 설정된 경우 이 값은 유지되며 사용자에 대한 후속 /launch 및 /evt 요청 시마다 전달되어야 합니다.

사용자가 정보 공유에 동의(옵트인)했음을 표시하려면 "limit_data_sharing":false를 전달합니다.

사용자가 거부한 경우 "limit_data_sharing":true를 전달합니다.

선택 사항

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

샘플 API 호출

파이썬 HTTP cURL 자바
import requests
import json
  
   SDK_KEY = '[개발자 도구 > SDK 통합 > SDK 키의 sdk_key].'
   LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
   params = {
       'a': SDK_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': '123456789abcd',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } result = requests.get(LAUNCH_URL, params=params) print result.json()

이벤트 알림 엔드포인트

GET https://s2s.singular.net/api/v1/evt

이 엔드포인트를 사용하여 세션 이외의 애플리케이션에서 발생하는 모든 이벤트를 보고하세요.

필수 이벤트 매개변수

파라미터 설명 지원 플랫폼 예시
n

이벤트 이름입니다.

Singular의 표준 이벤트 명명 규칙을 사용하는 것이 좋습니다.

iOS, Android, Web,
PC, Console
sng_add_to_cart
a 싱글 SDK 키. iOS, Android, Web,
PC, Console
a42be1d8119389dd36c7_acbeaf6abcd8
p 다음 플랫폼 중 하나입니다:
Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android, Web,
PC, Console
Android
i 모바일 애플리케이션의 패키지 이름(Android) 또는 번들 ID(iOS) 또는 WebSDK의 제품 ID. iOS, Android, Web,
PC, Console
com.yourcompany.app
ip 이벤트의 IP. iOS, Android, Web,
PC, Console
172.58.29.235
idfa iOS 앱에만 해당합니다. 대시를 포함한 대문자 원시 광고 ID. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv iOS 앱에만 해당합니다. 대시를 포함한 대문자 원시 공급업체 식별자. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa 안드로이드 앱에만 해당. 대시가 포함된 소문자 원시 광고 ID. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
asid 앱 세트 ID(Android 12 이상 기기용) 자세히 알아보기 Android edee92a2-7b2f-45f4-a509-840f170fc6d9
andi 안드로이드 앱 전용. 소문자 원시 안드로이드 ID. 기기에서 안드로이드 광고 ID를 사용할 수 없는 경우에만 필요합니다. Android fc8d449516de0dfb
sdid

웹: 싱귤러 웹SDK에서 제공하는 UUIDv4 디바이스 ID 자세히알아보기

PC/콘솔: 게임의 고유한 설치를 나타내는 클라이언트 측에서 생성된 UUID입니다.

Web, PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
ve 이벤트 시점의 디바이스 OS 버전. iOS, Android, Web,
PC, Console
9.2
att_authorization_status * 앱 트래킹 투명성 인증 상태. iOS 14 이상에서 사용 가능합니다.

지원되는 값입니다:

  • 0 - Undetermined, ATT 프롬프트가 아직 표시되지 않았습니다. iOS 14.5 이상에서 IDFA 사용 불가
  • 1 - Restricted 는 사용자가 ATT 프롬프트 표시 옵션을 비활성화했습니다. IDFA를 사용할 수 없습니다.
  • 2 - Denied 사용자가 ATT 프롬프트를 보고 인증을 거부했습니다. IDFA를 사용할 수 없음
  • 3 - Authorized 는 사용자가 ATT 프롬프트를 보고 권한을 부여한 경우입니다. IDFA 사용 가능
iOS 3

*참고:iOS 14.5부터 디바이스의 IDFA에 액세스하려면 ATT(앱 추적 투명성) 프롬프트가 필요합니다. ATT 프롬프트를 구현하지 않더라도 ATT 인증 상태를 '미결정'을 나타내는 '0' 값과 함께 '단수'로 전달해야 합니다.

선택적 이벤트 매개변수

파라미터 설명 지원 플랫폼 예제
custom_user_id User ID  iOS, Android, Web,
PC, Console
123456789abcd
utime 이벤트 시간(UNIX 시간)입니다. 참고: 시간은 설치 시간보다 작아서는 안 됩니다. iOS, Android, Web,
PC, Console
1483228800
umilisec 이벤트 시간(밀리초)(UNIX 시간). 참고: 시간은 설치 시간보다 작아서는 안 됩니다. iOS, Android, Web,
PC, Console
1483228800000
use_ip HTTP 요청에서 IP 필드를 추출합니다. 이 값을 true로 설정하는 경우 ip 매개 변수를 제공하지 마세요. iOS, Android, Web,
PC, Console
true
e

JSON 형식의 사용자 지정 이벤트 속성.

Singular의 표준 이벤트 속성 명명 규칙을 사용할 것을 적극 권장합니다.

iOS, Android, Web,
PC, Console
%7B%22sng_attr_content_id%22%3A5581%2C
sng_attr_content%22%3A%22XBox%22%2C%22
sng_attr_content_type%22%3A%22electronics%22%7D
global_properties 글로벌 속성은 최대 5개까지 정의할 수 있습니다. 각 속성 키와 값은 최대 200자까지 입력할 수 있습니다. 더 긴 속성 이름이나 값을 전달하면 200자로 잘립니다. 값은 URL로 인코딩된 JSON 개체여야 합니다. iOS, Android, Web,
PC, Console
%7B%22key1%22%3A%22value1%22
%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

정보 공유에 대한 최종 사용자의 동의를 표시합니다. 설정된 경우 이 값은 유지되며 사용자에 대한 후속 /launch 및 /evt 요청 시마다 전달되어야 합니다.

사용자가 정보 공유에 동의(옵트인)했음을 표시하려면 "limit_data_sharing":false를 전달합니다.

사용자가 거부한 경우 "limit_data_sharing":true를 전달합니다.

선택 사항

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

skan_conversion_value 이 이벤트 알림 시점의 최신 SKAdNetwork 전환 값(SKAdNetwork 구현에 대해 자세히 알아보려면 여기를 참조하세요). iOS 0 - 63
skan_first_call_timestamp 기본 SKAdNetwork API에 대한 첫 번째 호출의 유닉스 타임스탬프(SKAdNetwork 구현에 대해 자세히 알아보려면 여기를 참조하세요). iOS 1483228800
skan_last_call_timestamp 이 이벤트 알림이 발생한 시점의 기본 SkAdNetwork API에 대한 최신 호출의 유닉스 타임스탬프 (SKAdNetwork 구현에 대해 자세히 알아보려면 여기를 참조하세요). iOS 1483228800

 

수익 이벤트 파라미터

파라미터 설명 지원되는 플랫폼 예시
is_revenue_event 수익 이벤트인지 여부입니다. 이벤트 이름이 __iap__이거나 0이 아닌 금액이 제공된 경우 이 값을 생략할 수 있습니다. iOS, Android, Web, PC, Console True
amt 통화 금액입니다. 이 값은 cur 매개변수와 함께 사용해야 합니다. iOS, Android, Web, PC, Console 2.51
cur ISO 4217세 글자 통화 코드입니다. 이 코드는 amt 매개변수와 함께 사용해야 합니다. iOS, Android, Web, PC, Console EUR
purchase_receipt 구매 시 받은 영수증입니다. Android, iOS에서검색하는 방법은 아래 지침을 참조하세요. iOS, Android

iOS:
MIISqwYJKoZI...cNqts0jvcNvPcK7y
uj0KhJ9nTTQ54kDKfReihzc6aw==

Android:
{"orderId":"GPA.1234",
"packageName":"com.example",
"productId":"com.example.product",
"purchaseTime":1417113074914,
"purchaseState":0,
"purchaseToken":"hakfcimbk... pM"} 

receipt_signature 구매 영수증에 서명하는 데 사용된 서명입니다. Android TyVJfHg8OAoW7W4wuJt... 5agEDMnNXvhfrw==
purchase_product_id 제품 SKU 식별자 iOS, Android, Web, PC, Console

com.example.product

purchase_transaction_id 거래 식별자 iOS, Android, Web, PC, Console

iOS: 380000123004321

Android: GPA.1234-1234- 1234-12345 

샘플 API 호출

Python HTTP cURL Java
import requests
import json
  
  SDK_KEY = '[개발자 도구 > SDK 통합 > SDK 키의 sdk_key].'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  params = {
   'n': 'levelup',
   'e': json.dumps({"level": "10"}),
   'a': SDK_KEY,
   'p': 'Android',
   'i': 'com.yourcompany.app',
   'ip': '10.1.2.3',
   'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
   'andi': 'fc8d449516de0dfb',
   'utime': 1483228800,
   'custom_user_id': '123456789abcd',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } result = requests.get(EVENT_URL, params=params) print result.json()