PC 및 Console API 엔드포인트 레퍼런스
세션 추적과 이벤트 리포팅을 위한 상세한 파라미터 명세와 구현 예제를 제공하는, PC 및 Console server-to-server 엔드포인트에 대한 완전한 API 레퍼런스입니다.
관련 레퍼런스: PC 및 Console은 제품군의 나머지 부분과 동일한 S2S 엔드포인트를 사용합니다. 모바일 및 웹에 해당하는 내용은 SESSION 엔드포인트 레퍼런스 및 EVENT 엔드포인트 레퍼런스를 참고하세요. 이 레퍼런스는 PC 및 Console의 세션 및 이벤트 엔드포인트를 다룹니다.
엔터프라이즈 기능: PC 및 Console 게임 어트리뷰션은 엔터프라이즈 기능입니다. 자세한 내용은 PC 및 Console 게임 어트리뷰션 FAQ 를 참조하거나 고객 성공 매니저에게 문의하세요.
연동 가이드: 완전한 구현 지침과 모범 사례는 PC 및 Console S2S 연동 가이드 를 참조하세요.
세션 알림 엔드포인트
인스톨 어트리뷰션, 리인게이지먼트 추적, 사용자 리텐션 분석을 위해 게임 실행과 세션을 Singular에 리포팅합니다.
엔드포인트 명세
| 메서드 | URL |
|---|---|
POST
|
https://s2s.singular.net/api/v1/launch
|
파라미터는
application/x-www-form-urlencoded
요청 본문으로 전송됩니다. 다음 필수 헤더를 포함하세요:
Content-Type: application/x-www-form-urlencoded목적
세션 알림 엔드포인트를 사용하여 모든 게임 실행(최초 및 반복 세션)을 거의 실시간으로 리포팅하세요. Singular Device ID로 식별되는 인스톨에 대해 Singular가 수신한 최초 게임 실행이 어트리뷰션 프로세스를 트리거합니다.
어트리뷰션 워크플로우:
- 최초 세션: 웹 캠페인 클릭과의 매칭을 통해 인스톨 어트리뷰션을 트리거합니다
- 이후 세션: 사용자 활동, 리텐션, 리인게이지먼트 분석을 위해 추적됩니다
- 실시간 리포팅: 세션 알림을 실제 게임 실행에 최대한 가깝게 전송하세요
세션 파라미터
필수 파라미터
| 파라미터 | 세부 정보 |
|---|---|
a |
유형: String
중요: Reporting API Key를 사용하지 마십시오. 요청이 거부됩니다.
예시:
|
p
|
유형: String
|
i
|
유형: String
중요: 어트리뷰션이 작동하려면 Web SDK Product ID와 정확히 일치해야 합니다. 동일한 게임에 대해 모든 플랫폼에서 같은 값을 사용하세요.
예시:
|
sdid
|
유형: UUIDv4
|
os
|
유형: String
|
install_source
|
유형: String
|
ip
|
유형: String
대안: 명시적으로 전달하는 대신
예시:
|
선택적 파라미터
다음 선택적 파라미터가 지원됩니다.
| 파라미터 | 세부 정보 |
|---|---|
install_ref
|
유형: String
요구사항:
구현 세부 사항은
Native PC용 Google Play Install Referrer 문서
를 참조하세요.
|
match_id
|
유형: String
요구사항:
구현 세부 사항은
Match ID 어트리뷰션
을 참조하세요.
|
av
|
유형: String
|
global_properties
|
유형: JSON
|
install
|
유형: Boolean
|
utime
|
유형: Integer
|
umilisec
|
유형: Integer
|
ve |
유형: String
|
ua |
유형: String
|
use_ip |
유형: Boolean
제한 사항:
예시:
|
data_sharing_options |
유형: JSON
|
custom_user_id |
유형: String
PII 금지: 개인 식별 정보를 전달하지 마십시오. 원본 이메일 주소, 전화번호, 이름 대신 해시 처리되거나 익명화된 내부 식별자를 사용하십시오.
예시:
|
요청 예제
샘플 구현
기본 세션 요청
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "a=your_sdk_key" \
--data-urlencode "i=com.singular.game" \
--data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
--data-urlencode "p=PC" \
--data-urlencode "os=windows" \
--data-urlencode "install_source=steam" \
--data-urlencode "ip=172.58.29.235"Match ID를 포함한 최초 실행
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "a=your_sdk_key" \
--data-urlencode "i=com.singular.game" \
--data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
--data-urlencode "p=PC" \
--data-urlencode "os=windows" \
--data-urlencode "install_source=steam" \
--data-urlencode "ip=172.58.29.235" \
--data-urlencode "match_id=abc123def456" \
--data-urlencode "install=true"기본 세션 요청
import requests
def report_session(config):
url = "https://s2s.singular.net/api/v1/launch"
params = {
'a': config['sdk_key'],
'i': config['game_id'],
'sdid': config['device_id'],
'p': config['platform'],
'os': config['os_version'],
'install_source': config['store'],
'ip': config['ip_address']
}
response = requests.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
return response.json()
# Example usage
report_session({
'sdk_key': 'your_sdk_key',
'game_id': 'com.singular.game',
'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
'platform': 'PC',
'os_version': 'windows',
'store': 'steam',
'ip_address': '172.58.29.235'
})Match ID를 포함한 최초 실행
def report_first_launch(config):
url = "https://s2s.singular.net/api/v1/launch"
params = {
'a': config['sdk_key'],
'i': config['game_id'],
'sdid': config['device_id'],
'p': config['platform'],
'os': config['os_version'],
'install_source': config['store'],
'ip': config['ip_address'],
'match_id': config['match_id'],
'install': 'true'
}
response = requests.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
return response.json()기본 세션 요청
async function reportSession(config) {
const url = 'https://s2s.singular.net/api/v1/launch';
const params = new URLSearchParams({
'a': config.sdkKey,
'i': config.gameId,
'sdid': config.deviceId,
'p': config.platform,
'os': config.osVersion,
'install_source': config.store,
'ip': config.ipAddress
});
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
return await response.json();
}
// Example usage
reportSession({
sdkKey: 'your_sdk_key',
gameId: 'com.singular.game',
deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
platform: 'PC',
osVersion: 'windows',
store: 'steam',
ipAddress: '172.58.29.235'
});Match ID를 포함한 최초 실행
async function reportFirstLaunch(config) {
const url = 'https://s2s.singular.net/api/v1/launch';
const params = new URLSearchParams({
'a': config.sdkKey,
'i': config.gameId,
'sdid': config.deviceId,
'p': config.platform,
'os': config.osVersion,
'install_source': config.store,
'ip': config.ipAddress,
'match_id': config.matchId,
'install': 'true'
});
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
return await response.json();
}이벤트 알림 엔드포인트
파트너 Conversion API 지원:
Singular의 Conversion API 연동을 통해 이러한 이벤트를 광고 네트워크 파트너에게 전달하려면, 표준 선택적 이벤트 속성(예:
eventId
및
ehash
와 같은 해시 처리된 퍼스트 파티 데이터)을 포함하세요.
Conversion API 연동을 위한 표준 이벤트 속성
을 참조하세요.
분석, 캠페인 최적화, 파트너 전달을 위해 인게임 이벤트를 Singular에 리포팅합니다.
2026년 7월 15일부터 V2 필수. 2026년 7월 15일 이후에 생성된 계정은 Event Endpoint V2(SDID 기반)를 사용해야 하며, 신규 계정에는 V1을 사용할 수 없습니다. 이미 V1으로 연동된 기존 고객은 영향을 받지 않습니다. V2로 마이그레이션하려면 담당 Singular Customer Success Manager에게 문의하세요.
엔드포인트 명세
| 메서드 | URL |
|---|---|
POST
|
https://s2s.singular.net/api/v2/evt
|
파라미터는
application/x-www-form-urlencoded
요청 본문으로 전송됩니다. 다음 필수 헤더를 포함하세요:
Content-Type: application/x-www-form-urlencoded목적
이벤트 알림 엔드포인트를 사용하여 원하는 모든 인게임 이벤트를 거의 실시간으로 리포팅하세요. 이벤트 데이터는 분석, 리포팅, 파트너 최적화, 캠페인 성과 측정에 사용됩니다.
이벤트 모범 사례:
- 표준 이벤트: 자동 파트너 매핑을 위해 Singular 표준 이벤트 이름 을 사용하세요
- 실시간 리포팅: 이벤트를 실제 발생 시점에 최대한 가깝게 전송하세요
- 매출 이벤트: 구매 추적 및 ROI 분석을 위해 매출 파라미터를 포함하세요
이벤트 파라미터
필수 파라미터
| 파라미터 | 세부 정보 |
|---|---|
a |
유형: String
중요: Reporting API Key를 사용하지 마십시오. 요청이 거부됩니다.
예시:
|
p
|
유형: String
|
i
|
유형: String
|
sdid
|
유형: UUIDv4
|
n
|
유형: String
권장: 자동 파트너 연동을 위해 Singular 표준 이벤트 이름 을 사용하세요.
예시:
|
os
|
유형: String
|
install_source
|
유형: String
|
ip
|
유형: String
|
선택적 파라미터
다음 선택적 파라미터가 지원됩니다.
| 파라미터 | 세부 정보 |
|---|---|
e
|
유형: JSON
권장: 파트너 호환성을 위해 Singular 표준 속성 이름 을 사용하세요.
예시:
|
is_revenue_event
|
유형: Boolean
|
amt
|
유형: Number
|
cur
|
유형: String
|
av
|
유형: String
|
global_properties
|
유형: JSON
|
utime
|
유형: Integer
|
umilisec
|
유형: Integer
|
ve |
유형: String
|
ua |
유형: String
|
use_ip |
유형: Boolean
제한 사항:
예시:
|
data_sharing_options |
유형: JSON
|
custom_user_id |
유형: String
PII 금지: 개인 식별 정보를 전달하지 마십시오. 원본 이메일 주소, 전화번호, 이름 대신 해시 처리되거나 익명화된 내부 식별자를 사용하십시오.
예시:
|
요청 예제
샘플 구현
표준 이벤트
curl -X POST "https://s2s.singular.net/api/v2/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "a=your_sdk_key" \
--data-urlencode "i=com.singular.game" \
--data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
--data-urlencode "p=PC" \
--data-urlencode "os=windows" \
--data-urlencode "install_source=steam" \
--data-urlencode "n=sng_level_achieved" \
--data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
--data-urlencode "ip=172.58.29.235"매출 이벤트
curl -X POST "https://s2s.singular.net/api/v2/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "a=your_sdk_key" \
--data-urlencode "i=com.singular.game" \
--data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
--data-urlencode "p=PC" \
--data-urlencode "os=windows" \
--data-urlencode "install_source=steam" \
--data-urlencode "n=__iap__" \
--data-urlencode "is_revenue_event=true" \
--data-urlencode "amt=9.99" \
--data-urlencode "cur=USD" \
--data-urlencode "ip=172.58.29.235"표준 이벤트
import requests
import json
def report_event(config):
url = "https://s2s.singular.net/api/v2/evt"
params = {
'a': config['sdk_key'],
'i': config['game_id'],
'sdid': config['device_id'],
'p': config['platform'],
'os': config['os_version'],
'install_source': config['store'],
'n': config['event_name'],
'ip': config['ip_address']
}
if 'attributes' in config:
params['e'] = json.dumps(config['attributes'])
response = requests.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
return response.json()
# Example usage
report_event({
'sdk_key': 'your_sdk_key',
'game_id': 'com.singular.game',
'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
'platform': 'PC',
'os_version': 'windows',
'store': 'steam',
'event_name': 'sng_level_achieved',
'attributes': {
'sng_attr_level': '5',
'sng_attr_score': '1250'
},
'ip_address': '172.58.29.235'
})매출 이벤트
def report_revenue(config):
url = "https://s2s.singular.net/api/v2/evt"
params = {
'a': config['sdk_key'],
'i': config['game_id'],
'sdid': config['device_id'],
'p': config['platform'],
'os': config['os_version'],
'install_source': config['store'],
'n': '__iap__',
'is_revenue_event': 'true',
'amt': config['amount'],
'cur': config['currency'],
'ip': config['ip_address']
}
response = requests.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
return response.json()
# Example usage
report_revenue({
'sdk_key': 'your_sdk_key',
'game_id': 'com.singular.game',
'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
'platform': 'PC',
'os_version': 'windows',
'store': 'steam',
'amount': 9.99,
'currency': 'USD',
'ip_address': '172.58.29.235'
})표준 이벤트
async function reportEvent(config) {
const url = 'https://s2s.singular.net/api/v2/evt';
const params = new URLSearchParams({
'a': config.sdkKey,
'i': config.gameId,
'sdid': config.deviceId,
'p': config.platform,
'os': config.osVersion,
'install_source': config.store,
'n': config.eventName,
'ip': config.ipAddress
});
if (config.attributes) {
params.append('e', JSON.stringify(config.attributes));
}
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
return await response.json();
}
// Example usage
reportEvent({
sdkKey: 'your_sdk_key',
gameId: 'com.singular.game',
deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
platform: 'PC',
osVersion: 'windows',
store: 'steam',
eventName: 'sng_level_achieved',
attributes: {
'sng_attr_level': '5',
'sng_attr_score': '1250'
},
ipAddress: '172.58.29.235'
});매출 이벤트
async function reportRevenue(config) {
const url = 'https://s2s.singular.net/api/v2/evt';
const params = new URLSearchParams({
'a': config.sdkKey,
'i': config.gameId,
'sdid': config.deviceId,
'p': config.platform,
'os': config.osVersion,
'install_source': config.store,
'n': '__iap__',
'is_revenue_event': 'true',
'amt': config.amount,
'cur': config.currency,
'ip': config.ipAddress
});
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
return await response.json();
}
// Example usage
reportRevenue({
sdkKey: 'your_sdk_key',
gameId: 'com.singular.game',
deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
platform: 'PC',
osVersion: 'windows',
store: 'steam',
amount: 9.99,
currency: 'USD',
ipAddress: '172.58.29.235'
});응답 처리
두 엔드포인트 모두 일관된 JSON 응답을 반환하며, 성공 또는 오류를 판단하기 위해 status 필드 검증이 필요합니다.
응답 형식
중요:
모든 응답은 HTTP 200 상태
코드를 반환합니다. 성공
(
ok
)
또는 실패(
error
)를 판단하려면 항상 응답 본문의
status
필드를 검증하세요.
완전한 응답 코드 문서와 오류 처리 전략은 S2S 응답 코드 및 오류 처리 를 참조하세요.
추가 리소스
- 연동 가이드: PC 및 Console S2S 연동 가이드
- Web SDK: Web SDK 개요 및 시작하기
- 어트리뷰션 FAQ: PC 및 Console 게임 어트리뷰션 FAQ
- 표준 이벤트: Singular 표준 이벤트 레퍼런스