PC 및 콘솔 게임 연동 가이드

Singular을 사용하여 PC 및 콘솔 게임 어트리뷰션을 구현하기 위한 종합 가이드로, 데스크톱 및 게이밍 플랫폼 전반에서 정확한 캠페인 측정과 분석을 지원합니다.

개요

연동 옵션

Singular은 PC 및 콘솔 게임 어트리뷰션을 위한 두 가지 방식을 제공합니다. 구현 요구사항과 어트리뷰션 니즈에 가장 적합한 방법을 선택하세요.

어트리뷰션 흐름 비교

PC/콘솔 Singular Links 흐름:

1. 사용자가 Singular Link 클릭: 사용자가 마케팅 캠페인의 Singular 트래킹 링크를 클릭합니다
2. 랜딩 페이지로 리디렉션: 사용자가 랜딩 페이지 또는 스토어로 리디렉션됩니다(Web SDK 불필요)
3. 다운로드 및 설치: 사용자가 게임을 다운로드하고 설치합니다
4. 첫 실행: 사용자가 게임을 처음으로 실행합니다
5. S2S 보고: 게임이 S2S API를 통해 세션을 보고합니다
6. 확률적 어트리뷰션: Singular이 IP 주소를 기반으로 게임 설치를 Singular Link 클릭과 매칭합니다

Web SDK + Match ID 흐름:

1. 사용자가 캠페인 링크 클릭: 사용자가 마케팅 캠페인 광고 또는 링크를 클릭합니다
2. Web SDK가 적용된 랜딩 페이지: 사용자가 Singular Web SDK가 구현된 랜딩 페이지에 도착합니다
3. 클릭 캡처: Web SDK가 클릭 데이터를 캡처하고 Match ID를 생성합니다
4. 사용자 인증(선택 사항): 사용자가 로그인하면 결정적 어트리뷰션을 위해 Match ID를 게임에 전달할 수 있습니다
5. 다운로드 및 설치: 사용자가 게임을 다운로드하고 설치합니다
6. 첫 실행: 사용자가 게임을 실행하고 선택적으로 Match ID를 가져옵니다
7. Match ID를 포함한 S2S 보고: 게임이 Match ID를 포함하거나 포함하지 않고 S2S API를 통해 세션을 보고합니다
8. 어트리뷰션 매칭: Singular이 결정적 매칭(Match ID가 제공된 경우) 또는 확률적 매칭(IP 기반)을 수행합니다

서버 간(Server-to-Server) 연동

선택한 어트리뷰션 방식과 관계없이, 모든 PC 및 콘솔 게임 어트리뷰션에는 S2S API 연동 구현이 필요합니다.

연동 기능:

• 게임 세션 추적: 게임 실행 전반에 걸친 사용자 세션과 활동을 보고합니다
• 설치 어트리뷰션: 신규 게임 설치를 마케팅 캠페인에 어트리뷰션합니다
• 이벤트 분석: 퍼널 분석을 위해 게임 내 이벤트와 사용자 상호작용을 추적합니다
• 매출 측정: 게임 내 구매와 수익화 성과를 측정합니다
• 크로스 플랫폼 지원: PC, Xbox, PlayStation, Nintendo, Meta Quest 전반에 걸친 일원화된 추적

사전 요구사항

PC 및 콘솔 연동을 구현하기 전에 다음 요구사항이 충족되었는지 확인하세요.

문서 리소스

PC 및 콘솔 연동을 위한 전체 API 레퍼런스 및 구현 가이드입니다.

방법 1: PC/콘솔 Singular Links(권장)

랜딩 페이지에 Web SDK를 구현할 필요 없이 Singular 트래킹 링크를 사용하여 확률적 어트리뷰션을 수행하는 간소화된 연동 방식입니다.

개요

작동 방식

PC/콘솔 Singular Links는 클릭 데이터를 트래킹 링크에서 직접 캡처하여 어트리뷰션을 수행하므로, 랜딩 페이지에 Web SDK를 구현할 필요가 없습니다.

주요 이점:

