플레이어 데이터 수집

Pushwoosh는 플레이어가 누구이며 게임에서 무엇을 하는지 알아야 합니다. 이벤트는 행동을 기록하고, 태그는 각 플레이어의 현재 상태를 보관합니다.

User ID로 플레이어 식별하기

Pushwoosh는 플레이어의 모든 디바이스를 하나의 User ID에 연결하므로, 세그먼트와 Journey는 한 사람을 한 명의 플레이어로 취급합니다. 플레이어가 로그인하기 전에 디바이스가 기록한 이벤트와 User-specific 태그는 이전 ID에 그대로 남습니다. Device-specific 태그는 디바이스와 함께 이동합니다.

기본적으로 Pushwoosh는 각 디바이스의 하드웨어 ID(HWID)를 해당 디바이스의 User ID로 사용합니다. 이 경우 두 디바이스에서 플레이하는 한 명의 플레이어가 두 명으로 집계됩니다. 로그인하는 플레이어에서 이를 방지하려면 자체 계정 ID를 해당 플레이어의 User ID로 설정하세요.

사용할 ID를 선택합니다. 게임이 이미 각 플레이어에게 부여하는 계정 ID를 사용하세요.
플레이어가 로그인할 때 이 ID로 setUserId를 호출하도록 개발자에게 요청합니다.
결과를 확인합니다. 테스트 디바이스에서 게임에 로그인한 다음, 오디언스 → 사용자 탐색기를 열고 사용자 ID로 검색해 계정 ID를 입력합니다. 플레이어의 프로필이 열립니다.

로그인하지 않는 플레이어는 HWID를 User ID로 유지하며, Pushwoosh가 이를 대신 설정합니다.

User ID와 디바이스의 관계에 대해 자세히 알아보려면 사용자 (User ID)를 참조하세요.

추적할 이벤트 설정하기

Pushwoosh는 이벤트를 통해 플레이어가 무엇을 하는지 파악합니다. 이벤트를 먼저 만드세요. 세그먼트는 플레이어가 발생시킨 이벤트를 기준으로 플레이어를 그룹화하고, Journey는 이벤트가 발생하면 시작됩니다.

무엇이든 만들기 전에 이벤트와 그 속성을 함께 계획하세요. 게임 앱용 권장 이벤트에는 속성이 포함된 바로 쓸 수 있는 게임 이벤트가 나와 있으며, 사용자 지정 이벤트에서는 직접 이벤트를 정의하는 방법을 설명합니다.

이벤트에는 두 종류가 있습니다.

기본 이벤트: 디바이스 등록, 앱 열기, 구매 등. SDK가 이 이벤트를 전송하므로 Control Panel에서 만들 필요가 없습니다.
사용자 지정 이벤트: 레벨 완료, 보상 수령, 상점 열기 등. 개발자가 게임에서 이 이벤트를 전송하며, Pushwoosh는 각 이벤트가 처음 도착할 때 이를 생성합니다. 속성 유형을 직접 선택하려면 먼저 Control Panel에서 이벤트를 만드세요. 사용자 지정 이벤트와 자동으로 생성되는 이벤트를 참조하세요.

기본 이벤트

SDK가 이 이벤트를 대신 전송합니다. 이 플레이북의 대부분의 Journey, 즉 온보딩, 윈백, 구매 혜택에 이 이벤트가 필요합니다.

PW_DeviceRegistered: 디바이스가 첫 푸시 토큰을 받았습니다. SDK는 게임이 registerForPushNotifications를 호출할 때만 토큰을 요청하며, 이 호출은 iOS에서 권한 요청 창도 표시합니다. 토큰은 플레이어의 응답과 관계없이 도착합니다. 게임이 첫 실행 이후에 권한을 요청하면 이벤트는 설치 시점이 아니라 그 시점에 발생합니다. 신규 플레이어를 포착하려면 대신 Tutorial started 이벤트를 사용하세요.
PW_ApplicationOpen: 플레이어가 게임을 열었습니다. 아직 플레이 중인 플레이어와 플레이를 중단한 플레이어를 찾아 다시 불러오는 데 필요합니다.
PW_InAppPurchase: 플레이어가 게임에서 무언가를 구매했습니다. 결제 플레이어와 비결제 플레이어를 구분하는 데 필요합니다. 예를 들어 한 번도 결제하지 않은 플레이어에게만 첫 구매 혜택을 제공할 수 있습니다. 개발자는 iOS SDK에서 구매 추적을 켜거나 코드에서 구매를 전송하며, Android에서는 항상 코드에서 전송합니다. iOS에서는 App Store Connect에 구성된 상품에 대해서만 발생합니다.
선택 사항: PW_UserIdle: 플레이어가 설정한 시간(최소 30초) 동안 화면을 터치하지 않으면 발생합니다. 플레이어가 막혔을 때 인앱 힌트를 표시하는 Journey를 시작합니다. 개발자가 SDK 구성에서 활성화합니다.
선택 사항: PW_ApplicationExit: 플레이어가 게임을 떠나 10~30초 안에 돌아오지 않으면 발생합니다. 진행 중간에 떠난 플레이어를 위한 윈백 Journey를 시작합니다. 개발자가 SDK 구성에서 활성화합니다.

