GameAction API

GameAction API

게임 한 판(round/stage/level)의 라이프사이클을 플랫폼에 알리기 위한 메서드 묶음입니다. SDK 가 기록한 액션은 플랫폼 측에서 분석/리포팅 등으로 활용됩니다. 모든 호출은 fire-and-forget 으로 동작하며 응답을 기다리지 않습니다.

TudadaSDK.gameAction 네임스페이스 아래 3 개의 메서드를 제공합니다:

• start(options?) — 한 판 시작
• complete(options) — 한 판 정상 클리어
• exit(options) — 한 판 비정상 종료(포기/타임아웃)

---

start(options?)

게임이 한 판을 시작했음을 알립니다. 옵션은 모두 선택입니다.

옵션:

파라미터	타입	필수	설명
payload.round	number	-	라운드 번호
payload.stage	number	-	스테이지 번호
payload.level	number	-	레벨 번호
additionalPayload	string	-	자유 메타 데이터 (게임이 전달하고 싶은 임의의 문자열)

// 예시 1: 인자 없이 호출
TudadaSDK.gameAction.start();

// 예시 2: stage 정보 포함
TudadaSDK.gameAction.start({
  payload: { stage: 3 },
});

// 예시 3: 자유 메타 데이터 포함
TudadaSDK.gameAction.start({
  payload: { round: 1, stage: 3, level: 5 },
  additionalPayload: JSON.stringify({ tutorial: true }),
});

---

complete(options)

게임이 한 판을 정상 클리어했음을 알립니다. result 와 playTime 은 필수입니다.

옵션:

파라미터	타입	필수	설명
payload.result	'WIN' | 'LOSE' | 'DRAW' | 'DONE'	✅	종료 결과
payload.playTime	number	✅	한 판 진행 시간 (ms)
payload.score	number	-	획득 점수
payload.round	number	-	라운드 번호
payload.stage	number	-	스테이지 번호
payload.level	number	-	레벨 번호
additionalPayload	string	-	자유 메타 데이터

TudadaSDK.gameAction.complete({
  payload: {
    result: 'WIN',
    playTime: 12345,
    score: 9000,
    stage: 3,
  },
});

---

exit(options)

게임이 한 판을 정상 완료하지 않고 종료했음을 알립니다. 플레이어 포기·시간 초과 등이 해당됩니다. playTime 과 reason 은 필수입니다.

옵션:

파라미터	타입	필수	설명
payload.playTime	number	✅	한 판 진행 시간 (ms)
payload.reason	'TIMEOUT' | 'ABANDONED'	✅	종료 사유
additionalPayload	string	-	자유 메타 데이터

// 플레이어가 포기
TudadaSDK.gameAction.exit({
  payload: { playTime: 4500, reason: 'ABANDONED' },
});

// 시간 초과
TudadaSDK.gameAction.exit({
  payload: { playTime: 60000, reason: 'TIMEOUT' },
});

팁

exit() 는 게임 코드가 한 판의 종료 시점을 명시적으로 판단해 호출해야 합니다. 페이지 unload(웹뷰 닫힘)와는 무관하게 동작합니다.