• Web SDK 불필요: 서드파티 스토어(Steam, Epic 등)를 포함한 모든 랜딩 페이지로 사용자를 리디렉션합니다
• 간소화된 연동: 게임 측에서 S2S API 구현만 필요합니다
• 빠른 배포: 랜딩 페이지 수정 없이 캠페인을 신속하게 생성하고 시작합니다
• 유연한 대상: 모든 대상 URL로의 하나의 리디렉션을 지원합니다

어트리뷰션 방식:

• 확률적(IP 기반): Singular이 IP 주소와 기기 특성을 기반으로 게임 설치를 Singular Link 클릭과 매칭합니다

구현 단계

1단계: 사전 요구사항

PC/콘솔 Singular Links를 생성하기 전에 다음 요구사항이 충족되었는지 확인하세요.

2단계: PC/콘솔 Singular Link 생성

Singular 대시보드에서 PC/콘솔 Singular Links를 생성하여 캠페인 클릭을 추적하고 어트리뷰션을 수행하세요.

설정 단계:

1. Manage Links로 이동: Singular 대시보드에서 Attribution → Manage Links로 이동합니다
2. App 선택: PC/콘솔 앱 사이트가 설정된 App을 선택합니다
3. 새 링크 생성: Create New Link 버튼을 클릭합니다
4. 플랫폼 유형 선택: Platform Tracking Type 필드에서 "PC/Console"을 선택합니다
5. 대상 설정: 특정 PC/콘솔 앱 사이트를 선택하거나 "Track all app sites under this app" 옵션을 선택합니다
6. 대상 URL 설정: 리디렉션 URL(랜딩 페이지, 스토어 페이지 등)을 설정합니다
7. 어트리뷰션 설정 구성: 필요에 따라 어트리뷰션 윈도우와 트래킹 파라미터를 설정합니다
8. 링크 생성: Singular 트래킹 링크를 저장하고 생성합니다

3단계: S2S 연동 구현

게임 세션과 이벤트를 보고하기 위해 서버 간(Server-to-Server) API 연동을 구현하세요. 전체 S2S 구현 세부 사항은 아래 연동 개념 섹션을 참고하세요.

필수 구현:

• 세션 알림: Session Notification Endpoint를 사용하여 게임 실행을 보고합니다
• 이벤트 추적: Event Notification Endpoint를 사용하여 게임 내 이벤트와 매출을 보고합니다
• 기기 식별: 고유한 기기 식별자(SDID)를 생성하고 유지합니다

4단계: 캠페인 시작

생성한 PC/콘솔 Singular Links를 마케팅 캠페인에 사용하여 어트리뷰션 추적을 수행하세요.

캠페인 설정:

• 트래킹 링크 복사: Manage Links에서 생성된 Singular Link를 복사합니다
• 캠페인 설정: Singular Link를 캠페인 대상 URL로 사용합니다
• 캠페인 시작: Singular Link로 캠페인을 활성화합니다
• 어트리뷰션 모니터링: 사용자가 링크를 클릭하고 게임을 실행함에 따라 Singular 리포트에서 어트리뷰션 데이터를 확인합니다

어트리뷰션 매칭

어트리뷰션 작동 방식

PC/콘솔 Singular Links를 사용하는 경우, Singular은 IP 주소와 타이밍을 기반으로 확률적 어트리뷰션 매칭을 수행합니다.

어트리뷰션 프로세스:

1. 사용자가 Singular Link 클릭: IP 주소와 타임스탬프를 포함한 클릭 데이터가 Singular에 의해 캡처됩니다
2. 사용자가 게임 다운로드: 사용자가 게임을 다운로드하고 설치합니다
3. 게임 실행: 사용자가 게임을 처음으로 실행합니다
4. S2S 보고: 게임이 사용자 IP 주소를 포함하여 S2S API를 통해 Singular에 세션을 보고합니다
5. 확률적 매칭: Singular이 어트리뷰션 윈도우 내에서 IP 주소를 기반으로 게임 설치를 Singular Link 클릭과 매칭합니다
6. 어트리뷰션 완료: 설치가 캠페인 소스에 어트리뷰션됩니다