SDK가 이벤트를 처음 전송하면 해당 이벤트가 오디언스 → 이벤트에 표시됩니다.

다른 기본 이벤트를 목록에 미리 추가하려면(예: 게임 업데이트가 출시되기 전에 세그먼트를 만들려는 경우):

오디언스 → 이벤트를 열고 이벤트 생성을 클릭합니다.
기본 이벤트를 선택합니다.
이벤트를 선택하고 활성화를 클릭합니다.

3단계의 목록에는 PW_UserIdle과 PW_ApplicationExit이 없습니다. 이 두 이벤트는 SDK가 처음 전송한 후에만 오디언스 → 이벤트에 표시됩니다.

이 이벤트와 기타 기본 이벤트에 대한 자세한 내용은 기본 이벤트를 참조하세요.

사용자 지정 이벤트

사용자 지정 이벤트는 레벨 완료처럼 게임에서 일어나는 일을 기록합니다. 게임에 필요한 이벤트는 사용자가 선택하고, 개발자가 전송하며, 사용자는 이벤트가 도착하는지 확인합니다.

추적할 이벤트 선택하기

게임에 필요한 이벤트와 각 이벤트가 담을 속성을 선택하세요. 예를 들어 Level completed에는 level_id가 있습니다. 표의 예시는 그대로 사용하거나, 이름을 바꾸거나, 직접 추가할 수 있습니다. 실행하는 Journey에 필요한 이벤트만 추적하세요.

이벤트	발생 시점	주요 속성	활용
New level	플레이어가 새 레벨에 도달함	`level_id` (String)	선택 사항: 자체 마일스톤 세그먼트
Level completed	플레이어가 레벨을 완료함	`level_id` (String)	참여도 높은 비결제자 및 막힌 플레이어 세그먼트, 막힌 플레이어 지원 Journey
Level failed	플레이어가 레벨에 실패함	`level_id` (String)	막힌 플레이어 세그먼트 및 Journey
Tutorial started	플레이어가 게임 내 튜토리얼을 시작함	`tutorial_name` (String)	온보딩 Journey, 튜토리얼 이탈 세그먼트
Tutorial completed	플레이어가 게임 내 튜토리얼을 완료함	`tutorial_name` (String), `completion` (Boolean)	온보딩 Journey, 푸시 권한 흐름
Virtual currency earned	플레이어의 게임 내 재화 잔액이 늘어남	`currency_name` (String), `quantity` (Integer)	선택 사항: 자체 재화 기반 세그먼트
Achievement unlocked	플레이어가 업적을 달성함	`achievement_name` (String), `level` (Integer)	업적 사냥꾼 세그먼트
Daily reward claimed	플레이어가 일일 보상을 수령함	`day_number` (Integer)	일일 보상 알림 Journey
Live event joined	플레이어가 라이브 이벤트에 참여함	`event_id` (String)	라이브 이벤트 Journey의 전환 목표
Store opened	플레이어가 게임 내 상점을 엶	`section` (String)	상점 이탈 Journey

게임에서 이벤트 전송하기

게임이 전송할 이벤트와 각 이벤트가 담을 속성을 개발자와 합의하세요. 이벤트와 속성의 이름은 정확히 일치해야 합니다.

예를 들어, 게임은 level_id 속성과 함께 Level completed를 다음과 같이 전송합니다.

Android
iOS

TagsBundle attributes = new TagsBundle.Builder()
    .putString("level_id", "12")
    .build();

InAppManager.getInstance().postEvent("Level completed", attributes);

PWInAppManager.shared().postEvent("Level completed", withAttributes: ["level_id": "12"])

게임 백엔드나 토너먼트 서비스처럼 이미 자체 웹훅을 보내는 서버에서 이벤트가 발생하는 경우, 이벤트는 postEvent 대신 인바운드 웹훅을 통해 Pushwoosh에 도달할 수 있습니다. Control Panel에서 이 서버가 보내는 필드를 Pushwoosh 이벤트에 매핑하면, 해당 이벤트는 다른 이벤트처럼 Journey를 시작할 수 있습니다.

이벤트가 도착했는지 확인하려면 오디언스 → 사용자 탐색기를 열고 테스트 플레이어를 찾은 다음 이벤트 기록 탭을 여세요.

PW_Conversion으로 매출 추적하기

PW_Conversion은 모든 구매의 금액과 통화를 하나의 형식으로 기록합니다. Journey의 매출 목표와 RFM 세분화의 지출 등급에 필요합니다. RFM 세분화는 플레이어를 최근 구매 시점, 구매 빈도, 구매 금액에 따라 그룹화합니다.

iOS SDK가 추적하는 구매는 __amount와 __currency 속성을 담고 있으므로 자동으로 PW_Conversion에 반영됩니다. Android 구매에는 다음 중 하나가 필요합니다.

