PC 및 콘솔 API 엔드포인트 레퍼런스

PC 및 콘솔 서버 대 서버(S2S) 엔드포인트에 대한 완전한 API 레퍼런스로, 세션 추적 및 이벤트 리포팅을 위한 상세한 파라미터 사양과 구현 예제를 제공합니다.

공유 S2S 파라미터: 엔드포인트, 인증, 그리고 공통 요청 파라미터는 S2S Fundamentals 허브 에서 한 번 정의됩니다. 이 레퍼런스는 PC 및 콘솔 관련 세부 사항만 다룹니다.

엔터프라이즈 기능: PC 및 콘솔 게임 어트리뷰션은 엔터프라이즈 기능입니다. 자세히 알아보려면 PC 및 콘솔 게임 어트리뷰션 FAQ 를 읽거나 고객 성공 매니저에게 문의하세요.

연동 가이드: 완전한 구현 지침과 모범 사례는 PC 및 콘솔 S2S 연동 가이드 를 참고하세요.

세션 알림 엔드포인트

설치 어트리뷰션, 리인게이지먼트 추적, 유저 리텐션 분석을 위해 게임 실행 및 세션을 Singular에 리포팅합니다.

엔드포인트 사양

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

목적

세션 알림 엔드포인트를 사용하여 모든 게임 실행(최초 및 반복 세션)을 거의 실시간으로 리포팅합니다. Singular Device ID로 식별되는 설치에 대해 Singular가 수신한 최초 게임 실행은 어트리뷰션 프로세스를 트리거합니다.

어트리뷰션 워크플로우:

최초 세션: 웹 캠페인 클릭과의 매칭을 통해 설치 어트리뷰션을 트리거합니다
후속 세션: 유저 활동, 리텐션, 리인게이지먼트 분석을 위해 추적됩니다
실시간 리포팅: 세션 알림을 실제 게임 실행 시점에 최대한 가깝게 전송합니다

세션 파라미터

필수 파라미터

인증은 공유되는 a 파라미터(SDK Key)를 사용합니다. S2S Fundamentals 허브의 Authentication 을 참고하세요.