방법 2: Web SDK + Match ID(고급)

사용자가 인증하는 경우 결정적 어트리뷰션을 위해 랜딩 페이지에서 Singular Web SDK와 선택적 Match ID를 사용하는 고급 연동 방식입니다.

개요

이 방법을 사용해야 하는 경우

기본적인 확률적 매칭을 넘어서는 강화된 어트리뷰션 기능이 필요한 경우 Web SDK + Match ID 방식을 구현하세요.

사용 사례:

• Web Attribution: Singular Web Attribution 기능과 웹 분석이 필요한 경우
• 결정적 어트리뷰션: 사용자가 랜딩 페이지에서 인증하며 가장 높은 어트리뷰션 정확도를 원하는 경우
• 크로스 디바이스 추적: 사용자가 랜딩 페이지를 방문한 기기와 다른 기기에서 게임을 다운로드할 수 있는 경우
• 고급 분석: 게임 설치 전 상세한 웹 참여 지표가 필요한 경우

어트리뷰션 방식:

• 확률적(IP 기반): IP 주소를 기반으로 한 자동 매칭(PC/콘솔 Singular Links와 동일)
• 결정적(Match ID): 사용자가 인증할 때 랜딩 페이지에서 게임으로 전달된 고유 식별자를 사용한 정밀 매칭

구현 단계

1단계: Web SDK 구현

클릭 데이터를 캡처하고 어트리뷰션을 수행하기 위해 마케팅 랜딩 페이지에 Singular Web SDK를 구현하세요.

Web SDK 구현:

• Web SDK 가이드 참고: Web SDK 개요 및 시작하기
• Product ID 설정: Web SDK Product ID는 S2S 연동에서 사용하는 게임 식별자( i 파라미터)와 일치해야 합니다
• 랜딩 페이지 배포: 모든 마케팅 랜딩 페이지에 Web SDK를 배포합니다

2단계: S2S 연동 구현

게임 세션과 이벤트를 보고하기 위해 서버 간(Server-to-Server) API 연동을 구현하세요. 전체 S2S 구현 세부 사항은 아래 연동 개념 섹션을 참고하세요.

필수 구현:

• 세션 알림: Session Notification Endpoint를 사용하여 게임 실행을 보고합니다
• 이벤트 추적: Event Notification Endpoint를 사용하여 게임 내 이벤트와 매출을 보고합니다
• 기기 식별: 고유한 기기 식별자(SDID)를 생성하고 유지합니다

3단계: Match ID 구현(선택 사항)

결정적 어트리뷰션을 위해, 사용자가 인증할 때 랜딩 페이지에서 게임으로 고유 식별자를 전달하도록 Match ID를 구현하세요.

Match ID 구현:

• Match ID 가져오기: 사용자 인증 후 Web SDK getMatchID() 메서드를 사용합니다
• 게임으로 전달: Match ID를 웹에서 게임으로 전달하는 메커니즘(쿼리 파라미터, API 등)을 구현합니다
• 첫 세션에 포함: match_id 파라미터를 통해 첫 게임 세션에 Match ID를 보고합니다

자세한 Match ID 연동 단계는 아래 Match ID 구현 섹션을 참고하세요.

어트리뷰션 매칭

어트리뷰션 작동 방식

Web SDK를 사용하는 경우, Singular은 Match ID 제공 여부에 따라 확률적 또는 결정적 방식으로 어트리뷰션 매칭을 수행합니다.

확률적 어트리뷰션(Match ID 없음):

1. 사용자가 캠페인 클릭: 사용자가 마케팅 캠페인 링크를 클릭합니다
2. 랜딩 페이지 방문: Web SDK가 IP 주소를 포함한 클릭 데이터를 캡처합니다
3. 사용자가 게임 다운로드: 사용자가 게임을 다운로드하고 설치합니다
4. 게임 실행: 사용자가 게임을 처음으로 실행합니다
5. S2S 보고: 게임이 S2S API를 통해 Singular에 세션을 보고합니다
6. IP 매칭: Singular이 IP 주소를 기반으로 게임 설치를 웹 클릭과 매칭합니다