게임이 iOS와 Android 모두에서 실행된다면, Android 구매를 SDK의 구매 메서드 대신 postEvent를 통해 숫자형 __amount와 __currency 속성이 있는 PW_InAppPurchase로 전송하도록 개발자에게 요청하세요. 그러면 동일한 자동 매핑이 두 플랫폼을 모두 처리합니다.
게임이 Android에서만 실행된다면, 새 코드 없이 구매를 직접 매핑하세요. 하나의 이벤트에는 매핑이 하나만 유지되므로, iOS 구매가 있는 게임에서 수동 매핑을 하면 자동 매핑이 대체됩니다.

구매를 직접 매핑하려면:

오디언스 → 이벤트를 열고 전환 이벤트 설정을 엽니다.
PW_InAppPurchase를 전환 이벤트로 추가합니다.
가격과 통화를 담은 속성을 선택합니다.
적용을 클릭합니다.

모든 설정 옵션은 전환 이벤트를 참조하세요.

스토어에서 구독 추적하기

게임에서 VIP 패스나 배틀 패스 같은 구독을 판매한다면, Pushwoosh는 App Store와 Google Play에서 구독 상태 변경을 받습니다. 각 변경은 PW_Subscription* 이벤트로 도착합니다. 예:

PW_SubscriptionStart: 플레이어가 구독합니다.
PW_SubscriptionCancel: 플레이어가 자동 갱신을 끕니다.
PW_SubscriptionBillingIssue: 갱신 결제가 실패합니다.

이 이벤트로 Journey를 시작하세요. 예를 들어 취소된 패스가 만료되기 전에 알림을 보낼 수 있습니다.

이 이벤트는 구독만 다룹니다. 코인 팩 같은 일회성 구매는 계속 PW_InAppPurchase로 도착합니다.

태그에 플레이어 데이터 저장

태그는 플레이어의 레벨이나 결제 여부처럼 Pushwoosh가 플레이어 프로필에 저장하는 값입니다. 이벤트는 일어난 일을 기록하고, 태그는 현재 상태를 보관합니다. 태그를 사용하면 다음을 할 수 있습니다.

특정 값을 가진 플레이어에게만 메시지를 보냅니다. 예를 들어 결제 플레이어에게만 혜택을 보냅니다.
메시지 텍스트에 값을 넣습니다. 예를 들어 플레이어의 레벨을 넣습니다. Journey 구축을 참조하세요.

태그는 선택 사항입니다. 이 플레이북의 Journey는 이벤트와 Pushwoosh가 직접 설정하는 기본 태그로 실행되므로, 처음에는 자체 태그를 건너뛰어도 됩니다. 플레이어를 그룹화하는 방법을 더 늘리고 싶을 때 추가하세요. 태그 기반 세그먼트를 참조하세요.

자체 태그

개발자가 게임에서 태그 값을 전송하거나, CSV 파일에서 가져올 수 있습니다. 개발자가 태그를 처음 전송하면 Pushwoosh는 이를 User-specific 태그로 생성합니다. 태그 유형을 직접 선택하려면 먼저 Control Panel에서 태그를 만드세요. 태그로 사용자 데이터 관리하기를 참조하세요.

다음 태그는 예시입니다. 게임의 용어에 맞게 이름을 바꾸고 직접 추가하세요.

태그	유형	예시	활용
`player_level`	Integer	`12`	진행 단계별로 메시지 필터링
`is_paying_user`	Boolean	`true`	결제 플레이어와 비결제 플레이어용 메시지 분리
`soft_currency_balance`	Integer	`1500`	잔액이 적은 플레이어에게 재화 팩 제안
`vip_tier`	String	`gold`	VIP 플레이어에게 전용 혜택과 얼리 액세스 제공
`favorite_mode`	String	`pvp`	플레이어가 좋아하는 모드의 라이브 이벤트 공지

Control Panel에서 태그를 만들 때는 기본값대로 사용자별을 켜 둔 상태로 유지하세요. 그러면 Pushwoosh는 User ID마다 하나의 값을 보관하므로, 값은 플레이어의 디바이스 중 하나가 아니라 플레이어에게 속합니다. 사용자별을 끄면 각 디바이스가 자체 값을 보관합니다. User ID로 플레이어 식별하기를 참조하세요.

기본 태그

Pushwoosh는 모든 디바이스에 대해 다음 기본 태그를 저장하므로 직접 만들 필요가 없습니다.

Language: 디바이스의 언어입니다. Pushwoosh는 이를 사용해 각 플레이어에게 해당 언어로 된 메시지를 보냅니다.
Last Application Open: 디바이스에서 게임을 마지막으로 연 시점입니다. 플레이를 중단한 플레이어를 찾는 데 사용하세요.
Push Alerts Enabled: 디바이스 설정에서 알림이 허용되어 있는지 여부입니다. 아직 알림을 허용하지 않은 플레이어에게만 인앱 메시지를 표시하는 데 사용하세요.
First Install: 디바이스에 게임을 처음 설치한 시점입니다. 설치 기념일에 사용하세요.
Country: 디바이스의 국가입니다. 한 지역의 플레이어에게만 혜택이나 라이브 이벤트 공지를 보내는 데 사용하세요.