@apps-in-toss/web-framework 0.0.21 → 0.0.23

package/dist-web/index.d.ts

@@ -1,71 +1,6 @@
-export * from './bridge'
-/**
- * 비동기 브릿지 함수 생성
- * @param method 호출할 메서드 이름
- * @returns args를 받아 Promise를 반환하는 함수
- * @typeParam T: 인자로 전달할 데이터 타입
- * @typeParam R: resolve 시 반환될 데이터 타입 (기본 any)
- * @example
- * // 카메라 열기 브릿지 함수 생성
- * const openCamera = createAsyncBridge<{base64: boolean}, { dataUri: string }>('openCamera');
- *
- * // 사용 예시
- * async function takePicture() {
- *   try {
- *     const result = await openCamera();
- *     console.log('카메라로 찍은 이미지 URL:', result.dataUri);
- *   } catch (error) {
- *     console.error('카메라 오류:', error);
- *   }
- * }
- */
-declare function createAsyncBridge<T extends any[], R = any>(method: string): (...args: T) => Promise<R>;
-
-/**
- * 상수 브릿지 함수 생성
- * @param method 호출할 상수 핸들러 이름
- * @returns 상수 값을 반환하는 함수
- * @typeParam T: 상수 값의 타입
- * @example
- * // 디바이스 ID를 가져오는 상수 브릿지 생성
- * const getDeviceId = createConstantBridge<string>('getDeviceId');
- *
- * // 사용 예시
- * function displayDeviceInfo() {
- *   const deviceId = getDeviceId();
- *   console.log('디바이스 ID:', deviceId);
- * }
- */
-declare function createConstantBridge<T>(method: string): () => T;
-
-/**
- * 이벤트 브릿지 함수 생성
- * @param method 호출할 이벤트 핸들러 이름
- * @returns 이벤트 및 에러 핸들러를 포함한 객체를 받아 리스너 해제 함수를 반환하는 함수
- * @typeParam T: 이벤트 관련 추가 옵션 등의 타입
- * @example
- * // 위치 추적 이벤트 브릿지 생성
- * const startUpdatingLocation = createEventBridge<{ interval: number }>('startUpdatingLocation');
- *
- * // 사용 예시
- * const unsubscribe = startUpdatingLocation({
- *   options: { interval: 1000 }, // 1초마다 위치 업데이트
- *   onEvent: (location) => {
- *     console.log('현재 위치:', location.latitude, location.longitude);
- *   },
- *   onError: (error) => {
- *     console.error('위치 추적 오류:', error);
- *   }
- * });
- *
- * // 위치 추적 중단
- * unsubscribe();
- */
-declare function createEventBridge<TOptions, TData>(method: string): (args: {
-    onEvent: (data: TData) => void;
-    onError: (error: Error) => void;
-    options?: TOptions;
-}) => () => void;
+export * from './bridge';
+export * from '@apps-in-toss/bridge-core';
+import { LoadAdMobInterstitialAdOptions, ShowAdMobInterstitialAdOptions, LoadAdMobRewardedAdOptions, ShowAdMobRewardedAdOptions } from '@apps-in-toss/framework';
 
 /**
  * @public
@@ -152,6 +87,291 @@ declare function getSafeAreaInsets(): {
     bottom: number;
 };
 
+declare const GoogleAdMob: {
+    /**
+     * @public
+     * @category 광고
+     * @name loadAdMobInterstitialAd
+     * @description 앱 화면 전체를 덮는 전면 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.
+     * @param {LoadAdMobInterstitialAdParams} params 광고를 불러올 때 사용할 설정 값이에요. 광고 ID와 광고의 동작에 대한 콜백을 설정할 수 있어요.
+     * @param {LoadAdMobInterstitialAdOptions} params.options 광고를 불러올 때 전달할 옵션 객체예요.
+     * @param {string} params.options.adUnitId 광고 단위 ID예요. 발급받은 전면 광고용 ID를 입력해요.
+     * @param {(event: LoadAdMobInterstitialAdEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고가 닫히거나 클릭됐을 때). 자세한 이벤트 타입은 [LoadAdMobInterstitialAdEvent](/react-native/reference/framework/광고/LoadAdMobInterstitialAdEvent.html)를 참고하세요.
+     * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+     * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+     *
+     * @example
+     * ### 뷰 진입 시 전면광고 불러오기
+     * ```tsx
+     * import { GoogleAdMob } from '@apps-in-toss/framework';
+     * import { useEffect } from 'react';
+     * import { View, Text } from 'react-native';
+     *
+     * const AD_UNIT_ID = '<YOUR_AD_UNIT_ID>';
+     *
+     * function Page() {
+     *   useEffect(() => {
+     *     if (GoogleAdMob.loadAdMobInterstitialAd.isSupported() !== true) {
+     *       return;
+     *     }
+     *
+     *     const cleanup = GoogleAdMob.loadAdMobInterstitialAd({
+     *       options: {
+     *         adUnitId: AD_UNIT_ID,
+     *       },
+     *       onEvent: (event) => {
+     *         switch (event.type) {
+     *           case 'loaded':
+     *             console.log('광고 로드 성공', event.data);
+     *             break;
+     *
+     *           case 'clicked':
+     *             console.log('광고 클릭');
+     *             break;
+     *
+     *           case 'dismissed':
+     *             console.log('광고 닫힘');
+     *             break;
+     *
+     *           case 'failedToShow':
+     *             console.log('광고 보여주기 실패');
+     *             break;
+     *
+     *           case 'impression':
+     *             console.log('광고 노출');
+     *             break;
+     *
+     *           case 'show':
+     *             console.log('광고 컨텐츠 보여졌음');
+     *             break;
+     *         }
+     *       },
+     *       onError: (error) => {
+     *         console.error('광고 불러오기 실패', error);
+     *       },
+     *     });
+     *
+     *     return cleanup;
+     *   }, []);
+     *
+     *   return (
+     *     <View>
+     *       <Text>Page</Text>
+     *     </View>
+     *   );
+     * }
+     * ```
+     */
+    loadAdMobInterstitialAd: ((args: {
+        onEvent: (data: void) => void;
+        onError: (error: Error) => void;
+        options?: LoadAdMobInterstitialAdOptions | undefined;
+    }) => () => void) & {
+        isSupported: () => boolean;
+    };
+    /**
+     * @public
+     * @category 광고
+     * @name showAdMobInterstitialAd
+     * @description 앱 화면 전체를 덮는 전면 광고를 사용자에게 노출해요. 이 함수는 `loadAdMobInterstitialAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.
+     * @param {ShowAdMobInterstitialAdParams} params 광고를 보여주기 위해 사용할 설정 값이에요. 광고 ID와과 광고의 동작에 대한 콜백을 설정할 수 있어요.
+     * @param {ShowAdMobInterstitialAdOptions} params.options 광고를 보여줄 때 전달할 옵션 객체예요.
+     * @param {string} params.options.adUnitId 광고 단위 ID예요. `loadAdMobInterstitialAd` 로 불러온 전면 광고용 ID를 입력해요.
+     * @param {(event: ShowAdMobInterstitialAdEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고 노출을 요청했을 때). 자세한 이벤트 타입은 [ShowAdMobInterstitialAdEvent](/react-native/reference/framework/광고/ShowAdMobInterstitialAdEvent.html)를 참고하세요.
+     * @param {(reason: unknown) => void} [params.onError] 광고를 노출하지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+     * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+     *
+     * @example
+     * ### 버튼 눌러 불러온 전면 광고 보여주기
+     * ```tsx
+     * import { GoogleAdMob } from '@apps-in-toss/framework';
+     * import { View, Text, Button } from 'react-native';
+     *
+     * const AD_UNIT_ID = '<YOUR_AD_UNIT_ID>';
+     *
+     * function Page() {
+     *   const handlePress = () => {
+     *     if (GoogleAdMob.showAdMobInterstitialAd.isSupported() !== true) {
+     *       return;
+     *     }
+     *
+     *     GoogleAdMob.showAdMobInterstitialAd({
+     *       options: {
+     *         adUnitId: AD_UNIT_ID,
+     *       },
+     *       onEvent: (event) => {
+     *         switch (event.type) {
+     *           case 'requested':
+     *             console.log('광고 보여주기 요청 완료');
+     *             break;
+     *         }
+     *       },
+     *       onError: (error) => {
+     *         console.error('광고 보여주기 실패', error);
+     *       },
+     *     });
+     *   }
+     *
+     *   return (
+     *     <Button onPress={handlePress}>
+     *       <Text>광고 보기</Text>
+     *     </Button>
+     *   );
+     * }
+     * ```
+     */
+    showAdMobInterstitialAd: ((args: {
+        onEvent: (data: void) => void;
+        onError: (error: Error) => void;
+        options?: ShowAdMobInterstitialAdOptions | undefined;
+    }) => () => void) & {
+        isSupported: () => boolean;
+    };
+    /**
+     * @public
+     * @category 광고
+     * @name loadAdMobRewardedAd
+     * @description 사용자가 광고를 끝까지 시청하면 리워드를 제공할 수 있는 보상형 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.
+     * @param {LoadAdMobRewardedAdParams} params 광고를 불러올 때 사용할 설정 값이에요. 광고 ID와 광고의 동작에 대한 콜백을 설정할 수 있어요.
+     * @param {LoadAdMobRewardedAdOptions} params.options 광고를 불러올 때 전달할 옵션 객체예요.
+     * @param {string} params.options.adUnitId 광고 단위 ID예요. 발급받은 보상형 광고용 ID를 입력해요.
+     * @param {(event: LoadAdMobRewardedAdEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고가 닫히거나 클릭됐을 때). 자세한 이벤트 타입은 [LoadAdMobRewardedAdEvent](/react-native/reference/framework/광고/LoadAdMobRewardedAdEvent.html)를 참고하세요.
+     * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+     * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+     *
+     * @example
+     * ### 뷰 진입 시 보상형 광고 불러오기
+     * ```tsx
+     * import { GoogleAdMob } from '@apps-in-toss/framework';
+     * import { useEffect } from 'react';
+     * import { View, Text } from 'react-native';
+     *
+     * const AD_UNIT_ID = '<YOUR_AD_UNIT_ID>';
+     *
+     * function Page() {
+     *   useEffect(() => {
+     *     if (GoogleAdMob.loadAdMobRewardedAd.isSupported() !== true) {
+     *       return;
+     *     }
+     *
+     *     const cleanup = GoogleAdMob.loadAdMobRewardedAd({
+     *       options: {
+     *         adUnitId: AD_UNIT_ID,
+     *       },
+     *       onEvent: (event) => {
+     *         switch (event.type) {
+     *           case 'loaded':
+     *             console.log('광고 로드 성공', event.data);
+     *             break;
+     *
+     *           case 'clicked':
+     *             console.log('광고 클릭');
+     *             break;
+     *
+     *           case 'dismissed':
+     *             console.log('광고 닫힘');
+     *             break;
+     *
+     *           case 'failedToShow':
+     *             console.log('광고 보여주기 실패');
+     *             break;
+     *
+     *           case 'impression':
+     *             console.log('광고 노출');
+     *             break;
+     *
+     *           case 'show':
+     *             console.log('광고 컨텐츠 보여졌음');
+     *             break;
+     *
+     *           case 'userEarnedReward':
+     *             console.log('사용자가 광고 시청을 완료했음');
+     *             break;
+     *         }
+     *       },
+     *       onError: (error) => {
+     *         console.error('광고 불러오기 실패', error);
+     *       },
+     *     });
+     *
+     *     return cleanup;
+     *   }, []);
+     *
+     *   return (
+     *     <View>
+     *       <Text>Page</Text>
+     *     </View>
+     *   );
+     * }
+     * ```
+     */
+    loadAdMobRewardedAd: ((args: {
+        onEvent: (data: void) => void;
+        onError: (error: Error) => void;
+        options?: LoadAdMobRewardedAdOptions | undefined;
+    }) => () => void) & {
+        isSupported: () => boolean;
+    };
+    /**
+     * @public
+     * @category 광고
+     * @name showAdMobRewardedAd
+     * @description 사용자가 광고를 끝까지 보면 리워드를 받을 수 있도록, 보상형 광고를 화면에 보여줘요. 이 함수는 `loadAdMobRewardedAd` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.
+     * @param {ShowAdMobRewardedAdParams} params 광고를 보여주기 위해 사용할 설정 값이에요. 광고 ID와 광고의 동작에 대한 콜백을 설정할 수 있어요.
+     * @param {ShowAdMobRewardedAdOptions} params.options 광고를 보여줄 때 전달할 옵션 객체예요.
+     * @param {string} params.options.adUnitId 광고 단위 ID예요. `loadAdMobRewardedAd` 로 불러온 보상형 광고용 ID를 입력해요.
+     * @param {(event: ShowAdMobRewardedAdEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고 노출을 요청했을 때). 자세한 이벤트 타입은 [ShowAdMobRewardedAdEvent](/react-native/reference/framework/광고/ShowAdMobRewardedAdEvent.html)를 참고하세요.
+     * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+     * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+     *
+     * @example
+     * ### 버튼 눌러 불러온 보상형 광고 보여주기
+     * ```tsx
+     * import { GoogleAdMob } from '@apps-in-toss/framework';
+     * import { View, Text, Button } from 'react-native';
+     *
+     * const AD_UNIT_ID = '<YOUR_AD_UNIT_ID>';
+     *
+     * function Page() {
+     *   const handlePress = () => {
+     *     if (GoogleAdMob.showAdMobRewardedAd.isSupported() !== true) {
+     *       return;
+     *     }
+     *
+     *     GoogleAdMob.showAdMobRewardedAd({
+     *       options: {
+     *         adUnitId: AD_UNIT_ID,
+     *       },
+     *       onEvent: (event) => {
+     *         switch (event.type) {
+     *           case 'requested':
+     *             console.log('광고 보여주기 요청 완료');
+     *             break;
+     *         }
+     *       },
+     *       onError: (error) => {
+     *         console.error('광고 보여주기 실패', error);
+     *       },
+     *     });
+     *   }
+     *
+     *   return (
+     *     <Button onPress={handlePress}>
+     *       <Text>광고 보기</Text>
+     *     </Button>
+     *   );
+     * }
+     * ```
+     */
+    showAdMobRewardedAd: ((args: {
+        onEvent: (data: void) => void;
+        onError: (error: Error) => void;
+        options?: ShowAdMobRewardedAdOptions | undefined;
+    }) => () => void) & {
+        isSupported: () => boolean;
+    };
+};
+
 type BedrockEvent = {
     backEvent: {
         onEvent: () => void;
@@ -167,4 +387,62 @@ declare const bedrockEvent: {
     }) => () => void;
 };
 