파라미터	세부 정보
`p`	`string` 필수. 대소문자를 구분합니다. 유저가 게임을 플레이하는 플랫폼입니다. 지원되는 값: `pc` `xbox` `playstation` `nintendo` `metaquest` 예시: `pc`
`i`	`string` 필수. 대소문자를 구분합니다. 역방향 DNS 표기법을 권장합니다. 게임 고유의 게임 식별자입니다. 중요: 어트리뷰션이 작동하려면 Web SDK Product ID와 정확히 일치해야 합니다. 동일한 게임에 대해서는 모든 플랫폼에서 동일한 값을 사용하세요. 예시: `com.singular.game`
`sdid`	`UUID` 필수. UUID 버전 4 형식을 권장합니다. 고유한 게임 설치 및 유저 활동을 식별하는 Singular Device ID입니다. 생성: 최초 실행 시 게임/서버에서 생성되며, 게임 설치 수명 내내 유지됩니다. 예시: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	`string` 필수. 사용자 정의 값을 지원합니다. 운영 체제 또는 게임 시스템입니다. 플랫폼별 권장 값: PC: windows, linux, macos, steamos Xbox: xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation: playstation_3, playstation_4, playstation_5 Nintendo: nintendo_switch Meta Quest: metaquest, metaquest_2, metaquest_pro 예시: `windows`
`install_source`	`string` 필수. 사용자 정의 값을 지원합니다. 게임 스토어 또는 배포 방식입니다. 권장 값: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` 사용자 정의 값을 지원합니다. 예시: `steam`
`ip`	`string` 필수. IPv4 또는 IPv6 형식입니다. `use_ip=true` 인 경우 필요하지 않습니다. 게임 실행 시점의 디바이스 IP 주소입니다. 대안: 명시적으로 전달하는 대신 `use_ip=true` 를 사용하여 HTTP 요청 헤더에서 IP를 추출할 수 있습니다. S2S Fundamentals 허브의 Network and location 을 참고하세요. 예시: `172.58.29.235`

선택 파라미터

일반 디바이스 속성( ve , ua ), 네트워크 파라미터( use_ip ), 데이터 프라이버시( data_sharing_options ), 크로스 디바이스( custom_user_id )는 모든 S2S 엔드포인트에서 공유됩니다. S2S Fundamentals 허브의 Device parameters , Network and location , Data privacy , Cross-device 를 참고하세요. 아래 파라미터는 PC 및 콘솔 전용입니다.

파라미터	세부 정보
`install_ref`	`string` 선택. 최초 실행 시에만 사용합니다. JSON URL 인코딩된 Google Install Referrer 정보입니다. Google Play Games 스토어를 통해 배포되는 Native PC 게임에 가장 정확한 어트리뷰션을 제공합니다. 요구사항: 전달하려면 Play Games PC SDK 구현이 필요합니다 최초 게임 실행 시에만 전송해야 합니다 구현 세부 사항은 Google Play for Native PC Install Referrer 문서 를 참고하세요. 예시: `%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`	`string` 선택. 최초 실행 시에만 사용합니다. 웹 클릭을 게임 설치에 결정론적으로 매칭하는 어트리뷰션용 식별자입니다. 요구사항: 최초 게임 실행 시에만 전송해야 합니다 Web SDK 구현의 값과 일치해야 합니다 PII인 경우 SHA-256으로 해시 처리해야 합니다 구현 세부 사항은 Match ID Attribution 을 참고하세요. 예시: `matchid_12345`
`av`	`string` 선택. 애플리케이션 버전 또는 게임 빌드 식별자입니다. 예시: `1.1.5.581823a`
`global_properties`	`JSON` 선택. URL 인코딩된 JSON입니다. 최대 5개 속성, 각 최대 200자입니다. 유저에 대해 저장되며 이후 모든 요청에 걸쳐 유지되는 키-값 쌍입니다. 이전에 설정한 값을 전송하지 않으면 해당 값이 해제됩니다. 예시: `%7B%22key1%22%3A%22value1%22%7D`
`install`	`boolean` 선택. 게임 설치 후 첫 세션임을 나타내는 설치 플래그입니다. 재설치 추적 기능에 필요합니다. 예시: `true`
`utime`	`integer` 선택. UNIX 타임스탬프(초)입니다. UNIX 시간으로 표기한 게임 실행 타임스탬프입니다. 예시: `1483228800`
`umilisec`	`integer` 선택. UNIX 타임스탬프(밀리초)입니다. UNIX 시간으로 표기한 게임 실행 타임스탬프입니다. 예시: `1483228800000`

요청 예제

샘플 구현

기본 세션 요청

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"

Match 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'
})

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.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'
});

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

이벤트 알림 엔드포인트

파트너 Conversion API 지원: Singular의 Conversion API 연동을 통해 이러한 이벤트를 광고 네트워크 파트너로 전달하려면, 표준 선택적 이벤트 속성(eventId 및 ehash와 같은 해시된 자사 데이터)을 포함하세요. Conversion API 연동을 위한 표준 이벤트 속성을 참조하세요.

분석, 캠페인 최적화, 파트너 포워딩을 위해 인게임 이벤트를 Singular에 리포팅합니다.

엔드포인트 사양

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

목적

이벤트 알림 엔드포인트를 사용하여 원하는 모든 인게임 이벤트를 거의 실시간으로 리포팅합니다. 이벤트 데이터는 분석, 리포팅, 파트너 최적화, 캠페인 성과 측정에 사용됩니다.

이벤트 모범 사례:

표준 이벤트: 자동 파트너 매핑을 위해 Singular 표준 이벤트 이름 을 사용하세요
실시간 리포팅: 이벤트를 실제 발생 시점에 최대한 가깝게 전송하세요
수익 이벤트: 구매 추적 및 ROI 분석을 위해 수익 파라미터를 포함하세요

이벤트 파라미터

필수 파라미터

인증은 공유되는 a 파라미터(SDK Key)를 사용합니다. S2S Fundamentals 허브의 Authentication 을 참고하세요.

파라미터	세부 정보
`p`	`string` 필수. 대소문자를 구분합니다. 유저가 게임을 플레이하는 플랫폼입니다. 지원되는 값: pc, xbox, playstation, nintendo, metaquest 예시: `pc`
`i`	`string` 필수. 대소문자를 구분합니다. 역방향 DNS 표기법을 권장합니다. 게임 고유의 게임 식별자입니다. 세션 알림 및 Web SDK Product ID에서 사용한 값과 일치해야 합니다. 예시: `com.singular.game`
`sdid`	`UUID` 필수. 고유한 게임 설치를 식별하는 Singular Device ID입니다. 세션 알림에서 사용한 SDID와 일치해야 합니다. 예시: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	`string` 필수. 최대 32 ASCII 문자입니다. 인게임 행동 또는 마일스톤을 식별하는 이벤트 이름입니다. 권장: 자동 파트너 연동을 위해 Singular 표준 이벤트 이름 을 사용하세요. 예시: `sng_achievement_unlocked`
`os`	`string` 필수. 사용자 정의 값을 지원합니다. 운영 체제 또는 게임 시스템입니다. 세션 알림에서 사용한 값과 일치해야 합니다. 예시: `windows`
`install_source`	`string` 필수. 사용자 정의 값을 지원합니다. 게임 스토어 또는 배포 방식입니다. 세션 알림에서 사용한 값과 일치해야 합니다. 예시: `steam`
`ip`	`string` 필수. IPv4 또는 IPv6 형식입니다. `use_ip=true` 인 경우 필요하지 않습니다. 이벤트 시점의 디바이스 IP 주소입니다. 예시: `172.58.29.235`

선택 파라미터

파라미터	세부 정보
`e`	`JSON` 선택. URL 인코딩된 JSON이며, 속성당 최대 500 ASCII 문자입니다. 이벤트에 대한 풍부한 정보를 제공하는 사용자 정의 이벤트 속성입니다. 권장: 파트너 호환성을 위해 Singular 표준 속성 이름 을 사용하세요. 예시: `%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	`boolean` 수익 이벤트에 필수. 이벤트를 수익 이벤트로 표시합니다. 이벤트 이름이 `__iap__` 이거나 0이 아닌 `amt` 가 제공되는 경우 생략할 수 있습니다. 예시: `true`
`amt`	`number` 수익 이벤트에 필수. 수익 이벤트의 통화 금액입니다. `cur` 파라미터와 함께 사용합니다. 예시: `2.51`
`cur`	`string` 수익 이벤트에 필수. 수익 이벤트의 ISO-4217 세 자리 통화 코드입니다. `amt` 파라미터와 함께 사용합니다. 참고: ISO-4217 Currency Codes 예시: `EUR`
`av`	`string` 선택. 애플리케이션 버전 또는 게임 빌드 식별자입니다. 예시: `1.1.5.581823a`
`global_properties`	`JSON` 선택. URL 인코딩된 JSON입니다. 최대 5개 속성, 각 최대 200자입니다. 유저에 대해 저장되는 키-값 쌍입니다. 설정된 경우 이후 모든 요청에 걸쳐 유지되어야 합니다. 예시: `%7B%22key1%22%3A%22value1%22%7D`
`utime`	`integer` 선택. UNIX 타임스탬프(초)입니다. UNIX 시간으로 표기한 이벤트 타임스탬프입니다. 예시: `1483228800`
`umilisec`	`integer` 선택. UNIX 타임스탬프(밀리초)입니다. UNIX 시간으로 표기한 이벤트 타임스탬프입니다. 예시: `1483228800000`