결정적 어트리뷰션(Match ID 사용):

1. 사용자가 캠페인 클릭: 사용자가 마케팅 캠페인 링크를 클릭합니다
2. 랜딩 페이지 방문: Web SDK가 고유한 Match ID를 생성합니다
3. 사용자 인증: 사용자가 랜딩 페이지에서 로그인합니다
4. Match ID 가져오기: 구현 측에서 Web SDK로부터 Match ID를 가져옵니다
5. Match ID를 게임으로 전달: Match ID가 쿼리 파라미터, API 또는 기타 메커니즘을 통해 게임으로 전달됩니다
6. 사용자가 게임 다운로드: 사용자가 게임을 다운로드하고 설치합니다
7. Match ID를 포함한 게임 실행: 사용자가 게임을 실행하고 저장된 Match ID를 가져옵니다
8. Match ID를 포함한 S2S 보고: 게임이 match_id 파라미터를 포함하여 첫 세션을 보고합니다
9. 결정적 매칭: Singular이 Match ID를 사용하여 게임 설치를 웹 클릭과 매칭해 정밀한 어트리뷰션을 수행합니다

연동 개념

Singular과의 PC 및 콘솔 S2S 연동을 구현하기 위한 핵심 개념과 요구사항입니다. 이 개념들은 두 어트리뷰션 방법 모두에 적용됩니다.

인증

Singular의 PC 및 콘솔 S2S API에 대한 모든 요청에는 a 파라미터에 SDK key 인증이 필요합니다. 공유되는 인증 방식(SDK Key를 어디서 찾고 어떻게 전달하는지)에 대해서는 S2S Fundamentals의 Authentication 을 참고하세요.

사용자 개인정보 보호

Singular은 최종 사용자에게 트래킹에 대한 옵트인 또는 옵트아웃 기능을 제공할 것을 권장합니다. 공유되는 개인정보 보호 파라미터( data_sharing_options 및 Limit Data Sharing 포함)에 대해서는 S2S Fundamentals의 Privacy parameters 를 참고하세요.

지원 플랫폼

플랫폼 정의

플랫폼은 사용자가 게임을 플레이하는 위치를 나타내며 모든 S2S API 요청의 p 파라미터에 전달되어야 합니다.

지원되는 플랫폼 값:

• pc - 개인용 컴퓨터 플랫폼
• xbox - Microsoft Xbox 게이밍 콘솔
• playstation - Sony PlayStation 게이밍 콘솔
• nintendo - Nintendo 게이밍 콘솔
• metaquest - Meta Quest VR 헤드셋

운영 체제 및 스토어

플랫폼 외에도 os 파라미터를 통해 운영/게임 시스템을, install_source 파라미터를 통해 배포 스토어를 지정하세요.

게임 식별자

애플리케이션 식별

게임 식별자는 게임 이벤트를 특정 게임과 연결하며 모든 요청의 i 파라미터에 전달되어야 합니다.

식별자 요구사항:

• 형식: 모든 값이 지원되지만, Singular은 역방향 DNS 표기법을 권장합니다(예: com.singular.game )
• 크로스 플랫폼 일관성: 지원되는 모든 플랫폼에서 동일한 게임에는 동일한 게임 식별자를 사용해야 합니다
• Web SDK 정렬(방법 2에만 해당): Web SDK + Match ID 방법을 사용하는 경우, 어트리뷰션이 작동하려면 게임 식별자가 랜딩 페이지에 설정된 Web SDK Product ID와 일치해야 합니다

설정 예시:

const config = {
  apiKey: 'YOUR_SDK_KEY',
  productId: 'com.singular.game',  // Must match S2S identifier
  // ... other config
};

p=pc&i=com.singular.game

p=xbox&i=com.singular.game

p=playstation&i=com.singular.game

기기 식별

고유 게임 설치 추적

설치/기기 식별자는 동일한 게임 설치의 여러 게임 세션 전반에 걸쳐 게임 이벤트를 연결하며 모든 요청의 sdid 파라미터에 전달되어야 합니다.

식별자 사양:

• 형식: UUID Version 4 형식 권장
• 생성: 게임의 첫 실행(설치) 시 게임/서버에서 값이 생성됩니다
• 지속성: 게임 설치의 수명 전체에 걸쳐 유지되어야 합니다
• 고유성: 각 게임 설치마다 고유한 식별자가 필요합니다

예시: sdid=40009df0-d618-4d81-9da1-cbb3337b8dec

Match ID 구현

Match ID는 Web SDK에서 게임 설치로 고유 식별자를 전달하여 웹 캠페인에 대한 결정적 어트리뷰션을 수행합니다. 이 기능은 Web SDK + Match ID 어트리뷰션 방법을 사용하는 경우에만 사용할 수 있습니다.

Match ID 작동 방식:

1. Web SDK가 Match ID 생성: 사용자가 랜딩 페이지를 방문할 때 Singular Web SDK 가 고유한 Match ID를 생성합니다
2. Match ID 가져오기: 사용자 인증 후 Web SDK 메서드를 사용하여 랜딩 페이지에서 Match ID를 가져옵니다
3. 게임으로 전달: 구현 측에서 다운로드/설치 과정 중에 Match ID를 웹 페이지에서 게임으로 전달합니다(예: 쿼리 파라미터, 딥링크, 쿠키)
4. 첫 실행과 함께 보고: 게임이 match_id 파라미터를 통해 첫 세션 알림에 Match ID를 포함하여 Singular에 보고합니다
5. 결정적 매칭: Singular이 Match ID를 사용하여 정밀한 어트리뷰션 매칭을 수행합니다

Web SDK Match ID 메서드

네이티브 구현

Singular Web SDK는 랜딩 페이지에서 Match ID 값을 가져오고, 설정하고, 초기화하기 위한 네이티브 메서드를 제공합니다.

사용 가능한 메서드:

구현 예시

// Get the Singular-generated Match ID
const matchId = window.singularSdk.getMatchID();
console.log('Match ID:', matchId);

// Store Match ID for passing to game
localStorage.setItem('singular_match_id', matchId);

// Set your own Match ID value
const customMatchId = 'your-custom-match-id-123';
window.singularSdk.setMatchID(customMatchId);

console.log('Custom Match ID set:', customMatchId);

// Clear custom Match ID and revert to default
window.singularSdk.clearMatchID();

// Get the new default Match ID
const defaultMatchId = window.singularSdk.getMatchID();
console.log('Default Match ID restored:', defaultMatchId);

// Initialize Web SDK
const config = new SingularConfig(sdkKey, sdkSecret, productId)
  .withInitFinishedCallback(() => {
    console.log('Singular SDK initialized');
  });

singularSdk.init(config);

// Handle download button click
document.getElementById('download-button').addEventListener('click', function() {
  // Get Match ID before redirecting to download
  const matchId = window.singularSdk.getMatchID();

  // Pass Match ID to download page via query parameter
  const downloadUrl = `https://example.com/download?match_id=${matchId}`;

  // Redirect to download page
  window.location.href = downloadUrl;
});

Match ID를 게임으로 전달

구현 전략

Web SDK에서 Match ID를 가져온 후, 랜딩 페이지에서 게임 설치로 값을 전달하는 메커니즘을 구현하세요.

일반적인 방식:

https://example.com/download?match_id=abc123

document.cookie = `match_id=${matchId}; path=/; max-age=86400`;

localStorage.setItem('singular_match_id', matchId);

mygame://install?match_id=abc123

S2S API 구현

Match ID 보고

게임이 웹 구현으로부터 Match ID를 가져오면, 어트리뷰션 매칭을 위해 이를 첫 세션 알림에 포함하여 Singular에 보고하세요.

Match ID를 포함한 세션 요청:

import requests

def report_first_session_with_match_id(sdk_key, game_id, device_id, platform, match_id):
    """
    Report first game session with Match ID for attribution
    """
    session_url = "https://s2s.singular.net/api/v1/launch"

    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': 'windows',
        'install_source': 'steam',
        'ip': get_user_ip(),
        'match_id': match_id  # Include Match ID for attribution
    }

    response = requests.get(session_url, params=params)
    return response.json()