-export { type BedrockEvent, Storage, bedrockEvent, createAsyncBridge, createConstantBridge, createEventBridge, getSafeAreaInsets };
+/**
+ * @public
+ * @category 환경 확인
+ * @kind function
+ * @name isMinVersionSupported
+ * @description
+ * 현재 토스 앱 버전이 지정한 최소 버전 이상인지 확인해요.
+ *
+ * 이 함수는 현재 실행 중인 토스 앱의 버전이 파라미터로 전달된 최소 버전 요구사항을 충족하는지 확인해요. 특정 기능이 최신 버전에서만 동작할 때, 사용자에게 앱 업데이트를 안내할 수 있어요.
+ *
+ * @param {Object} minVersions 플랫폼별 최소 버전 요구사항을 지정하는 객체예요.
+ * @param {(`${number}.${number}.${number}` | 'always' | 'never')} minVersions.android 안드로이드 플랫폼의 최소 버전 요구사항이에요.
+ * @param {(`${number}.${number}.${number}` | 'always' | 'never')} minVersions.ios iOS 플랫폼의 최소 버전 요구사항이에요.
+ * @returns {boolean} 현재 앱 버전이 최소 버전 이상이면 true, 그렇지 않으면 false를 반환해요.
+ *
+ * @example
+ * ### 앱 버전 확인하기
+ *
+ * ```tsx
+ * import { isMinVersionSupported } from '@apps-in-toss/framework';
+ * import { Text, View } from 'react-native';
+ *
+ * function VersionCheck() {
+ *   const isSupported = isMinVersionSupported({
+ *     android: '1.2.0',
+ *     ios: '1.3.0'
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       {!isSupported && (
+ *         <Text>최신 버전으로 업데이트가 필요해요.</Text>
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+declare function isMinVersionSupported(minVersions: {
+    android: `${number}.${number}.${number}` | 'always' | 'never';
+    ios: `${number}.${number}.${number}` | 'always' | 'never';
+}): boolean;
+
+type AppsInTossEvent = {
+    entryMessageExited: {
+        onEvent: () => void;
+        onError?: (error: Error) => void;
+        options: undefined;
+    };
+};
+declare const appsInTossEvent: {
+    addEventListener: <K extends keyof AppsInTossEvent>(event: K, { onEvent, onError, options, }: {
+        onEvent: AppsInTossEvent[K]["onEvent"];
+        onError?: AppsInTossEvent[K]["onError"] | undefined;
+        options?: AppsInTossEvent[K]["options"] | undefined;
+    }) => () => void;
+};
+
+export { type AppsInTossEvent, type BedrockEvent, GoogleAdMob, Storage, appsInTossEvent, bedrockEvent, getSafeAreaInsets, isMinVersionSupported };