문서

PC 및 콘솔 API 엔드포인트 참조

PC 및 콘솔 서버 간 엔드포인트에 대한 완전한 API 참조 자료로, 세션 추적 및 이벤트 보고를 위한 상세한 매개변수 사양과 구현 예제를 제공합니다.

엔터프라이즈 기능: PC 및 콘솔 게임 어트리뷰션은 엔터프라이즈 기능입니다. 자세한 내용은 PC 및 콘솔 게임 어트리뷰션 FAQ를참조하거나 고객 성공 매니저에게 문의하십시오.

연동 가이드: 완전한 구현 지침 및 모범 사례는 PC 및 콘솔 S2S 연동 가이드를 참조하십시오.

세션 알림 엔드포인트

게임 실행 및 세션을 Singular에 보고하여 설치 어트리뷰션, 리인게이지먼트 추적 및 사용자 유지 분석을 수행합니다.

엔드포인트 사양

메서드	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

목적

세션 알림 엔드포인트를 사용하여 모든 게임 실행(첫 실행 및 반복 세션)을 실시간에 가깝게 보고합니다. Singular 디바이스 ID로 식별된 첫 게임 실행이 Singular에 수신되면 설치 어트리뷰션 프로세스가 시작됩니다.

어트리뷰션 워크플로우:

첫 세션: 설치 어트리뷰션 트리거 웹 캠페인 클릭과의 매칭 수행
후속 세션: 사용자 활동, 유지율, 리인게이지먼트 분석 추적
실시간 보고: 실제 게임 실행 시점과 최대한 가깝게 세션 알림 전송

세션 매개변수

필수 매개변수

매개변수	설명	제약 조건	예시
`a`	API 인증을 위한 고유한 SDK 키. 위치: 대시보드 → 개발자 도구 → SDK 연동 → SDK 키 중요: 리포팅 API 키가 아닌 SDK 키를 사용하세요.	필수 문자열	`your_org_name_sh868sdjv`
`p`	사용자가 게임을 플레이하는 플랫폼. 지원되는 값: `pc` `xbox` `playstation` `nintendo` `metaquest`	필수 문자열 대소문자 구분	`pc`
`i`	게임 식별자. 게임에 고유한 값이어야 합니다. 중요: 어트리뷰션이 작동하려면 웹 SDK 제품 ID와 정확히 일치해야 합니다. 동일한 게임에 대해 모든 플랫폼에서 동일한 값을 사용하십시오.	필수 역 DNS 표기법 권장 대소문자 구분	`com.singular.game`
`sdid`	Singular 게임 설치 및 사용자 활동을 식별하는 Singular 기기 ID. 생성: 게임/서버가 첫 실행 시 생성하며, 게임 설치 수명 주기 동안 유지됩니다.	필수 UUID 버전 4 형식 권장	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	운영 체제 또는 게임 시스템. 사용자 정의 값 지원 가능하나 플랫폼별 권장값: PC: windows, linux, macos, steamos Xbox: xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation: playstation_3, playstation_4, playstation_5 닌텐도: nintendo_switch Meta Quest: metaquest, metaquest_2, metaquest_pro	필수 사용자 정의 값 지원	`windows`
`install_source`	게임 스토어 또는 배포 방법. 권장 값: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` 사용자 정의 값 지원	필수 사용자 정의 값 지원	`steam`
`ip`	게임 실행 시점의 기기 IP 주소. 대안: 명시적으로 전달하는 대신 HTTP 요청 헤더에서 IP를 추출하려면 `use_ip=true`사용.	필수 IPv4 또는 IPv6 형식 `use_ip=true` 사용 시 불필요	`172.58.29.235`

선택적 매개변수

매개변수	설명	제약 조건	예시
`install_ref`	JSON URL 인코딩된 Google 설치 리퍼러 정보. Google Play 게임 스토어를 통해 배포되는 네이티브 PC 게임에 대해 가장 정확한 어트리뷰션을 제공합니다. 요구 사항: Play Games PC SDK구현이 필요하며 첫 게임 실행 시에만 첫 게임 실행 시에만 전송되어야 함 구현 세부 사항은 Google Play의 네이티브 PC 설치 리퍼러 문서를참조하십시오.	선택 사항 문자열 첫 실행 시에만	`%7B%22install_time_epoch_seconds%22%3A%221568939453%22` `%2C%22install_referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%7D`
`match_id`	웹 클릭과 게임 설치를 결정론적으로 매칭하는 식별자 게임 설치. 요구 사항: 첫 게임 실행 시에만 전송되어야 함 웹 SDK 구현의 값과 일치해야 함 개인 식별 정보(PII)인 경우 SHA-256 해시 처리 필수 구현 세부 사항은 매치 ID어트리뷰션 참조.	선택 사항 문자열 첫 실행 시에만	`matchid_12345`
`ve`	운영 체제 버전.	선택 사항 문자열	`22H2`
`av`	애플리케이션 버전 또는 게임 빌드 식별자.	선택 사항 문자열	`1.1.5.581823a`
`use_ip`	명시적인 `ip` 매개변수 대신 HTTP 요청 헤더에서 IP 주소를 추출합니다. `true` 로 설정된 경우 `ip` 매개변수를 제공하지 마십시오.	선택 사항 부울 기본값: false	`true`
`ua`	장치의 사용자 에이전트 문자열.	선택 사항 문자열	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	사용자를 위해 저장되고 이후 모든 요청에 걸쳐 유지되는 키-값 쌍. 설정된 값을 보내지 않으면 해당 값이 해제됩니다. 이전에 설정된 값을 전송하지 않으면 해당 값이 해제됩니다. 형식: URL 인코딩된 JSON 객체	선택 사항 최대 5개 속성 각 속성 최대 200자 URL 인코딩된 JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	개인정보 보호 규정 준수를 위한 정보 공유에 대한 사용자 동의. 설정된 경우, 이후 모든 요청에서 지속적 유지 및 전달 필수 값: 값: `"limit_data_sharing":false` - 사용자가 동의함 (수락) `"limit_data_sharing":true` - 사용자가 거부함 (동의 거부) 구현 지침은 사용자 개인정보보호 를 참조하십시오.	선택 사항 URL 인코딩된 JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	게임 설치 후 첫 세션을 나타내는 설치 플래그. 재설치 추적 기능을 위해 필수.	선택 사항 부울	`true`
`utime`	UNIX 시간(초)으로 표시된 게임 실행 타임스탬프.	선택 사항 정수 (UNIX 타임스탬프)	`1483228800`
`umilisec`	UNIX 시간으로 게임 실행 타임스탬프 (밀리초).	선택 사항 정수 (UNIX 타임스탬프 ms)	`1483228800000`
`custom_user_id`	시스템의 사용자 지정 사용자 식별자.	선택 사항 문자열	`123456789abcd`

요청 예시

샘플 구현

기본 세션 요청

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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"

매치 ID를 사용한 첫 실행

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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.get(url, params=params)
    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'
})

매치 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.get(url, params=params)
    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}?${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'
});

매치 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}?${params.toString()}`);
    return await response.json();
}