# Example: First launch with Match ID
report_first_session_with_match_id(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    match_id='abc123def456'  # Retrieved from landing page
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --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"

async function reportFirstSessionWithMatchId(config) {
    const sessionUrl = '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': await getUserIP(),
        'match_id': config.matchId  // Include Match ID
    });

    const response = await fetch(`${sessionUrl}?${params.toString()}`);
    return await response.json();
}

// Example: First launch with Match ID
reportFirstSessionWithMatchId({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    matchId: 'abc123def456'  // Retrieved from landing page
});

Match ID 모범 사례

구현 체크리스트

전체 어트리뷰션 방법론 세부 사항과 문제 해결은 PC 및 콘솔 게임 어트리뷰션 FAQ 를 참고하세요.

게임 세션 추적

Singular에 게임 세션을 보고하는 것은 PC 및 콘솔 연동에서 필수이며, 설치 어트리뷰션, 리인게이지먼트 추적, 사용자 리텐션 분석을 가능하게 합니다.

Session Notification Endpoint

구현 요구사항

게임이 실행될 때마다 Session Notification Endpoint를 호출하여 Singular에 게임 세션을 알리세요.

세션 처리

어트리뷰션 워크플로우

세션 알림을 통해 Singular은 세션 컨텍스트에 따라 여러 어트리뷰션 및 분석 기능을 수행할 수 있습니다.

처리 로직:

• 첫 세션(설치): 고유 설치 이후 첫 게임 세션인 경우, Singular은 신규 설치를 인식하고 설치 어트리뷰션 프로세스를 트리거합니다
• 리인게이지먼트 세션: 세션이 리인게이지먼트(출시 예정)에 해당하는 경우, Singular은 리인게이지먼트 어트리뷰션 프로세스를 트리거합니다( Re-engagement FAQ 참고)
• 일반 세션: 그 외의 경우, 사용자 활동 및 리텐션 추적을 위한 게임 세션으로 표시됩니다

구현 모범 사례

비동기 데이터 수집

게임 세션을 보고하기 위한 데이터를 수집할 때, 세션 알림을 전송하기 전에 비동기 함수가 반환될 때까지 기다리고 다양한 기능을 처리하세요.

세션 요청 예시

샘플 구현

import requests

def report_game_session(sdk_key, game_id, device_id, platform, os_version, store):
    """
    Report game session to Singular
    """
    session_url = "https://s2s.singular.net/api/v1/launch"

    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': os_version,
        'install_source': store,
        'ip': get_user_ip()
    }

    try:
        response = requests.get(session_url, params=params, timeout=10)

        if response.status_code == 200:
            data = response.json()
            if data.get('status') == 'ok':
                print("Session reported successfully")
                return True
            else:
                print(f"Session error: {data.get('reason')}")
                return False
        else:
            print(f"HTTP error: {response.status_code}")
            return False

    except Exception as e:
        print(f"Exception reporting session: {e}")
        return False

# Example usage
report_game_session(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    os_version='windows',
    store='steam'
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

async function reportGameSession(config) {
    const sessionUrl = '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': await getUserIP()
    });

    try {
        const response = await fetch(`${sessionUrl}?${params.toString()}`);
        const data = await response.json();

        if (data.status === 'ok') {
            console.log('Session reported successfully');
            return true;
        } else {
            console.error('Session error:', data.reason);
            return false;
        }
    } catch (error) {
        console.error('Exception reporting session:', error);
        return false;
    }
}

// Example usage
reportGameSession({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam'
});

게임 내 이벤트 추적

게임 내 이벤트와 사용자 상호작용을 추적하여 마케팅 캠페인 성과를 분석하고, 사용자 퍼널을 최적화하며, 플레이어 여정 전반의 참여를 측정하세요.

이벤트 계획

이벤트 정의

S2S 연동을 구현하기 전에, 캠페인 분석과 사용자 행동 측정을 위해 조직에서 추적하려는 이벤트를 정의하세요.

이벤트 계획 가이드: 게임 내 이벤트 정의하기

Event Notification Endpoint

