PC 및 콘솔 게임 통합 안내서

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

싱귤러는 분석 및 어트리뷰션을 위해 모든 PC 및 콘솔 게임 전환 데이터를 싱귤러에 보고하는 데 사용할 수 있는 REST API를 제공합니다.

이 가이드는 싱귤러와 PC 및 콘솔 S2S 연동을 구축하고 다양한 옵션 기능을 구현하는 방법을 설명합니다.

연동 개념

이 섹션에서는 완벽한 PC 및 콘솔 S2S 연동을 구현하는 데 중요한 주요 개념을 자세히 설명합니다.

S2S API 엔드포인트, 해당 매개변수 및 샘플 호출의 전체 목록은 PC 및 콘솔 S2S 엔드포인트 레퍼런스를 참조하세요.

사용자 개인정보 보호

사용자 개인정보를 보호하기 위해, 싱귤러는 게임 개발자가 최종 사용자가 게임 이벤트 데이터를 싱귤러로 전송하는 것을 옵트인 또는 옵트아웃할 수 있는 옵션을 제공할 것을 권장합니다.

인증

싱귤러의 PC 및 콘솔 S2S API에 대한 모든 요청은 "a=" 매개변수에 SDK 키를 전송해야 합니다. 싱귤러 SDK 키는 싱귤러 대시보드의 "개발자 도구 -> SDK 통합 -> SDK 키"에서 찾을 수 있습니다.

경고: "개발자 도구 -> API 키"에 있는 싱귤러 "API 키"를 사용하지 마세요. "API 키"는 싱귤러 리포팅 API 호출시에만 사용됩니다.

지원 플랫폼, 게임 시스템 및 스토어

싱귤러에서 "플랫폼"은 사용자가 게임을 플레이하는 "플랫폼"으로 정의되며, 모든 S2S API 요청에"p=" 매개변수로 전달되어야 합니다. 지원되는 "플랫폼" 값의 비공개 목록은 아래와 같습니다:

  • pc
  • xbox
  • playstation
  • nintendo
  • metaquest

"플랫폼" 외에도 "운영 체제/게임 시스템" 및 "스토어"는 각각"os=" 및"install_source=" 매개변수에 전달해야 합니다. 사용자 지정 값도 지원되지만 플랫폼별로 다음 값을 권장합니다:

플랫폼
(p=
)
운영/게임 시스템
(os=)
스토어
(install_source=
)
pc
windows
linux
macos
steamos
steam
epicgamestore
microsoftstore
gog
humblestore
selfdistributed
xbox xbox_one
xbox_360
xbox_series_s
xbox_series_x
xbox
playstation playstation_3
playstation_4
playstation_5
playstation
nintendo nintendo_switch nintendo
metaquest metaquest
metaquest_2
metaquest_pro
metaquest

게임 식별자

싱귤러가 게임 이벤트를 게임과 연결하려면 모든 요청에서"i=" 매개변수에 게임 식별자(=번들ID)를 전달해야 합니다.

  • 모든 값을 지원할 수 있지만, 싱귤러는 역 DNS 표기법(예: com.singular.game)으로 값을 전달할 것을 권장합니다.
  • 게임이 여러 플랫폼에서 제공되는 경우, 지원되는 모든 플랫폼에서 동일한 게임에 동일한 게임 식별자를 사용해야 합니다(예: p=pc&i=com.singular.game, p=xbox&i=com.singular.game, p=playstation&i=com.singular.game).
  • 싱귤러가 웹사이트 랜딩 페이지를 통해 발생한 웹 캠페인의 게임 전환을 어트리뷰션하려면, 싱귤러 웹 SDK 연동시 적용된 'Product ID'와 PC/Console의 게임 식별자 값과도 일치해야 합니다.

고유한 게임 인스톨 식별

싱귤러가 동일한 게임 인스톨에 대해 여러 게임 세션에 걸쳐 게임 이벤트를 연결하려면, 모든 요청에 대해 설치/기기 식별자를"sdid=" 파라미터에 전달해야 합니다.

  • 권장 UUID(버전 4) 형식
  • 첫 게임 실행(설치) 시 게임/서버에서 생성된 값이어야 합니다.

Match ID (선택 사항)

게임의 웹 캠페인이 사용자를 웹 랜딩 페이지로 유도하고 웹사이트 -> PC/콘솔 게임 어트리뷰션에 "match ID"를 활용할 수 있는 경우, 어트리뷰션 정확도를 높이기 위해 "match_id=" 파라미터에 "match ID"를 선택적으로 전달할 수 있습니다. PC 및 콘솔 어트리뷰션에 대한 자세한 내용은 해당 주제에 대한 FAQ를 참조하세요.

  • 인스톨 어트리뷰션이 "매치 ID"를 사용하려면 사용자가 게임을 처음 실행할 때 전달되어야 합니다.
  • "Match ID"는 싱귤러 웹 SDK에서 생성된 MatchID와 일치해야 합니다.
  • "Match ID"가 PII인 경우, 해시(SHA-256)되어야 합니다.