이벤트 알림 엔드포인트

분석, 캠페인 최적화 및 파트너 전달을 위해 게임 내 이벤트를 Singular에 보고합니다.

엔드포인트 사양

메소드	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

목적

이벤트 알림 엔드포인트를 사용하여 모든 원하는 게임 내 이벤트를 실시간에 가깝게 보고하십시오. 이벤트 데이터는 분석, 보고, 파트너 최적화 및 캠페인 성과 측정에 사용됩니다.

이벤트 모범 사례:

표준 이벤트: 자동 파트너 매핑을 위해 Singular 표준 이벤트 이름사용
실시간 보고: 이벤트를 가능한 한 실제 발생 시점과 가까운 시점에 전송
구매 이벤트: 구매 추적 및 ROI 분석을 위한 구매 매개변수 포함

이벤트 매개변수

필수 매개변수

매개변수	설명	제약 조건	예
`a`	API 인증을 위한 고유한 SDK 키. 위치: 대시보드 → 개발자 도구 → SDK 연동 → SDK 키	필수 문자열	`your_org_name_sh868sdjv`
`p`	사용자가 게임을 플레이하는 플랫폼. 지원되는 값: pc, xbox, playstation, nintendo, metaquest	필수 문자열 대소문자 구분	`pc`
`i`	게임 식별자 게임에 고유한 값입니다. 세션 알림 및 웹 SDK 제품 ID에 사용된 값과 일치해야 합니다. 필수	필수 역방향 DNS 표기법 권장 대소문자 구분	`com.singular.game`
`sdid`	Singular 게임 설치를 식별하는 Singular 기기 ID. 세션 알림에 사용된 SDID와 일치해야 합니다.	필수 UUID 형식	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	게임 내 행동 또는 마일스톤을 식별하는 이벤트 이름. 권장: 자동 파트너 연동을 위해 Singular 표준 이벤트 이름사용 .	필수 문자열 최대 32개의 ASCII 문자	`sng_achievement_unlocked`
`os`	운영 체제 또는 게임 시스템. 세션 알림에 사용된 값과 일치해야 함.	필수 사용자 정의 값 지원	`windows`
`install_source`	게임 스토어 또는 배포 방법. 세션 알림에 사용된 값과 일치해야 합니다.	필수 사용자 지정 값 지원	`steam`
`ip`	이벤트 발생 시점의 기기 IP 주소.	필수 IPv4 또는 IPv6 형식 `use_ip=true` 인 경우 필요하지 않음	`172.58.29.235`

