@apps-in-toss/native-modules 1.3.0 → 1.4.0

package/dist/bridges-meta.json

@@ -107,6 +107,14 @@
     "identifier": "submitGameCenterLeaderBoardScore",
     "dts": "/**\n * @public\n * @category 게임센터\n * @name SubmitGameCenterLeaderBoardScoreResponse\n * @description\n * 토스게임센터 리더보드에 점수를 제출한 결과 정보를 담아서 반환해요. 반환된 정보를 사용해서 점수 제출 결과에 따라 적절한 에러 처리를 할 수 있어요.\n * @property {'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE'} statusCode\n * 점수 제출 결과를 나타내는 상태 코드예요.\n * - `'SUCCESS'`: 점수 제출이 성공했어요.\n * - `'LEADERBOARD_NOT_FOUND'`: `gameId`에 해당하는 리더보드를 찾을 수 없어요.\n * - `'PROFILE_NOT_FOUND'`: 사용자의 프로필이 없어요.\n * - `'UNPARSABLE_SCORE'`: 점수를 해석할 수 없어요. 점수는 실수(float) 형태의 문자열로 전달해야 해요.\n */\nexport interface SubmitGameCenterLeaderBoardScoreResponse {\n\tstatusCode: \"SUCCESS\" | \"LEADERBOARD_NOT_FOUND\" | \"PROFILE_NOT_FOUND\" | \"UNPARSABLE_SCORE\";\n}\n/**\n * @public\n * @category 게임센터\n * @name submitGameCenterLeaderBoardScore\n * @description\n * 사용자의 게임 점수를 토스게임센터 리더보드에 제출해요. 이 기능으로 사용자의 점수를 공식 리더보드에 기록하고 다른 사용자와 비교할 수 있어요.\n * @param {string} params.score\n * 제출할 게임 점수예요. 실수 형태의 숫자를 문자열로 전달해야 해요. 예를들어 `\"123.45\"` 또는 `\"9999\"` 예요.\n * @returns {Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>}\n * 점수 제출 결과를 반환해요. 앱 버전이 최소 지원 버전보다 낮으면 아무 동작도 하지 않고 `undefined`를 반환해요.\n *\n * @example\n * ### 게임 점수를 토스게임센터 리더보드에 제출하기\n * ```tsx\n * import { Button } from 'react-native';\n * import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/framework';\n *\n * function GameCenterLeaderBoardScoreSubmitButton() {\n *   async function handlePress() {\n *     try {\n *       const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });\n *\n *       if (!result) {\n *         console.warn('지원하지 않는 앱 버전이에요.');\n *         return;\n *       }\n *\n *       if (result.statusCode === 'SUCCESS') {\n *         console.log('점수 제출 성공!');\n *       } else {\n *         console.error('점수 제출 실패:', result.statusCode);\n *       }\n *     } catch (error) {\n *       console.error('점수 제출 중 오류가 발생했어요.', error);\n *     }\n *   }\n *\n *   return (\n *     <Button onPress={handlePress}>점수 제출하기</Button>\n *   );\n * }\n * ```\n */\nexport declare function submitGameCenterLeaderBoardScore(params: {\n\tscore: string;\n}): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;\n\nexport {};\n"
   },