중요: 어트리뷰션에 Match ID를 활용하는 것은 고급 기능에 해당합니다. 구현하기 전에 싱귤러 솔루션 엔지니어와 상담하세요.

게임 세션 트래킹

PC 및 콘솔 연동에서는 모든 게임 세션을 싱귤러에 보고해야 하며, 게임이 실행될 때마다 게임 세션이 전송될 것으로 예상합니다.

싱귤러에 게임 세션실행을 알리려면 세션 알림 엔드포인트를 호출하세요.

세션 알림을 통해 싱귤러는 여러 가지 작업을 수행할 수 있습니다:

  • 고유 인스톨 후 첫 번째 게임 세션인 경우( 고유 게임 인스톨 식별하기 참조), 싱귤러는 새 인스톨을 인식하고 인스톨 어트리뷰션 프로세스를 트리거합니다.
  • (출시 예정) 게임 세션이 리인게이지먼트 세션에 해당하는 경우, 싱귤러는 리인게이지먼트 어트리뷰션 프로세스를 트리거합니다( 리인게이지먼트 FAQ에서 자세히 알아보기).
  • 그렇지 않으면, 싱귤러는 이를 게임 세션으로 표시하여 사용자 활동과 리텐션을 추적하는 데 사용합니다.

팁: 게임 세션을 보고하기 위해 데이터를 수집할 때는 비동기 함수가 반환되어 다양한 기능을 처리할 때까지 기다려야 합니다. 예를 들면 다음과 같습니다:

  • 어트리뷰션 매칭을 개선하기 위해 Match ID를 사용하는 경우, Match ID를 사용할 수 있을 때만 첫 번째 게임 세션을 보고하는 것이 중요합니다. Match ID 안내를 참조하십시오.
  • 게임에서 싱귤러의 마케팅 및 게임 분석에 옵트인할 수 있는 방법을 제공하는 경우, 게임 세션을 보고하기 전에 동의를 수집할 때까지 기다리는 것이 중요합니다. 사용자 개인정보 보호 안내를 참조하세요.

인앱 이벤트 트래킹

이벤트

싱귤러는 마케팅 캠페인의 성과를 분석하기 위해 게임 내 이벤트에 대한 데이터를 수집할 수 있습니다. 이벤트에는 로그인 및 등록부터 게임 내 레벨업에 이르는 모든 사용자 상호 작용이 포함될 수 있습니다.

싱귤러와 S2S 통합을 구현하기 전에 조직에서 추적하려는 이벤트 목록이 있어야 합니다( 인게임 이벤트 정의 참조).

게임에서 이벤트가 발생하면 Singular에 알리려면 이벤트 알림 엔드포인트를 호출하세요. 호출에 포함하는 이벤트 이름은 Singular 보고서, 내보내기 및 포스트백에서 이벤트가 식별되는 방식입니다.

참고:

  • 싱귤러는 싱귤러 표준 이벤트 및 속성 명명 규칙을 사용하여 이벤트를 전달할 것을 권장합니다. 표준 이벤트를 사용하면 통합시 파트너 표준 이벤트와의 매핑 및 호환성을 간소화할 수 있습니다.
  • 사용하려는 타사 파트너 및 분석 솔루션과의 호환성을 위해 사용자 지정 이벤트 이름과 속성을 영어로 전달할 것을 권장합니다.
  • 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
  • 이벤트 속성 및 값은 500자로 제한됩니다.

수익

싱귤러는 게임을 통해 얻은 수익에 대한 데이터를 수집하여 캠페인의 성과와 ROI를 분석하는 데 도움을 줄 수 있습니다. 싱귤러는 보고서, 로그 내보내기 및 포스트백에서 데이터를 사용할 수 있도록 합니다.

수익 이벤트를 추적하려면 모든 이벤트에 사용하는 것과 동일한 이벤트 알림 엔드포인트를 사용하되, 다음 정보를 추가하세요:

  • is_revenue_event=true: 이벤트를 수익 이벤트로 표시합니다. 이벤트 이름이"__iap__"이거나 금액이 0보다 큰 경우 이 매개 변수를 건너뛸 수 있습니다.
  • 수익 금액 (예:"amt=1.99").
  • 통화 (ISO 4217 통화 코드 사용(예:"cur=USD")).