--- url: /api-sdk/sdk/tiara-web.md description: Tiara Web SDK로 게임 로그(Pageview, Event 등)를 수집·전송하는 방법 --- # Tiara Web SDK Tiara Web SDK를 직접 연동해 게임 로그를 수집·전송하는 방법입니다. ::: info 신규 연동이라면 게임플레이 JS SDK를 사용하는 게임은 SDK의 로그 적용 방식을 따르므로 Tiara Web SDK를 별도로 설치하지 않습니다. 이 문서는 **게임플레이 JS SDK를 사용하지 않는 게임에서 Tiara Web SDK를 직접 연동하는 방식**을 안내합니다. 두 방식을 동시에 구성하는 것은 권장하지 않습니다. 자세한 내용은 [SDK 연동 방식 선택](/api-sdk/sdk/)을 참고하세요. ::: 게임플레이 JS SDK를 적용하지 않은 게임은 이 가이드와 [게임 로그 설정](/api-sdk/sdk/tiara-game-logs)에 따라 Tiara Web SDK를 설치하고 필수 게임 로그를 구현하세요. ::: info 게임플레이 JS SDK 를 쓰는 게임 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)가 이 문서의 수집·전송을 대신 처리합니다. `init()` 에 넘긴 `gameCode` 와 `appId` 가 그때 쓰입니다. **이 문서대로 직접 연동할 필요가 없습니다** — 자세한 내용은 [전체 메서드: 게임 로그](/api-sdk/sdk/gameplay-js/reference#게임-로그)을 참고하세요. ::: ## 개요 ### 주요 수집 내용 * **Pageview (화면 조회)**: 사용자가 특정 페이지(화면)에 방문했음을 기록합니다. * **Event (사용자 행동)**: 클릭 등 Pageview를 제외한 사용자 행동을 기록합니다. * **ViewableImpression (콘텐츠 노출)**: 게임 종료 팝업 등 특정 영역이 사용자에게 실제로 노출됐음을 기록합니다. * **Usage (체류시간)**: 페이지 체류시간을 기록합니다. ### 주요 용어 | 용어 | 설명 | 예시 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | 액션 | Tiara Web SDK가 수집하는 게임 로그 단위(Action). Pageview·Event·ViewableImpression·Usage 네 가지 타입으로 나뉩니다 | Pageview, Event, ViewableImpression, Usage | | 서비스 도메인 | 데이터를 수집할 서비스 고유 식별자. 게임플레이 파트너사는 카카오에서 제공하는 도메인을 사용합니다 | gameplay.kakao.com | | 페이지 | 화면을 구분하는 이름. 게임플레이 파트너사는 고정값을 사용합니다. 모든 액션은 페이지 정보를 기본으로 합니다 | SDK게임 | | 섹션 | 페이지들을 그룹핑하는 상위 카테고리. 게임플레이 파트너사는 게임 코드 기준 고정값을 사용합니다 | SDK\_{게임ID} | | 액션명 | 발생한 행동을 설명하는 이름. 게임플레이 필수 게임 로그는 게임 로그 정의 표의 Name 값을 그대로 사용합니다 | Event: 게임\_더보기\_클릭Pageview: SDK\_게임\_조회 | ### ActionType 사용자의 행동을 구분하는 가장 큰 단위입니다. 단위에 따라 사용하는 SDK 함수가 다릅니다. | Action Type | 설명 | SDK 함수 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | | Pageview | 사용자가 하나의 화면을 볼 때 사용합니다. 팝업이나 메뉴 레이어에는 사용하지 않습니다 | `trackPage('액션명')` | | Event | 사용자가 직접 행동을 취한 경우 사용합니다. 대표적으로 클릭 동작입니다 | `trackEvent('액션명')` | | ViewableImpression | 화면 상의 특정 콘텐츠 영역의 노출을 기록합니다. 노출은 사용자가 실제로 해당 영역을 본 경우를 뜻하며, 게임플레이에서는 게임 종료 팝업 노출에 사용합니다 | `trackViewImp('액션명')` | | Usage | 페이지 단위로 사용자의 체류시간을 기록합니다. 보통 체류시간 측정을 위해 사용하며, 서비스에서 직접 페이지 진입·이탈 시점을 확인해 측정한 시간을 기록합니다. ms 단위로 기록합니다. 최대값은 3시간으로, 그 이상 값이 입력되면 null로 변환되어 저장됩니다 | `trackUsage('액션명')` | ### 세팅시 주의사항 * 아래 필드는 설정 후 페이지 전환 등 TiaraTracker 인스턴스가 재생성되기 전까지 고정됩니다. * Page, PageMeta: `setPage()` 및 `setPageMeta()` 호출 이후 고정 * SPA 등 TiaraTracker 인스턴스가 재생성되지 않는 환경에서는 필요 시 페이지 전환 이후 다음 필드를 초기화합니다. * Page, PageMeta: `setPage()` 및 `setPageMeta()`로 초기화 ## SDK 설치 및 초기화 ### 스크립트 추가 분석하려는 웹 페이지의 상단에 아래 내용을 추가합니다. `` 영역 사용을 권장합니다. ```html ``` ### 기본 설정 (초기화) 스크립트 로드 후 아래 설정 항목(Deployment·서비스 도메인·페이지명·Section)을 설정합니다. ## 설정 항목 TiaraTracker에 지정하는 설정값입니다. 게임플레이 입점 시 반드시 맞춰야 하는 값은 [게임 로그 설정의 필수 세팅 항목](/api-sdk/sdk/tiara-game-logs#필수-세팅-항목)을 먼저 확인하세요. ### Deployment 세팅 게임플레이 파트너사는 `production`만 사용합니다. 개발·테스트 단계에서도 동일하게 `production`을 사용하며, `dev`·`cbt`·`sandbox`로 전송한 로그는 게임플레이 로그로 수집되지 않습니다. ```ts TiaraTracker.getInstance().setDeploymentProduction().track(); ``` ### 서비스 구분 전송되는 데이터의 서비스를 구분하기 위한 정보를 설정합니다. 게임플레이 입점 파트너사는 카카오에서 제공하는 svcDomain 값을 그대로 사용합니다. ```text .setSvcDomain('gameplay.kakao.com') ``` ### 페이지명 게임플레이 파트너사는 `SDK게임`으로 고정합니다. 세팅 이후에는 페이지 전환 등 TiaraTracker 인스턴스 초기화 전까지 고정됩니다. ```text .setPage('SDK게임') ``` ### Section 게임플레이 파트너사는 `SDK_{게임ID}`로 고정합니다. `{게임ID}`는 게임플레이 파트너센터에 등록한 게임 코드를 그대로 사용하며, 게임 이름이나 공백은 사용할 수 없습니다. ```text .setSection('SDK_{게임ID}') ``` ### 설정 일괄 적용 아래 항목은 초기화 시 일괄 적용할 수 있습니다. ```ts TiaraTracker.init(config); ``` | 파라미터 | 설명 | | --- | --- | | svcDomain | 서비스를 구분하는 값. 게임플레이 파트너사는 gameplay.kakao.com 고정 사용 | | thirdProvideAgree | 기본값 null제3자 정보 제공 동의 여부. 게임플레이 파트너사는 true 고정 사용 | | thirdAdAgree | 기본값 null광고 마케팅 제공에 동의한 경우 true, 동의하지 않은 경우 false | | deployment | 기본값 production서비스 배포 상태. 게임플레이 파트너사는 production만 사용합니다 | 사용 예제입니다. ```ts const config = { svcDomain: 'gameplay.kakao.com', thirdProvideAgree: true, thirdAdAgree: false, deployment: 'production', }; TiaraTracker.getInstance().init(config); ``` ### TiaraTracker 설정 예제 ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .setDeployment('production') .setAccessToken('access_token') // 또는 .setAppUserId + .setKakaoAppKey .track(); ``` 모든 설정값을 초기화하려면 아래를 실행합니다. ```ts TiaraTracker.initTracker(); ``` ### AccessToken / AppUserId 카카오 계정 연동을 위해 AccessToken 또는 AppUserId를 반드시 설정합니다. 아래 세 가지 방식 중 하나를 선택하며, 미세팅 시 카카오 분석 환경에서 게임 로그를 집계·활용할 수 없습니다. AccessToken·AppUserId·kakaoAppKey는 카카오디벨로퍼스 Prod(Real) phase 기준 값을 사용합니다. ```text .setAccessToken("access_token") // 또는 .setAppUserId("app_user_id") + .setKakaoAppKey("kakaoappkey") // 또는 .setAppUserId("app_user_id") + .setKakaoAppId("kakaoappid") ``` app\_user\_id를 넣을 때는 kakaoAppKey 또는 kakaoAppId를 반드시 함께 설정해야 합니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .setAccessToken('xxx-xxx-xxx-xxx') // 또는 .setAppUserId('xxx-xxx-xxx-xxx'); ``` ### 제3자 동의 여부 세팅 게임플레이 플랫폼에 입점하는 파트너사는 제3자 정보 제공 동의 여부를 필수로 세팅하고, 광고 마케팅 동의 여부는 사용자 선택값을 알고 있는 경우 함께 세팅합니다. 해당 정보는 로그인한 상태에서만 세팅합니다. 게임플레이 사용자는 진입 시 제3자 정보 제공 동의를 필수로 거치므로 `thirdProvideAgree`는 항상 `true`로 설정합니다. 미설정 또는 `false` 상태의 게임 로그는 카카오 내부에서 분석·활용할 수 없습니다. [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)를 쓰는 게임은 이 setter 를 직접 호출하지 않습니다. 광고 마케팅 동의 여부는 `init({tiara: {thirdAdAgree}})` 로 넘기고, 제3자 정보 제공 동의는 SDK 가 `true` 로 고정합니다. | setter | 매개변수 타입 | 설명 | | -------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | setThirdProvideAgree | boolean | (필수 동의) 제3자 정보 제공 동의 여부. 게임플레이 진입을 위한 필수 동의로, 미동의 사용자는 진입 자체가 불가능합니다. 게임플레이 사용자는 항상 동의 상태이므로 true로 세팅합니다 | | setThirdAdAgree | boolean | (선택 동의) 광고 마케팅 동의 여부. 사용자가 선택할 수 있는 동의이므로 동의/미동의 케이스가 모두 발생합니다. 사용자 선택에 따라 true 또는 false로 세팅합니다 | 게임 로그 필드 `common.third_provide_agree = 1`은 `thirdProvideAgree: true`와 같습니다. 동의한 사용자는 반드시 `true(=1)`로 설정해 전송합니다. ## 게임 로그 전송 방법 게임플레이 필수 게임 로그의 액션명은 [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의) 표의 Name 값을 그대로 사용합니다. ### Pageview 페이지(화면) 정보를 트래킹할 때 사용합니다. ```ts trackPage('액션명'); ``` 사용 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); TiaraTracker.getInstance().trackPage('SDK_게임_조회').track(); ``` ### Event 이벤트 통계를 수집할 때 사용합니다. 이벤트란 클릭 등 Pageview를 제외한 사용자 행동입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); TiaraTracker.getInstance().trackEvent('게임종료_팝업_확인_클릭').track(); ``` ### Usage 페이지 체류시간을 수집할 때 사용합니다. 체류시간은 Foreground 상태에서 실제 페이지를 사용한 시간을 기준으로 측정합니다. * Foreground/Background 전환은 게임웹뷰 SDK의 [registerNativeHandler와 UPDATE 이벤트](/api-sdk/sdk/kakaotalk-gameplay#registernativehandler-handlername-와-update-이벤트) 중 `LIFECYCLE` 이벤트로 감지합니다. * `FOREGROUND`: 체류시간 측정 시작 또는 재시작 (0ms부터 측정) * `BACKGROUND`: 현재까지 측정한 체류시간을 Usage로 기록 및 전송 * 페이지 진입 시 최초 측정을 시작하며, 이후 `FOREGROUND` 전환마다 새로운 사용 세션으로 간주해 0ms부터 다시 측정합니다. * 페이지 이탈 시 측정 중인 체류시간이 있으면 마지막 구간을 기록 및 전송합니다. * ms 단위로 기록하며 최대 3시간(10,800,000ms)입니다. 초과 시 null로 변환되어 저장됩니다. ```text .trackUsage('액션명') .usage(usage정보) ``` 사용 예제입니다. ```ts const usage = {duration: '120000'}; TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .trackUsage('SDK_게임_체류시간') .usage(usage) .track(); ``` | 파라미터 | 설명 | 예제 | | --------------------- | ----------------------------------------------------------------- | -------- | | duration | 현재 Foreground Usage 구간의 체류시간(ms). 최대 10,800,000 (3시간) | "120000" | ### ViewableImpression `trackViewImp('액션명')` 형태로 액션명을 반드시 전달합니다. 사용 예제입니다. ```ts TiaraTracker.getInstance().trackViewImp('게임종료_팝업_노출').track(); ``` ## 추가 정보 전송 ### ActionKind [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의)에 ActionKind가 명시된 로그(예: `SDK_게임_조회`의 `ViewContent`)는 해당 값을 반드시 동일하게 전송합니다. `SDK_게임_조회` 로그의 전송 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); const pageMeta = { id: 'GAME_001', type: 'h5', name: '퍼즐 게임 샘플', }; TiaraTracker.getInstance() .trackPage('SDK_게임_조회') .actionKind('ViewContent') .pageMeta(pageMeta) .track(); ``` ### Page meta 해당 페이지(page)에 대한 메타 정보를 부가적으로 추가할 수 있습니다. 게임플레이 표준값은 [게임 로그 설정](/api-sdk/sdk/tiara-game-logs)을 참고하세요. 세팅 이후에는 페이지 전환 등 TiaraTracker 인스턴스 초기화 전까지 고정됩니다. ```text .pageMeta(pageMeta) ``` 전송 예제는 [ActionKind](#actionkind)를 참고하세요. ## 이벤트별 스펙 행동 유형별로 전송해야 하는 파라미터 규격입니다. ### Click 이벤트 액션이 클릭인 경우 클릭 항목에 대한 추가 정보를 전송할 수 있습니다. ```text .click(클릭정보) ``` [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의)에 click 정보가 명시된 로그(더보기·공유하기·문의하기·내 게임 관리·닫기·접기)만 `click.layer1: 'header'`를 세팅합니다. 사용 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); const click = {layer1: 'header'}; TiaraTracker.getInstance().trackEvent('게임_더보기_클릭').click(click).track(); ``` ## 참고 문서 * [게임 로그 설정](/api-sdk/sdk/tiara-game-logs): 필수 세팅 항목과 게임 로그 11종 정의 * [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 액션데이터 요청 본문 샘플 * [액션데이터 API](/api-sdk/data/action-data): 게임 이벤트 전송 규격 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)