요청 예제

샘플 구현

표준 이벤트

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'
});

응답 처리

두 엔드포인트 모두 성공 또는 오류 판별을 위해 status 필드의 검증이 필요한 일관된 JSON 응답을 반환합니다.

응답 형식

중요: 모든 응답은 HTTP 200 상태 코드를 반환합니다. 성공( ok ) 또는 실패( error ) 여부를 판별하려면 항상 응답 본문의 status 필드를 검증하세요.

전체 응답 코드 문서와 오류 처리 전략은 S2S Response Codes & Error Handling 을 참고하세요.

PC 및 콘솔 - API 엔드포인트 레퍼런스

PC 및 콘솔 API 엔드포인트 레퍼런스

세션 알림 엔드포인트

엔드포인트 사양

목적

세션 파라미터

필수 파라미터

선택 파라미터

요청 예제

샘플 구현

기본 세션 요청

Match ID를 사용한 최초 실행

기본 세션 요청

Match ID를 사용한 최초 실행

기본 세션 요청

Match ID를 사용한 최초 실행

이벤트 알림 엔드포인트

엔드포인트 사양

목적

이벤트 파라미터

필수 파라미터

선택 파라미터

요청 예제

샘플 구현

표준 이벤트

수익 이벤트

표준 이벤트

수익 이벤트

표준 이벤트

수익 이벤트

응답 처리

응답 형식

추가 리소스