데이터 수집하기

데이터 수집이란 로그인이나 재화 획득과 같이 게임 플레이나 제품 사용 중 사용자가 하는 행동에 대한 정보를 수집하는 과정을 말합니다. 데이터 수집은 클라이언트에서 이루어지며 관련 API를 불러냄으로써 수행됩니다. 수집된 데이터는 데이터 분석의 근거가 되며 이로부터 개인화 오퍼나 AI 인게임 상점 오퍼가 생성됩니다.

TentuPlay REST upload data ko
데이터 수집 개요

기본 데이터 업로드하기

기본 데이터 업로드 방법에 대해 알아보겠습니다. 여기에는 세 가지 기본적인 행동 데이터만 들어갑니다.

기본적인 사용자 행위로 가입, 로그인, 구매가 있습니다. 이들 행동 데이터는 사용자 활성도, 출석 빈도, 구매자 수, 수익, 평균 경력 등 제품에 대한 핵심 정보(모래시계 분석으로도 알려진)를 도출하는데 사용됩니다. 이를 통해 게임 뿐 아니라 웹사이트를 비롯한 일반 소프트웨어 제품의 활성도와 시장성도 평가할 수 있습니다.

요청

요청 형식

  • A.데이터 압축 없음

  • B.데이터 압축 사용

POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/octet-stream

데이터를 압축하여 보내는 경우 요청 body의 데이터를 UTF8로 인코딩하여 바이트 형태로 전달합니다.

헤더

이름 값 자료형 필수여부 기본값

TPAuthMode

api_key_plain

string

필수

null

TPClientKey

Client key

string

필수

null

Body

Body 예시
{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "players_login": [
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
	"characters_purchases": [
	   {
	     "player_slug":"TentuPlayer",
	     "character_slug":"_DUMMY_CHARACTER_ID_",
	     "purchasable_slug":"productSlug",
	     "purchase_quantity":2.0,
	     "purchase_unit_price":2.5,
	     "purchase_total_price":5.0,
	     "purchase_currency_code":"USD",
	     "is_ad_remove":true,
	     "event_timestamp": 1647504609
	   }
   ]
}
Body 파라미터
이름 설명 자료형 필수여부 비고

players_join

players_join에 포함된 데이터를 업로드하는 것은 Unity SDK의 Join 메소드를 호출하는 것과 같습니다.

player_slug

플레이어의 고유 ID

string

필수

Unity SDK의 player_uuid와 동일

device_unique_id

클라이언트 디바이스 ID

string

필수

device_info

클라이언트 디바이스 정보

string

필수

형식: OS || 모델명 || 디바이스 유형

region

국가 코드 (두자리 알파벳)

string

필수

is_tp_debug_mode

SDK의 디버그 모드 여부

int

필수

유효한 값: 0, 1

event_timestamp

UTC 기준 유닉스 시간

int

필수

players_login

players_login에 포함된 데이터를 업로드하는 것은 Unity SDK의 LoginApp 메소드를 호출하는 것과 같습니다.

app_version

게임 클라이언트 버전

string

선택

기본값: null

sdk_version

SDK 버전

string

필수

현재 버전: 2021.4

characters_purchases

characters_purchases에 포함된 데이터를 업로드하는 것은 Unity SDK의 InAppPurchase 메소드를 호출하는 것과 같습니다.

character_slug

플레이어 캐릭터의 고유 ID

게임에 캐릭터가 없거나, 캐릭터가 아닌 플레이어를 가리킬 경우 character_uuid를 TentuPlayKeyword._DUMMY_CHARACTER_ID_로 설정합니다.

string

필수

Unity SDK의 character_uuid와 동일

purchasable_slug

구매 상품의 고유 구분자

string

필수

purchase_quantity

구매 상품의 갯수 또는 양

double

필수

purchase_unit_price

구매 상품의 단가

double

필수

purchase_total_price

구매 상품의 총 가격

double

필수

purchase_currency_code

구매에 사용된 통화 코드 (ISO 4217에 따른 세자리 알파벳)

string

필수

is_ad_remove

구매한 상품이 광고 제거 상품이거나 광고 제거와 관련된 상품인지 여부

boolean

선택

players_join, players_login이나 players_purchases에 넣을 데이터가 없으면 해당 오브젝트를 아예 넣지 않아도 됩니다. 예를 들어 아래 예시처럼 players_join만 보낼 수 있습니다.

{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ]
}

테이블 별 콘텐츠는 리스트의 형태로 업로드 되기 때문에 한번에 여러 개를 업로드할 수 있습니다. 가령 players_purchases 테이블에는 아래와 같이 여러 이벤트를 넣어 업로드할 수 있습니다.

{
  "characters_purchases": [
    {
      "player_slug":"TentuPlayer",
      "character_slug":"_DUMMY_CHARACTER_ID_",
      "purchasable_slug":"productSlug1",
      "purchase_quantity":2.0,
      "purchase_unit_price":2.5,
      "purchase_total_price":5.0,
      "purchase_currency_code":"USD",
      "is_ad_remove":true,
      "event_timestamp": 1647504609
    },
    {
      "player_slug":"TentuPlayer",
      "character_slug":"_DUMMY_CHARACTER_ID_",
      "purchasable_slug":"productSlug2",
      "purchase_quantity":2.0,
      "purchase_unit_price":2.5,
      "purchase_total_price":5.0,
      "purchase_currency_code":"USD",
      "is_ad_remove":true,
      "event_timestamp": 1647504609
    }
  ]
}

응답

성공

