game
토스게임센터 연동에 필요한 함수 모음입니다. 게임 프로필 조회, 리더보드 점수 제출·열기, 프로모션 리워드 지급, 연락처 기반 친구 공유 리워드(contactsViral)를 지원합니다. 대부분 Promise를 반환하며(예외: contactsViral은 cleanup 함수 반환), contactsViral만 contacts 권한이 필요합니다.
게임 세션 익명 키는 getUserKeyForGame(auth 네임스페이스, deprecated) 또는 권장 후속 getAnonymousKey를 사용하세요.
메서드
| 메서드 | 반환 타입 | 용도 |
|---|---|---|
contactsViral | () => void | 연락처 기반 친구 공유 리워드 모듈을 엽니다. 이벤트 콜백으로 결과를 받습니다. |
getGameCenterGameProfile | Promise<GameCenterGameProfileResponse | undefined> | 토스게임센터 프로필(닉네임, 프로필 이미지)을 조회합니다. |
grantPromotionReward | Promise<GrantPromotionRewardResult> | 모든 카테고리 미니앱에서 프로모션 코드를 사용해 리워드를 지급합니다. |
grantPromotionRewardForGame | Promise<GrantPromotionRewardResult> | Deprecated. 게임 카테고리 미니앱에서 프로모션 리워드를 지급합니다. grantPromotionReward 사용을 권장합니다. |
openGameCenterLeaderboard | Promise<void> | 게임센터 리더보드 웹뷰를 엽니다. |
submitGameCenterLeaderBoardScore | Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined> | 리더보드에 게임 점수를 제출합니다. |
권한
contactsViral만 contacts 권한이 필요합니다. 나머지 함수는 별도의 PermissionName에 바인딩되지 않으며, 토스 세션(계정 연결)이 처리됩니다. 게임센터 함수들은 getPermission() / openPermissionDialog() 유틸도 노출하지 않습니다.
contactsViral은 함수 객체에 권한 유틸이 붙어있지 않으므로, 같은 contacts 권한을 공유하는 fetchContacts.getPermission()으로 사전 확인하세요.
최소 지원 버전
게임센터 API는 토스 앱 5.221.0 이상(안드로이드·iOS 동일)이 필요합니다. 버전이 낮으면 undefined를 반환하거나 아무 동작도 하지 않습니다.
import { isMinVersionSupported } from '@apps-in-toss/web-framework';
if (!isMinVersionSupported('5.221.0')) {
// 사용자에게 앱 업데이트 안내
}
Deprecated 함수 마이그레이션
| 구버전 | 신버전 | 비고 |
|---|---|---|
getUserKeyForGame | getAnonymousKey | 타입·동작 동일. 두 함수 모두 auth 네임스페이스에서 문서화. |
grantPromotionRewardForGame | grantPromotionReward | 게임 전용 → 전체 카테고리 확장 |
UX 가이드
- 프로필이 없을 수 있습니다.
getGameCenterGameProfile은statusCode: 'PROFILE_NOT_FOUND'를 반환할 수 있습니다. 이 경우 프로필 생성 안내 UI를 보여주세요. - 리더보드 점수는 float 문자열로.
submitGameCenterLeaderBoardScore의score는"123.45"형태의 문자열로 전달해야 합니다. - 리워드 에러 코드를 핸들링하세요.
grantPromotionReward/grantPromotionRewardForGame반환값에는 에러 코드가 포함될 수 있습니다. 각 메서드 페이지에서 코드 목록을 확인하세요. - 버전 게이트를 먼저 확인하세요.
undefined반환은 앱 버전이 낮다는 신호입니다 —isMinVersionSupported로 선행 체크하면 사용자에게 더 명확한 안내가 가능합니다.
직접 실행해 보기
sdk-example의 Game 페이지에서 모든 메서드를 직접 실행해 볼 수 있습니다.
sdk-example에서 실행해 보기외부 참조
@apps-in-toss/web-framework— 상위 SDK 패키지. 실제 export는 내부적으로@apps-in-toss/web-bridge에서 가져옵니다.