선택적 매개변수

매개 변수	설명	제약 조건	예시
`e`	이벤트에 대한 풍부한 정보를 제공하는 사용자 정의 이벤트 속성. 권장: 파트너 호환성을 위해 Singular 표준 속성 이름사용 .	선택 사항 URL 인코딩된 JSON 속성당 최대 500 ASCII 문자	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	이벤트를 구매 이벤트로 표시합니다. 이벤트 이름이 `__iap__` 또는 0이 아닌 `amt` 인 경우 생략 가능.	구매 이벤트에 필수 부울	`true`
`amt`	구매 이벤트의 통화 금액. `cur` 매개변수와 함께 사용합니다.	구매 이벤트에 필수 소수점 숫자	`2.51`
`cur`	구매 이벤트에 대한 ISO-4217 3자리 통화 코드. `amt` 매개변수와 함께 사용합니다. 참고: ISO-4217 통화 코드	구매 이벤트에 필수 ISO-4217 코드	`EUR`
`ve`	운영 체제 버전.	선택 사항 문자열	`22H2`
`av`	애플리케이션 버전 또는 게임 빌드 식별자.	선택 사항 문자열	`1.1.5.581823a`
`use_ip`	HTTP 요청 헤더에서 IP 주소를 추출합니다.	선택 사항 부울 기본값: false	`true`
`ua`	장치의 사용자 에이전트 문자열.	선택 사항 문자열	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	사용자를 위해 저장된 키-값 쌍. 설정된 경우 이후 모든 요청에 걸쳐 유지되어야 함.	선택 사항 최대 5개 속성 각 최대 200자 URL 인코딩된 JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	정보 공유에 대한 사용자 동의. 설정된 경우 이후 모든 요청에 걸쳐 유지되어야 함.	선택 사항 URL 인코딩된 JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	UNIX 시간(초) 단위의 이벤트 타임스탬프.	선택 사항 정수(UNIX 타임스탬프)	`1483228800`
`umilisec`	UNIX 시간(밀리초)으로 표시된 이벤트의 타임스탬프.	선택 사항 정수 (UNIX 타임스탬프 ms)	`1483228800000`
`custom_user_id`	시스템의 사용자 지정 사용자 식별자.	선택 사항 문자열	`123456789abcd`

요청 예제

샘플 구현

표준 이벤트

curl -G "https://s2s.singular.net/api/v1/evt" \
  --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 -G "https://s2s.singular.net/api/v1/evt" \
  --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/v1/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.get(url, params=params)
    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/v1/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.get(url, params=params)
    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/v1/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}?${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/v1/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}?${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 상태 코드를 반환합니다. 반드시 응답 본문의 status 필드를 검증하여 성공(ok) 또는 실패(error)를 판단하십시오.

완전한 응답 코드 문서 및 오류 처리 전략은 S2S 응답 코드 및 오류 처리를 참조하십시오.

PC 및 콘솔 - API 엔드포인트 참조

PC 및 콘솔 API 엔드포인트 참조

세션 알림 엔드포인트

엔드포인트 사양

목적

세션 매개변수

필수 매개변수

선택적 매개변수

요청 예시

샘플 구현

기본 세션 요청

매치 ID를 사용한 첫 실행

기본 세션 요청

매치 ID를 사용한 첫 실행

기본 세션 요청

매치 ID를 사용한 첫 실행

이벤트 알림 엔드포인트

엔드포인트 사양

목적

이벤트 매개변수

필수 매개변수

선택적 매개변수

요청 예제

샘플 구현

표준 이벤트

구매 이벤트

표준 이벤트

구매 이벤트

표준 이벤트

구매 이벤트

응답 처리

응답 형식

추가 자료