web-launch-kit 0.0.7 → 0.0.8

package/README.ko.md

@@ -33,7 +33,8 @@ npm install web-launch-kit
 | `LaunchKit.map(options?)` | `Promise<AppOpenedBy>` | 검색어·좌표·경로로 지도 열기. OS별 네이티브 앱과 Google Maps 웹 폴백 |
 | `LaunchKit.filepicker(options?)` | `Promise<File[]>` | 파일 또는 디렉터리 선택 (File System Access API, input 폴백) |
 | `LaunchKit.setting(type?)` | `Promise<void>` | 지원되는 환경에서 시스템 설정 화면 열기 |
-| `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` getter와 비동기 `getTrackId` / `getProductId` |
+| `LaunchKit.escapeWebview(options?)` | `Promise<void>` | URL(기본값은 현재 페이지)을 외부 브라우저에서 다시 열어 인앱 웹뷰에서 탈출 |
+| `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` / `canEscapeWebview` getter와 비동기 `getTrackId` / `getProductId` |
 
 `AppOpenedBy`는 `"scheme"`, `"universal"`, `"intent"`, `"fallback"`, `"store"` 중 하나입니다.
 
@@ -82,8 +83,8 @@ LaunchKit.telephone({ to: '+821012345678' })
 
 싱글톤의 형태는 `LaunchKitInstance`로 export되고, 모든 옵션 객체에 이름이 붙어 있습니다 —
 `AppOpenOptions`, `AndroidAppInfo`, `IOSAppInfo`, `WindowsAppInfo`, `MacOSAppInfo`,
-`TelephoneOptions`, `MessageOptions`, `MailOptions`, `MapOptions`, `FilepickerOptions`.
-`SettingType`은 값 export이고 `AppOpenedBy`는 타입입니다.
+`TelephoneOptions`, `MessageOptions`, `MailOptions`, `MapOptions`, `FilepickerOptions`,
+`EscapeWebviewOptions`. `SettingType`은 값 export이고 `AppOpenedBy`는 타입입니다.
 
 ```ts
 import LaunchKit, {
@@ -313,6 +314,32 @@ if (LaunchKit.utils.canOpenSetting) {
 }
 ```
 
+## 인앱 브라우저 탈출
+
+`escapeWebview()`는 URL — 기본값은 현재 페이지 — 을 외부 기본 브라우저에서 다시 열어,
+페이지가 갇혀 있는 인앱 웹뷰에서 탈출합니다.
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+if (LaunchKit.utils.canEscapeWebview) {
+  await LaunchKit.escapeWebview()
+}
+
+// 현재 페이지 대신 특정 URL을 내보낼 수도 있습니다
+await LaunchKit.escapeWebview({ url: 'https://example.com/checkout' })
+```
+
+경로는 환경에 따라 결정됩니다. 카카오톡은 전용 `kakaotalk://web/openExternal` 스킴을
+제공하고, LINE은 공식 문서화된 `openExternalBrowser=1` 쿼리 파라미터를 지원합니다 —
+둘 다 안드로이드와 iOS에서 동작합니다. 그 외 웹뷰는 OS 경로로 폴백합니다. 안드로이드는
+Chrome을 고정한 `intent://` URL(원본 URL이 `S.browser_fallback_url`로 실려서 Chrome이
+없는 기기는 제자리에 머뭅니다), iOS는 비공개 `x-safari-` 스킴입니다 — iOS 15와 17+에서
+동작하고 16에서는 동작하지 않으며, 기본 브라우저 설정과 무관하게 항상 Safari를 열고,
+Meta 계열 웹뷰(Facebook, Instagram) 안에서는 차단됩니다. http(s) URL만 다시 열 수
+있습니다. 웹뷰 밖이거나 사용 가능한 경로가 없으면(완전 차단 웹뷰, iOS 16, 데스크톱)
+프로미스가 reject됩니다 — 버튼 노출은 `utils.canEscapeWebview`로 게이트하세요.
+
 ---
 
 ## 참고

package/README.md

@@ -34,7 +34,8 @@ The bundle is self-contained (OS/locale detection is inlined) — no peer script
 | `LaunchKit.map(options?)` | `Promise<AppOpenedBy>` | Open a map by query, coordinate, or directions; native app per-OS with a Google Maps web fallback |
 | `LaunchKit.filepicker(options?)` | `Promise<File[]>` | Pick files or a directory (File System Access API, with input fallback) |
 | `LaunchKit.setting(type?)` | `Promise<void>` | Open a system-settings pane where supported |