HTTP/1.1 200 OK
Content-Type:application/json
Body 예시
{
    "status": 200,
    "reason": "OK",
    "data": {
        "default": {},
        "cache": {
            "cache_players_join": null,
            "cache_players_login": null,
			      "cache_characters_purchases": null
        }
    }
}

실패

상태 및 오류 코드

키

설명

비고

status

reason

403

"Method Not Allowed"

잘못된 메소드를 사용함 (가령 POST가 아닌 메소드)

400

"Missing Headers"

헤더가 포함되지 않음

400

"Missing TPAuthMode"

헤더에 TPAuthMode 키가 없음

400

"Invalid TPAuthMode"

TPAuthMode 키에 api_key_plain가 아닌 값이 들어감

400

"Missing TPClientKey"

헤더에 TPClientKey 키가 없음

403

"Invalid TPClientKey"

TPClientKey 키의 값이 잘못됨

400

"Missing Body"

요청 body가 없음

400

"Missing Content-Type"

content_type이 포함되지 않음

400

"Unsupported Content Type"

content-type이 잘못됨

유효한 값: application/json, application/octet-stream

전체 데이터 업로드하기

일반적인 데이터 업로드 방법에 대해 알아보겠습니다. 여기에는 텐투플레이가 사용하는 모든 행동 데이터가 포함됩니다.

기본 행동 데이터를 제외한 나머지 행동 데이터는 주로 게임 내 아이템이나 스테이지, 캐릭터와 플레이어 간의 상호 작용을 분석하는데 필요합니다. 이를 통해 특정 스테이지의 플레이 시간 같은 부가적인 게임 지표를 얻을 수 있습니다. 무엇보다 이들 데이터는 지정된 사용자나 특정 사용자 세그먼트에 특화된 개인화 오퍼를 생성하는 재료로 쓰입니다. 따라서 본인의 제품이 게임이고 잔존율과 매출 향상을 위해 오퍼를 제공하고 싶다면 다음 지침에 따라 데이터를 업로드하십시오.

요청

요청 형식

  • A.데이터 압축 없음

  • B.데이터 압축 사용

POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/octet-stream

헤더

이름 값 자료형 필수여부 기본값

TPAuthMode

api_key_plain

string

필수

null

TPClientKey

Client key

string

필수

null

Body

요청 body 형식
{
  "{오브젝트명}": [ (1)
    {
      "{속성명}": "{값}", (2)
      ...
    },
    ...
  ],
  ...
}
1 JSON의 오브젝트는 데이터베이스의 테이블에 해당합니다. 여기서 사용 가능한 모든 오브젝트는 데이터 업로드 오브젝트에서 확인할 수 있습니다.
2 JSON의 속성은 데이터베이스의 컬럼에 해당합니다. 사용 가능한 모든 속성은 데이터 업로드 속성에서 확인할 수 있습니다. 각 속성에 대한 설명은 기본 데이터 업로드에서 요청 body 파라미터와 Unity API 레퍼런스의 각 메소드에서 파라미터 섹션을 참고하십시오.
Body 예시
{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "players_login": [
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    },
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "99bc8eac57de4b506a4164eef8699b46a37f4f9c",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "characters_login": [], (1)
  "characters_purchases": [],
  "characters_ads": [],
  "characters_quests": [],
  "characters_bonuses": [],
  "players_characters_change": [],
  "characters_stats_change": [],
  "characters_custom_ability_change": [],
  "players_stages": [],
  "characters_stages": [],
  "characters_items_infrastructure_play": [],
  "characters_items_consumable_play": [],
  "characters_items_equipment_play": [],
  "characters_items_cosmetic_play": [],
  "characters_skills_play": [],
  "players_characters_get": [
    {
      "player_slug": "TentuPlayer",
      "character_slug": "_DUMMY_CHARACTER_ID_",
      "characterarchetype_slug": "DUMMY_CHARACTER",
      "reference_entity": "join",
      "reference_category_slug": "JOIN",
      "reference_slug": "JOIN",
      "event_timestamp": 1647504609
    }
  ],
  "characters_currencies_get": [],
  "characters_items_infrastructure_get": [],
  "characters_items_token_get": [],
  "characters_items_consumable_get": [],
  "characters_items_material_get": [],
  "characters_items_equipment_get": [],
  "characters_items_cosmetic_get": [],
  "characters_items_randombox_get": [],
  "characters_currencies_use": [],
  "characters_items_equip": [],
  "characters_items_token_use": [],
  "characters_items_consumable_use": [],
  "characters_items_material_use": [],
  "characters_items_randombox_use": [],
  "characters_skills_equip": [],
  "players_characters_dismiss": [],
  "characters_items_dismiss": [],
  "characters_levelup": [],
  "characters_items_levelup": [],
  "characters_skills_levelup": [],
  "characters_currencies_deposit": [],
  "characters_items_deposit": [],
  "characters_currencies_withdraw": [],
  "characters_items_withdraw": []
}
1 어떤 오브젝트(테이블)에 넣을 데이터가 없다면 해당 오브젝트를 아예 넣지 않아도 됩니다. 즉, 예시("characters_login": [], "characters_purchases": [])에 있는 것처럼 넣지 않아됩니다.

응답

성공

HTTP/1.1 200 OK
Content-Type:application/json
Body 예시
{
    "status": 200,
    "reason": "OK",
    "data": {
        "default": {},
        "cache": {
            "cache_players_join": null,
            "cache_players_login": null,
			      "cache_characters_purchases": null
        }
    }
}

실패

상태 및 오류 코드