game

Functions for Toss Game Center integration. Covers game profile lookup, leaderboard score submission and display, promotion reward grants, and contacts-based viral sharing (contactsViral). Most return a Promise (exception: contactsViral returns a cleanup function). Only contactsViral requires the contacts permission.

The anonymous game-session key lives in the auth namespace — use getUserKeyForGame (deprecated) or its recommended successor getAnonymousKey.

Methods

Method	Return type	Purpose
contactsViral	() => void	Open the contacts-based viral sharing reward module. Results arrive via the event callback.
getGameCenterGameProfile	Promise<GameCenterGameProfileResponse | undefined>	Fetch the Toss Game Center profile (nickname, avatar).
grantPromotionReward	Promise<GrantPromotionRewardResult>	Grant a promotion reward in any mini-app category.
grantPromotionRewardForGame	Promise<GrantPromotionRewardResult>	Deprecated. Grant a promotion reward in game-category mini-apps. Use grantPromotionReward instead.
openGameCenterLeaderboard	Promise<void>	Open the Game Center leaderboard web view.
submitGameCenterLeaderBoardScore	Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>	Submit a game score to the leaderboard.

Permission

Only contactsViral requires the contacts permission. The other functions are not bound to any PermissionName (account binding is handled by the Toss session) and do not expose getPermission() / openPermissionDialog() utilities.

contactsViral itself does not expose permission helpers — use fetchContacts.getPermission(), which shares the same contacts permission, to pre-check.

Minimum supported version

Game Center APIs require Toss app 5.221.0 or later (Android and iOS). Calls on older versions return undefined or do nothing.

import { isMinVersionSupported } from '@apps-in-toss/web-framework';

if (!isMinVersionSupported('5.221.0')) {
  // Prompt the user to update the app.
}

Deprecated function migration

Old	New	Notes
getUserKeyForGame	getAnonymousKey	Same type and behavior. Both documented under auth.
grantPromotionRewardForGame	grantPromotionReward	Expanded from game-only to all categories

UX guidance

• Profiles may be absent. getGameCenterGameProfile can return statusCode: 'PROFILE_NOT_FOUND'. Show a profile creation prompt in that case.
• Scores must be float strings. submitGameCenterLeaderBoardScore expects a string like "123.45", not a number.
• Handle reward error codes. grantPromotionReward / grantPromotionRewardForGame return structured error codes — see each method page for the full list.
• Gate on version first. An undefined return signals an outdated app. Pre-checking with isMinVersionSupported lets you show a clearer prompt.

Try it live

All methods are available on the Game page in sdk-example.

→Open in sdk-example

External references

• @apps-in-toss/web-framework — SDK package. The actual exports are re-exported from @apps-in-toss/web-bridge.