-| `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` getters, plus async `getTrackId` / `getProductId` |
+| `LaunchKit.escapeWebview(options?)` | `Promise<void>` | Reopen a URL (the current page by default) in the external browser, escaping an in-app webview |
+| `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` / `canEscapeWebview` getters, plus async `getTrackId` / `getProductId` |
 
 `AppOpenedBy` is one of: `"scheme"`, `"universal"`, `"intent"`, `"fallback"`, `"store"`.
 
@@ -84,7 +85,8 @@ The global `LaunchKit` is a namespace object; the singleton is `LaunchKit.defaul
 The singleton shape is exported as `LaunchKitInstance`, and every option object has a
 named type: `AppOpenOptions`, `AndroidAppInfo`, `IOSAppInfo`, `WindowsAppInfo`,
 `MacOSAppInfo`, `TelephoneOptions`, `MessageOptions`, `MailOptions`, `MapOptions`,
-`FilepickerOptions`. `SettingType` is a value export; `AppOpenedBy` is a type.
+`FilepickerOptions`, `EscapeWebviewOptions`. `SettingType` is a value export;
+`AppOpenedBy` is a type.
 
 ```ts
 import LaunchKit, {
@@ -316,6 +318,34 @@ if (LaunchKit.utils.canOpenSetting) {
 }
 ```
 
+## Escaping in-app browsers
+
+`escapeWebview()` reopens a URL — the current page by default — in the external
+default browser, escaping the in-app webview the page is trapped in.
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+if (LaunchKit.utils.canEscapeWebview) {
+  await LaunchKit.escapeWebview()
+}
+
+// Or send a specific URL out instead of the current page
+await LaunchKit.escapeWebview({ url: 'https://example.com/checkout' })
+```
+
+The route depends on the environment. KakaoTalk exposes a dedicated
+`kakaotalk://web/openExternal` scheme and LINE honors the documented
+`openExternalBrowser=1` query parameter — both work on Android and iOS. Other
+webviews fall back to the OS route: a Chrome-pinned `intent://` URL on Android
+(the original URL rides along as `S.browser_fallback_url`, so a Chrome-less
+device stays in place), and the undocumented `x-safari-` scheme on iOS — which
+works on iOS 15 and 17+ but not 16, always opens Safari regardless of the
+default browser, and is blocked inside Meta's webviews (Facebook, Instagram).
+Only http(s) URLs can be reopened. Outside a webview, or where no route is
+available (hard-blocked webviews, iOS 16, desktop), the promise rejects — gate
+the button on `utils.canEscapeWebview`.
+
 ---
 
 ## Notes

package/dist/index.d.ts

@@ -93,10 +93,14 @@ declare interface MapOptions {
     fallback?: URLStringOrFallback;
     onAttempt?: (attempt: LaunchAttempt) => void;
 }
+declare interface EscapeWebviewOptions {
+    url?: URLCandidate;
+}
 interface LaunchKitUtils {
     get canOpenIntent(): boolean;
     get canOpenUniversal(): boolean;
     get canOpenSetting(): boolean;
+    get canEscapeWebview(): boolean;
     getTrackId(bundleId: string): Promise<string | undefined>;
     getProductId(packageFamilyName: string): Promise<string | undefined>;
 }
@@ -113,8 +117,9 @@ interface LaunchKitInstance {
     map(options?: MapOptions): Promise<AppOpenedBy>;
     filepicker(options?: FilepickerOptions): Promise<File[]>;
     setting(type?: SettingType): Promise<void>;
+    escapeWebview(options?: EscapeWebviewOptions): Promise<void>;
 }
 declare const LaunchKit: LaunchKitInstance;
 
 export { SettingType, LaunchKit as default };
-export type { AndroidAppInfo, AppInfo, AppOpenOptions, AppOpenedBy, FilepickerOptions, IOSAppInfo, LaunchAttempt, LaunchError, LaunchErrorCode, LaunchKitInstance, MacOSAppInfo, MailOptions, MapOptions, MessageOptions, OpenPickerStartIn, TelephoneOptions, WindowsAppInfo };
+export type { AndroidAppInfo, AppInfo, AppOpenOptions, AppOpenedBy, EscapeWebviewOptions, FilepickerOptions, IOSAppInfo, LaunchAttempt, LaunchError, LaunchErrorCode, LaunchKitInstance, MacOSAppInfo, MailOptions, MapOptions, MessageOptions, OpenPickerStartIn, TelephoneOptions, WindowsAppInfo };

package/dist/launch-kit.cjs

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var version$3 = "0.0.7";
+var version$3 = "0.0.8";
 var packageJSON$3 = {
 	version: version$3};
 
@@ -2526,6 +2526,34 @@ function isFullyBlockedInAppBrowser() {
 function isPartnerAppOnly() {
     return /weibo.*weibo__[\d.]+/i.test(PlatformKit.userAgent);
 }
+function canOpenXSafari() {
+    if (PlatformKit.os.name !== 'ios')
+        return false;
+    var version = PlatformKit.os.version;
+    if (PlatformKit.compareVersion(version, '15.0') < 0)
+        return false;
+    if (PlatformKit.compareVersion(version, '16.0') >= 0 && PlatformKit.compareVersion(version, '17.0') < 0)
+        return false;
+    var inAppBrowser = PlatformKit.inAppBrowser;
+    if (inAppBrowser === 'facebook' || inAppBrowser === 'instagram')
+        return false;
+    return canOpenScheme();
+}
+function isInWebview() {
+    return PlatformKit.inAppBrowser !== null || PlatformKit.webview;
+}
+function canEscapeWebview() {
+    if (!isInWebview())
+        return false;
+    var inAppBrowser = PlatformKit.inAppBrowser;
+    if (inAppBrowser === 'kakaotalk' || inAppBrowser === 'line')
+        return true;
+    if (PlatformKit.os.name === 'android')
+        return canOpenIntent();
+    if (PlatformKit.os.name === 'ios')
+        return canOpenXSafari();
+    return false;
+}
 function canOpenWindowsSetting(version) {
     if (version.length === 0)
         return false;
@@ -2623,6 +2651,24 @@ function createWebStoreURL(id, os) {
             return os;
     }
 }
+function appendURLParameter(url, parameter) {
+    var index = url.indexOf('#');
+    var base = index === -1 ? url : url.substring(0, index);
+    var hash = index === -1 ? '' : url.substring(index);
+    return base + (base.indexOf('?') === -1 ? '?' : '&') + parameter + hash;
+}
+function createEscapeWebviewURL(url) {
+    var inAppBrowser = PlatformKit.inAppBrowser;
+    if (inAppBrowser === 'kakaotalk')
+        return 'kakaotalk://web/openExternal?url=' + escapeURIComponentString(url);
+    if (inAppBrowser === 'line')
+        return appendURLParameter(url, 'openExternalBrowser=1');
+    if (PlatformKit.os.name === 'android' && canOpenIntent())
+        return createIntentURL(url, 'com.android.chrome', url);
+    if (PlatformKit.os.name === 'ios' && canOpenXSafari())
+        return 'x-safari-' + url;
+    return undefined;
+}
 function escapeURIComponentString(value) {
     return encodeURIComponent(value)
         .replace(/[!'()*]/g, function (char) {
@@ -2896,6 +2942,9 @@ var LaunchKit = {
         get canOpenSetting() {
             return canOpenSetting();
         },
+        get canEscapeWebview() {
+            return canEscapeWebview();
+        },
         getTrackId: getTrackIdAsync,
         getProductId: getProductIdAsync,
     },
@@ -3163,6 +3212,18 @@ var LaunchKit = {
             return openURLSequential();
         });
     },
+    escapeWebview: function (options) {
+        if (options === void 0) { options = {}; }
+        if (!isInWebview())
+            return Promise.reject(new Error('Escaping the webview is not needed: the current environment is not an in-app browser or webview. (userAgent: "' + PlatformKit.userAgent + '")'));
+        var url = typeof options.url !== 'undefined' ? stripURL(options.url) : getTopmostWindow().location.href;
+        if (!isWebURL(url))
+            return Promise.reject(new Error('Cannot escape the webview: only http(s) URLs can be reopened in an external browser. (url: "' + url + '")'));
+        var escape = createEscapeWebviewURL(url);
+        if (typeof escape === 'undefined')
+            return Promise.reject(new Error('Failed to escape the webview: no escape route is available in the current environment. (userAgent: "' + PlatformKit.userAgent + '")'));
+        return openURL(0, escape, getDefaultTimeout(), isWebURL(escape));
+    },
 };
 
 exports.default = LaunchKit;