이벤트 보고

게임에서 이벤트가 발생하면 Event Notification Endpoint를 호출하여 어트리뷰션 분석 및 캠페인 최적화를 위해 Singular에 알리세요.

API 호출에 포함된 이벤트 이름은 Singular 리포트, 익스포트, 포스트백에서 이벤트가 식별되는 방식을 결정합니다.

이벤트 명명 모범 사례

표준 이벤트

Singular은 간소화된 파트너 연동과 분석 호환성을 위해 표준 이벤트 및 속성 명명 규칙을 사용할 것을 권장합니다.

매출 이벤트 추적

매출 측정

게임 내 구매로부터 매출을 추적하여 캠페인 성과와 ROI를 분석하세요. 데이터는 리포트, 로그 익스포트, 포스트백에서 확인할 수 있습니다.

매출 이벤트 구현: 매출 이벤트를 지정하려면 추가 매출 파라미터와 함께 Event Notification Endpoint를 사용하세요.

필수 매출 파라미터:

• is_revenue_event=true - 이벤트를 매출 이벤트로 표시합니다(이벤트 이름이 __iap__ 이거나 금액이 0보다 큰 경우 선택 사항)
• amt=1.99 - 매출 금액
• cur=USD - ISO 4217 통화 코드

이벤트 요청 예시

샘플 구현

import requests

def report_game_event(sdk_key, game_id, device_id, platform, event_name, event_attributes=None):
    """
    Report in-game event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"

    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': event_name,
        'ip': get_user_ip()
    }

    if event_attributes:
        import json
        params['e'] = json.dumps(event_attributes)

    response = requests.get(event_url, params=params)
    return response.json()

# Example: Level complete event
report_game_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    event_name='sng_level_achieved',
    event_attributes={
        'level': '5',
        'score': '1250'
    }
)

def report_revenue_event(sdk_key, game_id, device_id, platform, amount, currency):
    """
    Report revenue event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"

    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': amount,
        'cur': currency,
        'ip': get_user_ip()
    }

    response = requests.get(event_url, params=params)
    return response.json()

# Example: $9.99 purchase
report_revenue_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    amount=9.99,
    currency='USD'
)

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"level":"5","score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --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"

async function reportGameEvent(config) {
    const eventUrl = 'https://s2s.singular.net/api/v1/evt';

    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'n': config.eventName,
        'ip': await getUserIP()
    });

    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }

    const response = await fetch(`${eventUrl}?${params.toString()}`);
    return await response.json();
}

// Example: Level complete
reportGameEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    eventName: 'sng_level_achieved',
    attributes: {
        level: '5',
        score: '1250'
    }
});

async function reportRevenueEvent(config) {
    const eventUrl = 'https://s2s.singular.net/api/v1/evt';

    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': await getUserIP()
    });

    const response = await fetch(`${eventUrl}?${params.toString()}`);
    return await response.json();
}

// Example: $9.99 purchase
reportRevenueEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    amount: 9.99,
    currency: 'USD'
});

다음 단계

추가 리소스와 지원을 통해 PC 및 콘솔 연동을 완료하세요.

추가 리소스

문서 및 지원

• API 레퍼런스: PC 및 콘솔 S2S 엔드포인트 레퍼런스
• 어트리뷰션 FAQ: PC 및 콘솔 게임 어트리뷰션 FAQ
• Web SDK(선택 사항): Web SDK 개요 및 시작하기
• 이벤트 계획: 게임 내 이벤트 정의하기
• 표준 이벤트: Singular 표준 이벤트 레퍼런스
• 응답 코드: S2S 응답 코드 및 오류 처리

지원 채널

도움 받기

구현 지원과 기술 지원을 받으려면 Singular 팀에 문의하세요.

• Solution Engineer: 고급 기능 및 연동 계획에 대해서는 Singular Solution Engineer와 상담하세요
• 고객 성공 매니저: 엔터프라이즈 기능 활성화 및 계정 설정에 대해서는 CSM에게 문의하세요
• 지원팀: 기술적 문제 및 문제 해결 지원을 위해 지원 티켓을 제출하세요