+  {
+    "identifier": "getUserKeyForGame",
+    "dts": "export interface GetUserKeyForGameSuccessResponse {\n\thash: string;\n\ttype: \"HASH\";\n}\nexport interface GetUserKeyForGameErrorResponse {\n\ttype: \"NOT_AVAILABLE\";\n}\nexport type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;\n/**\n * @public\n * @category 게임\n * @name getUserKeyForGame\n * @description\n * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.\n * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.\n * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}\n * 사용자 키 조회 결과를 반환해요.\n * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.\n * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.\n * - `'ERROR'`: 알 수 없는 오류가 발생했어요.\n * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.\n *\n * @example\n * ```tsx\n * // react-native\n * import { Button } from 'react-native';\n * import { getUserKeyForGame } from '@apps-in-toss/framework';\n *\n * function GameUserKeyButton() {\n *   async function handlePress() {\n *       const result = await getUserKeyForGame();\n *\n *       if (!result) {\n *         console.warn('지원하지 않는 앱 버전이에요.');\n *         return;\n *       }\n *\n *       if (result === 'INVALID_CATEGORY') {\n *         console.error('게임 카테고리가 아닌 미니앱이에요.');\n *         return;\n *       }\n *\n *       if (result === 'ERROR') {\n *         console.error('사용자 키 조회 중 오류가 발생했어요.');\n *         return;\n *       }\n *\n *       if (result.type === 'HASH') {\n *         console.log('사용자 키:', result.hash);\n *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.\n *       }\n *   }\n *\n *   return (\n *     <Button onPress={handlePress} title=\"유저 키 가져오기\" />\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // webview\n * import { getUserKeyForGame } from '@apps-in-toss/web-framework';\n *\n * function GameUserKeyButton() {\n *   async function handleClick() {\n *       const result = await getUserKeyForGame();\n *\n *       if (!result) {\n *         console.warn('지원하지 않는 앱 버전이에요.');\n *         return;\n *       }\n *\n *       if (result === 'INVALID_CATEGORY') {\n *         console.error('게임 카테고리가 아닌 미니앱이에요.');\n *         return;\n *       }\n *\n *       if (result === 'ERROR') {\n *         console.error('사용자 키 조회 중 오류가 발생했어요.');\n *         return;\n *       }\n *\n *       if (result.type === 'HASH') {\n *         console.log('사용자 키:', result.hash);\n *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.\n *       }\n *   }\n *\n *   return (\n *     <button onClick={handleClick}>유저 키 가져오기</button>\n *   );\n * }\n * ```\n */\nexport declare function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | \"INVALID_CATEGORY\" | \"ERROR\" | undefined>;\n\nexport {};\n"
+  },
+  {
+    "identifier": "grantPromotionRewardForGame",
+    "dts": "export interface GrantPromotionRewardForGameSuccessResponse {\n\tkey: string;\n}\nexport interface GrantPromotionRewardForGameErrorResponse {\n\tcode: string;\n\t[key: string]: any;\n}\nexport interface GrantPromotionRewardForGameErrorResult {\n\terrorCode: string;\n\tmessage: string;\n}\nexport type GrantPromotionRewardForGameResponse = GrantPromotionRewardForGameSuccessResponse | GrantPromotionRewardForGameErrorResponse;\nexport type GrantPromotionRewardForGameResult = GrantPromotionRewardForGameResponse | GrantPromotionRewardForGameErrorResult | \"ERROR\" | undefined;\n/**\n * @public\n * @category 게임\n * @name grantPromotionRewardForGame\n * @description\n * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.\n * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.\n * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.\n * @param {string} params.promotionCode - 프로모션 코드예요.\n * @param {number} params.amount - 지급할 포인트 금액이에요.\n * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}\n * 포인트 지급 결과를 반환해요.\n * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.\n * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.\n *   - `\"40000\"`: 게임이 아닌 미니앱에서 호출했을 때\n *   - `\"4100\"`: 프로모션 정보를 찾을 수 없을 때\n *   - `\"4104\"`: 프로모션이 중지되었을 때\n *   - `\"4105\"`: 프로모션이 종료되었을 때\n *   - `\"4108\"`: 프로모션이 승인되지 않았을 때\n *   - `\"4109\"`: 프로모션이 실행중이 아닐 때\n *   - `\"4110\"`: 리워드를 지급/회수할 수 없을 때\n *   - `\"4112\"`: 프로모션 머니가 부족할 때\n *   - `\"4113\"`: 이미 지급/회수된 내역일 때\n *   - `\"4114\"`: 프로모션에 설정된 1회 지급 금액을 초과할 때\n * - `'ERROR'`: 알 수 없는 오류가 발생했어요.\n * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.\n * @example\n * ```tsx\n * // react-native\n * import { Button } from 'react-native';\n * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';\n *\n * function GrantRewardButton() {\n *   async function handlePress() {\n *       const result = await grantPromotionRewardForGame({\n *         params: {\n *           promotionCode: 'GAME_EVENT_2024',\n *           amount: 1000,\n *         },\n *       });\n *\n *       if (!result) {\n *         console.warn('지원하지 않는 앱 버전이에요.');\n *         return;\n *       }\n *\n *       if (result === 'ERROR') {\n *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');\n *         return;\n *       }\n *\n *       if ('key' in result) {\n *         console.log('포인트 지급 성공!', result.key);\n *       } else if ('errorCode' in result) {\n *         console.error('포인트 지급 실패:', result.errorCode, result.message);\n *       }\n *   }\n *\n *   return <Button onPress={handlePress} title=\"포인트 지급하기\" />;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // webview\n * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';\n *\n * function GrantRewardButton() {\n *   async function handleClick() {\n *       const result = await grantPromotionRewardForGame({\n *         params: {\n *           promotionCode: 'GAME_EVENT_2024',\n *           amount: 1000,\n *         },\n *       });\n *\n *       if (!result) {\n *         console.warn('지원하지 않는 앱 버전이에요.');\n *         return;\n *       }\n *\n *       if (result === 'ERROR') {\n *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');\n *         return;\n *       }\n *\n *       if ('key' in result) {\n *         console.log('포인트 지급 성공!', result.key);\n *       } else if ('errorCode' in result) {\n *         console.error('포인트 지급 실패:', result.errorCode, result.message);\n *       }\n *   }\n *\n *   return (\n *     <button onClick={handleClick}>포인트 지급하기</button>\n *   );\n * }\n * ```\n */\nexport declare function grantPromotionRewardForGame({ params, }: {\n\tparams: {\n\t\tpromotionCode: string;\n\t\tamount: number;\n\t};\n}): Promise<GrantPromotionRewardForGameResult>;\n\nexport {};\n"
+  },
   {
     "identifier": "getLocale",
     "dts": "/**\n * @public\n * @category 언어\n * @kind function\n * @name getLocale\n * @description\n * 사용자의 로케일(locale) 정보를 반환해요. 네이티브 모듈에서 로케일 정보를 가져올 수 없을 때는 기본값으로 'ko-KR'을 반환합니다. 앱의 현지화 및 언어 설정과 관련된 기능을 구현할 때 사용하세요.\n *\n * @returns {string} 사용자의 로케일 정보를 반환해요.\n *\n * @example\n * ### 현재 사용자의 로케일 정보 가져오기\n *\n * ```tsx\n * import { getLocale } from '@apps-in-toss/native-modules';\n * import { Text } from 'react-native';\n *\n * function MyPage() {\n *  const locale = getLocale();\n *\n *  return (\n *    <Text>사용자의 로케일 정보: {locale}</Text>\n *  )\n * }\n *\n * ```\n */\nexport declare function getLocale(): string;\n\nexport {};\n"

package/dist/index.cjs

@@ -51,6 +51,8 @@ __export(index_exports, {
   getSchemeUri: () => getSchemeUri2,
   getTossAppVersion: () => getTossAppVersion,
   getTossShareLink: () => getTossShareLink,
+  getUserKeyForGame: () => getUserKeyForGame,
+  grantPromotionRewardForGame: () => grantPromotionRewardForGame,
   iapCreateOneTimePurchaseOrder: () => iapCreateOneTimePurchaseOrder,
   isMinVersionSupported: () => isMinVersionSupported,
   onVisibilityChangedByTransparentServiceWeb: () => onVisibilityChangedByTransparentServiceWeb,
@@ -914,6 +916,14 @@ var GAME_CENTER_MIN_VERSION = {
   android: "5.221.0",
   ios: "5.221.0"
 };
+var GAME_USER_KEY_MIN_VERSION = {
+  android: "5.232.0",
+  ios: "5.232.0"
+};
+var GAME_PROMOTION_REWARD_MIN_VERSION = {
+  android: "5.232.0",
+  ios: "5.232.0"
+};
 
 // src/AppsInTossModule/native-modules/openGameCenterLeaderboard.ts
 async function openGameCenterLeaderboard() {
@@ -948,6 +958,54 @@ async function submitGameCenterLeaderBoardScore(params) {
   return AppsInTossModule.submitGameCenterLeaderBoardScore(params);
 }
 
+// src/AppsInTossModule/native-modules/getUserKeyForGame.ts
+async function getUserKeyForGame() {
+  const isSupported = isMinVersionSupported(GAME_USER_KEY_MIN_VERSION);
+  if (!isSupported) {
+    return;
+  }
+  try {
+    const response = await AppsInTossModule.getUserKeyForGame({});
+    if (response.type === "HASH") {
+      return response;
+    }
+    if (response.type === "NOT_AVAILABLE") {
+      return "INVALID_CATEGORY";
+    }
+    return "ERROR";
+  } catch (_) {
+    return "ERROR";
+  }
+}
+
+// src/AppsInTossModule/native-modules/grantPromotionRewardForGame.ts
+function isGrantPromotionRewardForGameError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+}
+async function grantPromotionRewardForGame({
+  params
+}) {
+  const isSupported = isMinVersionSupported(GAME_PROMOTION_REWARD_MIN_VERSION);
+  if (!isSupported) {
+    return;
+  }
+  try {
+    const response = await AppsInTossModule.grantPromotionRewardForGame({ params });
+    if (response.key) {
+      return response;
+    }
+    return "ERROR";
+  } catch (error) {
+    if (isGrantPromotionRewardForGameError(error)) {
+      return {
+        errorCode: error.code,
+        message: error.message
+      };
+    }
+    return "ERROR";
+  }
+}
+
 // src/AppsInTossModule/native-event-emitter/contactsViral.ts
 function contactsViral(params) {
   const isSupported = isMinVersionSupported({
@@ -1143,6 +1201,8 @@ var INTERNAL__module = {
   getSchemeUri,
   getTossAppVersion,
   getTossShareLink,
+  getUserKeyForGame,
+  grantPromotionRewardForGame,
   iapCreateOneTimePurchaseOrder,
   isMinVersionSupported,
   onVisibilityChangedByTransparentServiceWeb,

package/dist/index.d.cts

@@ -1443,6 +1443,222 @@ type GameCenterGameProfileResponse = {
  */
 declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
 
+interface GetUserKeyForGameSuccessResponse {
+    hash: string;
+    type: 'HASH';
+}
+interface GetUserKeyForGameErrorResponse {
+    type: 'NOT_AVAILABLE';
+}
+type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;
+/**
+ * @public
+ * @category 게임
+ * @name getUserKeyForGame
+ * @description
+ * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.
+ * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}
+ * 사용자 키 조회 결과를 반환해요.
+ * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
+ * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ *
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { getUserKeyForGame } from '@apps-in-toss/framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handlePress() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <Button onPress={handlePress} title="유저 키 가져오기" />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { getUserKeyForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handleClick() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>유저 키 가져오기</button>
+ *   );
+ * }
+ * ```
+ */
+declare function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
+
+interface GrantPromotionRewardForGameSuccessResponse {
+    key: string;
+}
+interface GrantPromotionRewardForGameErrorResponse {
+    code: string;
+    [key: string]: any;
+}
+interface GrantPromotionRewardForGameErrorResult {
+    errorCode: string;
+    message: string;
+}
+type GrantPromotionRewardForGameResponse = GrantPromotionRewardForGameSuccessResponse | GrantPromotionRewardForGameErrorResponse;
+type GrantPromotionRewardForGameResult = GrantPromotionRewardForGameResponse | GrantPromotionRewardForGameErrorResult | 'ERROR' | undefined;
+/**
+ * @public
+ * @category 게임
+ * @name grantPromotionRewardForGame
+ * @description
+ * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.
+ * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.
+ * @param {string} params.promotionCode - 프로모션 코드예요.
+ * @param {number} params.amount - 지급할 포인트 금액이에요.
+ * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}
+ * 포인트 지급 결과를 반환해요.
+ * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
+ * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.
+ *   - `"40000"`: 게임이 아닌 미니앱에서 호출했을 때
+ *   - `"4100"`: 프로모션 정보를 찾을 수 없을 때
+ *   - `"4104"`: 프로모션이 중지되었을 때
+ *   - `"4105"`: 프로모션이 종료되었을 때
+ *   - `"4108"`: 프로모션이 승인되지 않았을 때
+ *   - `"4109"`: 프로모션이 실행중이 아닐 때
+ *   - `"4110"`: 리워드를 지급/회수할 수 없을 때
+ *   - `"4112"`: 프로모션 머니가 부족할 때
+ *   - `"4113"`: 이미 지급/회수된 내역일 때
+ *   - `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과할 때
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handlePress() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return <Button onPress={handlePress} title="포인트 지급하기" />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handleClick() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>포인트 지급하기</button>
+ *   );
+ * }
+ * ```
+ */
+declare function grantPromotionRewardForGame({ params, }: {
+    params: {
+        promotionCode: string;
+        amount: number;
+    };
+}): Promise<GrantPromotionRewardForGameResult>;
+
 type Sku = {
     /**
      * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
@@ -1980,6 +2196,13 @@ interface Spec extends TurboModule {
         };
     }) => Promise<boolean>;
     getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
+    getUserKeyForGame: (params: CompatiblePlaceholderArgument) => Promise<GetUserKeyForGameResponse>;
+    grantPromotionRewardForGame: (params: {
+        params: {
+            promotionCode: string;
+            amount: number;
+        };
+    }) => Promise<GrantPromotionRewardForGameResponse>;
     submitGameCenterLeaderBoardScore: (params: {
         score: string;
     }) => Promise<SubmitGameCenterLeaderBoardScoreResponse>;
@@ -3401,4 +3624,4 @@ declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { AppsInTossModule, type AppsInTossSignTossCertParams, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { AppsInTossModule, type AppsInTossSignTossCertParams, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, type GetUserKeyForGameErrorResponse, type GetUserKeyForGameResponse, type GetUserKeyForGameSuccessResponse, GoogleAdMob, type GrantPromotionRewardForGameErrorResponse, type GrantPromotionRewardForGameErrorResult, type GrantPromotionRewardForGameResponse, type GrantPromotionRewardForGameSuccessResponse, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };

package/dist/index.d.ts

@@ -1443,6 +1443,222 @@ type GameCenterGameProfileResponse = {
  */
 declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
 
+interface GetUserKeyForGameSuccessResponse {
+    hash: string;
+    type: 'HASH';
+}
+interface GetUserKeyForGameErrorResponse {
+    type: 'NOT_AVAILABLE';
+}
+type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;
+/**
+ * @public
+ * @category 게임
+ * @name getUserKeyForGame
+ * @description
+ * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.
+ * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}
+ * 사용자 키 조회 결과를 반환해요.
+ * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
+ * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ *
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { getUserKeyForGame } from '@apps-in-toss/framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handlePress() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <Button onPress={handlePress} title="유저 키 가져오기" />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { getUserKeyForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handleClick() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>유저 키 가져오기</button>
+ *   );
+ * }
+ * ```
+ */
+declare function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
+
+interface GrantPromotionRewardForGameSuccessResponse {
+    key: string;
+}
+interface GrantPromotionRewardForGameErrorResponse {
+    code: string;
+    [key: string]: any;
+}
+interface GrantPromotionRewardForGameErrorResult {
+    errorCode: string;
+    message: string;
+}
+type GrantPromotionRewardForGameResponse = GrantPromotionRewardForGameSuccessResponse | GrantPromotionRewardForGameErrorResponse;
+type GrantPromotionRewardForGameResult = GrantPromotionRewardForGameResponse | GrantPromotionRewardForGameErrorResult | 'ERROR' | undefined;
+/**
+ * @public
+ * @category 게임
+ * @name grantPromotionRewardForGame
+ * @description
+ * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.
+ * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.
+ * @param {string} params.promotionCode - 프로모션 코드예요.
+ * @param {number} params.amount - 지급할 포인트 금액이에요.
+ * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}
+ * 포인트 지급 결과를 반환해요.
+ * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
+ * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.
+ *   - `"40000"`: 게임이 아닌 미니앱에서 호출했을 때
+ *   - `"4100"`: 프로모션 정보를 찾을 수 없을 때
+ *   - `"4104"`: 프로모션이 중지되었을 때
+ *   - `"4105"`: 프로모션이 종료되었을 때
+ *   - `"4108"`: 프로모션이 승인되지 않았을 때
+ *   - `"4109"`: 프로모션이 실행중이 아닐 때
+ *   - `"4110"`: 리워드를 지급/회수할 수 없을 때
+ *   - `"4112"`: 프로모션 머니가 부족할 때
+ *   - `"4113"`: 이미 지급/회수된 내역일 때
+ *   - `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과할 때
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handlePress() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return <Button onPress={handlePress} title="포인트 지급하기" />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handleClick() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>포인트 지급하기</button>
+ *   );
+ * }
+ * ```
+ */
+declare function grantPromotionRewardForGame({ params, }: {
+    params: {
+        promotionCode: string;
+        amount: number;
+    };
+}): Promise<GrantPromotionRewardForGameResult>;
+
 type Sku = {
     /**
      * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
@@ -1980,6 +2196,13 @@ interface Spec extends TurboModule {
         };
     }) => Promise<boolean>;
     getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
+    getUserKeyForGame: (params: CompatiblePlaceholderArgument) => Promise<GetUserKeyForGameResponse>;
+    grantPromotionRewardForGame: (params: {
+        params: {
+            promotionCode: string;
+            amount: number;
+        };
+    }) => Promise<GrantPromotionRewardForGameResponse>;
     submitGameCenterLeaderBoardScore: (params: {
         score: string;
     }) => Promise<SubmitGameCenterLeaderBoardScoreResponse>;
@@ -3401,4 +3624,4 @@ declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { AppsInTossModule, type AppsInTossSignTossCertParams, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { AppsInTossModule, type AppsInTossSignTossCertParams, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, type GetUserKeyForGameErrorResponse, type GetUserKeyForGameResponse, type GetUserKeyForGameSuccessResponse, GoogleAdMob, type GrantPromotionRewardForGameErrorResponse, type GrantPromotionRewardForGameErrorResult, type GrantPromotionRewardForGameResponse, type GrantPromotionRewardForGameSuccessResponse, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };

package/dist/index.js

@@ -841,6 +841,14 @@ var GAME_CENTER_MIN_VERSION = {
   android: "5.221.0",
   ios: "5.221.0"
 };
+var GAME_USER_KEY_MIN_VERSION = {
+  android: "5.232.0",
+  ios: "5.232.0"
+};
+var GAME_PROMOTION_REWARD_MIN_VERSION = {
+  android: "5.232.0",
+  ios: "5.232.0"
+};
 
 // src/AppsInTossModule/native-modules/openGameCenterLeaderboard.ts
 async function openGameCenterLeaderboard() {
@@ -875,6 +883,54 @@ async function submitGameCenterLeaderBoardScore(params) {
   return AppsInTossModule.submitGameCenterLeaderBoardScore(params);
 }
 
+// src/AppsInTossModule/native-modules/getUserKeyForGame.ts
+async function getUserKeyForGame() {
+  const isSupported = isMinVersionSupported(GAME_USER_KEY_MIN_VERSION);
+  if (!isSupported) {
+    return;
+  }
+  try {
+    const response = await AppsInTossModule.getUserKeyForGame({});
+    if (response.type === "HASH") {
+      return response;
+    }
+    if (response.type === "NOT_AVAILABLE") {
+      return "INVALID_CATEGORY";
+    }
+    return "ERROR";
+  } catch (_) {
+    return "ERROR";
+  }
+}
+
+// src/AppsInTossModule/native-modules/grantPromotionRewardForGame.ts
+function isGrantPromotionRewardForGameError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+}
+async function grantPromotionRewardForGame({
+  params
+}) {
+  const isSupported = isMinVersionSupported(GAME_PROMOTION_REWARD_MIN_VERSION);
+  if (!isSupported) {
+    return;
+  }
+  try {
+    const response = await AppsInTossModule.grantPromotionRewardForGame({ params });
+    if (response.key) {
+      return response;
+    }
+    return "ERROR";
+  } catch (error) {
+    if (isGrantPromotionRewardForGameError(error)) {
+      return {
+        errorCode: error.code,
+        message: error.message
+      };
+    }
+    return "ERROR";
+  }
+}
+
 // src/AppsInTossModule/native-event-emitter/contactsViral.ts
 function contactsViral(params) {
   const isSupported = isMinVersionSupported({
@@ -1069,6 +1125,8 @@ export {
   getSchemeUri2 as getSchemeUri,
   getTossAppVersion,
   getTossShareLink,
+  getUserKeyForGame,
+  grantPromotionRewardForGame,
   iapCreateOneTimePurchaseOrder,
   isMinVersionSupported,
   onVisibilityChangedByTransparentServiceWeb,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apps-in-toss/native-modules",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Native Modules for Apps In Toss",
   "scripts": {
     "prepack": "yarn build",
@@ -43,7 +43,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@apps-in-toss/types": "^1.3.0",
+    "@apps-in-toss/types": "^1.4.0",
     "es-toolkit": "^1.39.3"
   },
   "peerDependencies": {
@@ -54,5 +54,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "71845fd4a349b630c91f07c3ab3d14f81774335a"
+  "gitHead": "b75a03ae2d9de16548e7ec020cbe036fe9896016"
 }

package/src/AppsInTossModule/constants.ts

@@ -4,3 +4,13 @@ export const GAME_CENTER_MIN_VERSION = {
   android: '5.221.0',
   ios: '5.221.0',
 } as const;
+
+export const GAME_USER_KEY_MIN_VERSION = {
+  android: '5.232.0',
+  ios: '5.232.0',
+} as const;
+
+export const GAME_PROMOTION_REWARD_MIN_VERSION = {
+  android: '5.232.0',
+  ios: '5.232.0',
+} as const;

package/src/AppsInTossModule/native-modules/AppsInTossModule.ts

@@ -16,6 +16,8 @@ import { TurboModuleRegistry, type TurboModule as __TurboModule } from 'react-na
 import type { AppsInTossSignTossCertParams } from './appsInTossSignTossCert';
 import type { CheckoutPaymentOptions, CheckoutPaymentResult } from './checkoutPayment';
 import type { GameCenterGameProfileResponse } from './getGameCenterGameProfile';
+import { GetUserKeyForGameResponse } from './getUserKeyForGame';
+import { GrantPromotionRewardForGameResponse } from './grantPromotionRewardForGame';
 import { IapCreateOneTimePurchaseOrderResult, IapProductListItem, CompletedOrRefundedOrdersResult } from './iap';
 import type { SaveBase64DataParams } from './saveBase64Data';
 import type { SubmitGameCenterLeaderBoardScoreResponse } from './submitGameCenterLeaderBoardScore';
@@ -78,6 +80,10 @@ interface Spec extends __TurboModule {
   completeProductGrant: (params: { params: { orderId: string } }) => Promise<boolean>;
 
   getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
+  getUserKeyForGame: (params: CompatiblePlaceholderArgument) => Promise<GetUserKeyForGameResponse>;
+  grantPromotionRewardForGame: (params: {
+    params: { promotionCode: string; amount: number };
+  }) => Promise<GrantPromotionRewardForGameResponse>;
   submitGameCenterLeaderBoardScore: (params: { score: string }) => Promise<SubmitGameCenterLeaderBoardScoreResponse>;
 
   contactsViral: (params: ContactsViralParams) => () => void;

package/src/AppsInTossModule/native-modules/getUserKeyForGame.ts

@@ -0,0 +1,125 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { isMinVersionSupported } from './isMinVersionSupported';
+import { GAME_USER_KEY_MIN_VERSION } from '../constants';
+
+export interface GetUserKeyForGameSuccessResponse {
+  hash: string;
+  type: 'HASH';
+}
+
+export interface GetUserKeyForGameErrorResponse {
+  type: 'NOT_AVAILABLE';
+}
+
+export type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;
+
+/**
+ * @public
+ * @category 게임
+ * @name getUserKeyForGame
+ * @description
+ * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.
+ * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}
+ * 사용자 키 조회 결과를 반환해요.
+ * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
+ * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ *
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { getUserKeyForGame } from '@apps-in-toss/framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handlePress() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <Button onPress={handlePress} title="유저 키 가져오기" />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { getUserKeyForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GameUserKeyButton() {
+ *   async function handleClick() {
+ *       const result = await getUserKeyForGame();
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>유저 키 가져오기</button>
+ *   );
+ * }
+ * ```
+ */
+export async function getUserKeyForGame(): Promise<
+  GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined
+> {
+  const isSupported = isMinVersionSupported(GAME_USER_KEY_MIN_VERSION);
+
+  if (!isSupported) {
+    return;
+  }
+
+  try {
+    const response = await AppsInTossModule.getUserKeyForGame({});
+    if (response.type === 'HASH') {
+      return response;
+    }
+    if (response.type === 'NOT_AVAILABLE') {
+      return 'INVALID_CATEGORY';
+    }
+    return 'ERROR';
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  } catch (_) {
+    return 'ERROR';
+  }
+}

package/src/AppsInTossModule/native-modules/grantPromotionRewardForGame.ts

@@ -0,0 +1,165 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { isMinVersionSupported } from './isMinVersionSupported';
+import { GAME_PROMOTION_REWARD_MIN_VERSION } from '../constants';
+
+export interface GrantPromotionRewardForGameSuccessResponse {
+  key: string;
+}
+
+export interface GrantPromotionRewardForGameErrorResponse {
+  code: string;
+  [key: string]: any;
+}
+
+export interface GrantPromotionRewardForGameErrorResult {
+  errorCode: string;
+  message: string;
+}
+
+export type GrantPromotionRewardForGameResponse =
+  | GrantPromotionRewardForGameSuccessResponse
+  | GrantPromotionRewardForGameErrorResponse;
+
+type GrantPromotionRewardForGameResult =
+  | GrantPromotionRewardForGameResponse
+  | GrantPromotionRewardForGameErrorResult
+  | 'ERROR'
+  | undefined;
+
+function isGrantPromotionRewardForGameError(error: unknown): error is { code: string; message: string } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof (error as any).code === 'string' &&
+    'message' in error &&
+    typeof (error as any).message === 'string'
+  );
+}
+
+/**
+ * @public
+ * @category 게임
+ * @name grantPromotionRewardForGame
+ * @description
+ * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.
+ * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.
+ * @param {string} params.promotionCode - 프로모션 코드예요.
+ * @param {number} params.amount - 지급할 포인트 금액이에요.
+ * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}
+ * 포인트 지급 결과를 반환해요.
+ * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
+ * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.
+ *   - `"40000"`: 게임이 아닌 미니앱에서 호출했을 때
+ *   - `"4100"`: 프로모션 정보를 찾을 수 없을 때
+ *   - `"4104"`: 프로모션이 중지되었을 때
+ *   - `"4105"`: 프로모션이 종료되었을 때
+ *   - `"4108"`: 프로모션이 승인되지 않았을 때
+ *   - `"4109"`: 프로모션이 실행중이 아닐 때
+ *   - `"4110"`: 리워드를 지급/회수할 수 없을 때
+ *   - `"4112"`: 프로모션 머니가 부족할 때
+ *   - `"4113"`: 이미 지급/회수된 내역일 때
+ *   - `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과할 때
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handlePress() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return <Button onPress={handlePress} title="포인트 지급하기" />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // webview
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';
+ *
+ * function GrantRewardButton() {
+ *   async function handleClick() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
+ *
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>포인트 지급하기</button>
+ *   );
+ * }
+ * ```
+ */
+export async function grantPromotionRewardForGame({
+  params,
+}: {
+  params: { promotionCode: string; amount: number };
+}): Promise<GrantPromotionRewardForGameResult> {
+  const isSupported = isMinVersionSupported(GAME_PROMOTION_REWARD_MIN_VERSION);
+
+  if (!isSupported) {
+    return;
+  }
+
+  try {
+    const response = await AppsInTossModule.grantPromotionRewardForGame({ params });
+    if (response.key) {
+      return response;
+    }
+    return 'ERROR';
+  } catch (error) {
+    if (isGrantPromotionRewardForGameError(error)) {
+      return {
+        errorCode: error.code,
+        message: error.message,
+      };
+    }
+    return 'ERROR';
+  }
+}

package/src/AppsInTossModule/native-modules/index.ts

@@ -53,6 +53,8 @@ export * from './storage';
 export * from './openGameCenterLeaderboard';
 export * from './getGameCenterGameProfile';
 export * from './submitGameCenterLeaderBoardScore';
+export * from './getUserKeyForGame';
+export * from './grantPromotionRewardForGame';
 export * from '../native-event-emitter/contactsViral';
 export * from './appsInTossSignTossCert';
 

package/src/async-bridges.ts

@@ -28,3 +28,5 @@ export * from './AppsInTossModule/native-modules/appsInTossSignTossCert';
 export * from './AppsInTossModule/native-modules/getGameCenterGameProfile';
 export * from './AppsInTossModule/native-modules/openGameCenterLeaderboard';
 export * from './AppsInTossModule/native-modules/submitGameCenterLeaderBoardScore';
+export * from './AppsInTossModule/native-modules/getUserKeyForGame';
+export * from './AppsInTossModule/native-modules/grantPromotionRewardForGame';