web-launch-kit 0.0.6 → 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, {
@@ -119,10 +120,10 @@ flowchart TD
         A1{"intent given, but scheme /<br/>packageName / fallback missing?"}
         A1 -->|yes| A2["parseIntentURL:<br/>derive scheme · packageName · fallback"]
         A1 -->|no| A3
-        A2 --> A3{"scheme given, but intent missing?"}
+        A2 --> A3{"allowIntent, and scheme given<br/>but intent missing?"}
         A3 -->|yes| A4["createIntentURL:<br/>scheme + packageName + fallback"]
         A3 -->|no| A5
-        A4 --> A5["Priority list:<br/>intent (if canOpenIntent) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
+        A4 --> A5["Priority list:<br/>intent (if allowIntent and canOpenIntent) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
     end
 
     subgraph IOS["ios · resolveOptions"]
@@ -202,8 +203,8 @@ const openedBy = await LaunchKit.app({
 console.log(openedBy) // "universal" | "scheme" | "intent" | "fallback" | "store"
 ```
 
-플랫폼별 필드: 안드로이드는 `intent` / `scheme` / `packageName` / `fallback`(scheme ⇄ intent는
-서로에게서 유도됩니다), iOS는 `universal` / `scheme` / `bundleId` / `trackId`, Windows는
+플랫폼별 필드: 안드로이드는 `intent` / `scheme` / `packageName` / `fallback` /
+`allowIntent`(scheme ⇄ intent는 서로에게서 유도됩니다), iOS는 `universal` / `scheme` / `bundleId` / `trackId`, Windows는
 `scheme` / `packageFamilyName` / `productId`, macOS는 `scheme` / `bundleId` / `trackId`를
 받습니다. 모두 `fallback`, `timeout`, `allowAppStore`, `allowWebStore`를 함께 받습니다.
 
@@ -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`로 게이트하세요.
+
 ---
 
 ## 참고
@@ -333,6 +360,13 @@ if (LaunchKit.utils.canOpenSetting) {
   그리고 파트너가 아닌 웨이보) 안에서는 커스텀 스킴·`intent://`·`market://` 같은 스토어 스킴이
   타임아웃을 소진하지 않고 미리 제외됩니다. 그래서 체인이 곧바로 `fallback` / 웹스토어로
   떨어집니다. 화이트리스트에 등록된 파트너 앱은 `assumeAllowedInApp: true`로 되돌립니다.
+- **`allowIntent: false`는 안드로이드의 `intent://` 경로를 제외합니다.** 유도된 `intent://`에는
+  `S.browser_fallback_url`이 실립니다 — `fallback`에 URL을 주면 그 URL, 아니면 `packageName`이
+  있을 때 스토어입니다. 그래서 그 이동은 브라우저가 첫 시도 안에서 직접 처리합니다. 앱이 없는
+  사용자를 스토어로 보내는 가장 빠른 경로지만, 동시에 첫 시도가 항상 어딘가에 도달하므로 그
+  뒤의 순수 스킴은 실행되지 않습니다. `allowIntent: false`로 이 경로를 아예 건너뛰면 순서를
+  체인이 결정합니다 — 스킴, `fallback`, 그리고 허용한 스토어 순입니다. 직접 넘긴 `intent`도 같이
+  제외되지만, 거기서 파싱한 scheme·`packageName`·`fallback`은 그대로 사용됩니다.
 - **`map()`은 각 후보에 OS별 타임아웃**을 사용하고, `app()`처럼 성공한 경로를 반환합니다.
 - **웹 폴백은 내비게이션 시점에 resolve합니다.** `fallback`이나 웹스토어 후보는 문서 자체를
   교체하므로 기다릴 앱 전환이 없습니다. 이동을 시작하는 즉시 resolve하며, 이동이 성공한 뒤에

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, {
@@ -120,10 +122,10 @@ flowchart TD
         A1{"intent given, but scheme /<br/>packageName / fallback missing?"}
         A1 -->|yes| A2["parseIntentURL:<br/>derive scheme · packageName · fallback"]
         A1 -->|no| A3
-        A2 --> A3{"scheme given, but intent missing?"}
+        A2 --> A3{"allowIntent, and scheme given<br/>but intent missing?"}
         A3 -->|yes| A4["createIntentURL:<br/>scheme + packageName + fallback"]
         A3 -->|no| A5
-        A4 --> A5["Priority list:<br/>intent (if canOpenIntent) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
+        A4 --> A5["Priority list:<br/>intent (if allowIntent and canOpenIntent) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
     end
 
     subgraph IOS["ios · resolveOptions"]
@@ -203,8 +205,8 @@ const openedBy = await LaunchKit.app({
 console.log(openedBy) // "universal" | "scheme" | "intent" | "fallback" | "store"
 ```
 
-Per-platform fields: Android accepts `intent` / `scheme` / `packageName` / `fallback`
-(scheme ⇄ intent are derived from each other); iOS accepts `universal` / `scheme` /
+Per-platform fields: Android accepts `intent` / `scheme` / `packageName` / `fallback` /
+`allowIntent` (scheme ⇄ intent are derived from each other); iOS accepts `universal` / `scheme` /
 `bundleId` / `trackId`; Windows accepts `scheme` / `packageFamilyName` / `productId`;
 macOS accepts `scheme` / `bundleId` / `trackId`. All accept `fallback`, `timeout`,
 `allowAppStore`, `allowWebStore`. 
@@ -216,7 +218,7 @@ UI — there is otherwise nothing on screen for the length of the timeout.
 await LaunchKit.app({
   android: { scheme: 'myapp://profile/42', packageName: 'com.example.myapp', allowWebStore: true },
   onAttempt({ by, index, total }) {
-    setStatus(by === 'store' ? '스토어로 이동합니다' : '앱을 여는 중… (' + (index + 1) + '/' + total + ')')
+    setStatus(by === 'store' ? 'Go to the store' : 'Opening the app… (' + (index + 1) + '/' + total + ')')
   },
 })
 ```
@@ -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
@@ -338,6 +368,14 @@ if (LaunchKit.utils.canOpenSetting) {
   burning their timeouts, so the chain falls straight through to `fallback` / web store
   (the only routes that work there). Whitelisted partner apps opt back in with
   `assumeAllowedInApp: true`.
+- **`allowIntent: false` drops the Android `intent://` route.** A derived `intent://` carries
+  `S.browser_fallback_url` — your `fallback` when you gave a URL, otherwise the store when a
+  `packageName` is present — so the browser handles that hop itself during the first attempt.
+  That is the fastest route to the store for a user without the app, but it also means the
+  first attempt always lands somewhere, and the plain scheme behind it never runs. Set
+  `allowIntent: false` to skip the route entirely and let the chain decide the order: scheme,
+  then `fallback`, then the store you allowed. An explicit `intent` is gated too, though the
+  scheme, `packageName` and `fallback` parsed out of it are still used.
 - **`map()` uses the per-OS timeout** for each candidate, and resolves with the route that
   worked just like `app()`.
 - **Web fallbacks resolve on navigation.** A `fallback` or web-store candidate replaces the

package/dist/index.d.ts

@@ -36,6 +36,7 @@ declare interface AppInfo {
 declare interface AndroidAppInfo extends AppInfo {
     intent?: URLCandidate;
     packageName?: string;
+    allowIntent?: boolean;
     assumeAllowedInApp?: boolean;
 }
 declare interface IOSAppInfo extends AppInfo {
@@ -92,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>;
 }
@@ -112,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.6";
+var version$3 = "0.0.8";
 var packageJSON$3 = {
 	version: version$3};
 
@@ -2347,6 +2347,7 @@ function resolveOptions(option) {
     var timeout;
     var intent;
     var packageName;
+    var allowIntent = true;
     var bundleId;
     var trackId;
     var universal;
@@ -2356,6 +2357,7 @@ function resolveOptions(option) {
         case 'android':
             if (typeof option.android === 'undefined')
                 return [[], 0];
+            allowIntent = option.android.allowIntent !== false;
             intent = stripURL(option.android.intent);
             scheme = stripURL(option.android.scheme);
             fallback = stripURL(option.android.fallback);
@@ -2374,11 +2376,11 @@ function resolveOptions(option) {
                 if (typeof parsed.fallback !== 'undefined' && typeof fallback === 'undefined')
                     fallback = parsed.fallback;
             }
-            if (typeof scheme !== 'undefined' && typeof intent === 'undefined')
+            if (allowIntent && typeof scheme !== 'undefined' && typeof intent === 'undefined')
                 intent = createIntentURL(scheme, packageName, fallback);
             if (typeof timeout === 'undefined')
                 timeout = ANDROID_DEFAULT_TIMEOUT;
-            if (typeof intent !== 'undefined' && canOpenIntent())
+            if (allowIntent && typeof intent !== 'undefined' && canOpenIntent())
                 resolved.push(['intent', intent]);
             if (typeof scheme !== 'undefined' && allowScheme)
                 resolved.push(['scheme', scheme]);
@@ -2524,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;
@@ -2621,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) {
@@ -2894,6 +2942,9 @@ var LaunchKit = {
         get canOpenSetting() {
             return canOpenSetting();
         },
+        get canEscapeWebview() {
+            return canEscapeWebview();
+        },
         getTrackId: getTrackIdAsync,
         getProductId: getProductIdAsync,
     },
@@ -3161,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;