web-launch-kit 0.0.7 → 0.0.9

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(bundleId)` / `getProductId(packageFamilyName, language?, country?)` |
 
 `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, {
@@ -146,6 +147,18 @@ flowchart TD
         M2 --> M3["Priority list:<br/>scheme ⭢ fallback<br/>⭢ app store ⭢ web store (by trackId)"]
     end
 
+    subgraph LOC["web store · createWebStoreURL"]
+        L1{"country given?"}
+        L1 -->|yes| L3["Play · MS Store: hl / gl parameters<br/>App Store: /country/ path + l parameter"]
+        L1 -->|no| L2["Derive from language:<br/>region subtag ⭢ Intl.Locale.maximize()<br/>⭢ omit (store geolocation)"]
+        L2 --> L3
+    end
+
+    A5 -.->|"web store"| L1
+    I3 -.->|"web store"| L1
+    W3 -.->|"web store"| L1
+    M3 -.->|"web store"| L1
+
     AND --> P
     IOS --> P
     WIN --> P
@@ -190,6 +203,8 @@ const openedBy = await LaunchKit.app({
     packageName: 'com.example.myapp',
     allowAppStore: true,
     allowWebStore: true,
+    language: 'ko', // 웹스토어 UI 언어
+    country: 'KR',  // 생략하면 language 에서 유도됩니다 (region 서브태그 → Intl.Locale.maximize())
   },
   ios: {
     universal: 'https://example.com/profile/42',
@@ -205,7 +220,17 @@ console.log(openedBy) // "universal" | "scheme" | "intent" | "fallback" | "store
 플랫폼별 필드: 안드로이드는 `intent` / `scheme` / `packageName` / `fallback` /
 `allowIntent`(scheme ⇄ intent는 서로에게서 유도됩니다), iOS는 `universal` / `scheme` / `bundleId` / `trackId`, Windows는
 `scheme` / `packageFamilyName` / `productId`, macOS는 `scheme` / `bundleId` / `trackId`를
-받습니다. 모두 `fallback`, `timeout`, `allowAppStore`, `allowWebStore`를 함께 받습니다.
+받습니다. 모두 `fallback`, `timeout`, `allowAppStore`, `allowWebStore`, `language`,
+`country`를 함께 받습니다.
+
+`language` / `country`는 **웹스토어** 후보에만 적용됩니다 — Google Play와 Microsoft
+Store에서는 `hl` / `gl` 파라미터, App Store에서는 국가 경로 세그먼트와 `l` 파라미터로
+반영됩니다. `country`를 생략하면 `language`에서 유도합니다. region 서브태그가 우선하고
+(`ko-KR` → `KR`), 없으면 런타임이 지원하는 환경에서 `Intl.Locale.maximize()`를
+사용합니다. 둘 다 실패하면 국가를 붙이지 않고 스토어의 자체 위치 추정에 맡깁니다 —
+잘못된 국가는 "이 지역에서 사용할 수 없음" 페이지로 이어질 수 있어 생략이 안전한
+기본값입니다. 네이티브 앱스토어 스킴(`market://`, `itms-apps://` 등)은 건드리지
+않습니다. OS가 기기 로케일로 알아서 렌더링합니다.
 
 `onAttempt`는 각 후보 시도 직전에 동기로 호출됩니다. 대기 UI를 여기서 그리세요 — 그러지
 않으면 타임아웃 동안 화면에 아무 변화가 없습니다.
@@ -313,6 +338,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`로 게이트하세요.
+
 ---
 
 ## 참고
@@ -326,7 +377,12 @@ if (LaunchKit.utils.canOpenSetting) {
 - **`utils.getTrackId` / `getProductId`는 비동기**이고 1시간 캐시됩니다. 페이지 초기화 때
   한 번 호출해두면 `app()`이 id를 인라인으로 조회하지 않습니다. `app()`은 사용자 제스처 안에서
   실행돼야 하므로, id가 없으면 `await`으로 user activation을 잃는 대신 동기로 조회합니다.
-  `trackId` / `productId`를 직접 주면 조회 자체가 생략됩니다.
+  `trackId` / `productId`를 직접 주면 조회 자체가 생략됩니다. `getProductId`는 선택적
+  `language` / `country`를 추가로 받아 Microsoft 카탈로그의 언어와 마켓을 고정합니다 —
+  조회 성공 여부가 마켓에 따라 달라질 수 있으니 `app()`에 넘길 값과 동일하게 주어야
+  프리워밍된 캐시가 같은 마켓을 커버합니다. 생략하면 웹스토어 country와 같은 방식으로
+  유도됩니다: 명시 region 서브태그 → 런타임이 지원하면 `Intl.Locale.maximize()` →
+  `en-US` / `US`. `getTrackId`는 로케일이 필요 없습니다 — iTunes lookup은 마켓과 무관합니다.
 - **스토어 id 조회는 외부 API에 의존합니다**(iTunes Lookup, Microsoft display catalog).
   1시간 캐시되며 실패는 예외가 아니라 `undefined`로 resolve됩니다.
 - **인앱 브라우저는 후보 단위로 걸러집니다.** 실행이 차단된 웹뷰(WeChat, QQ, Qzone, Baidu,

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(bundleId)` / `getProductId(packageFamilyName, language?, country?)` |
 
 `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, {
@@ -147,6 +149,18 @@ flowchart TD
         M2 --> M3["Priority list:<br/>scheme ⭢ fallback<br/>⭢ app store ⭢ web store (by trackId)"]
     end
 
+    subgraph LOC["web store · createWebStoreURL"]
+        L1{"country given?"}
+        L1 -->|yes| L3["Play · MS Store: hl / gl parameters<br/>App Store: /country/ path + l parameter"]
+        L1 -->|no| L2["Derive from language:<br/>region subtag ⭢ Intl.Locale.maximize()<br/>⭢ omit (store geolocation)"]
+        L2 --> L3
+    end
+
+    A5 -.->|"web store"| L1
+    I3 -.->|"web store"| L1
+    W3 -.->|"web store"| L1
+    M3 -.->|"web store"| L1
+
     AND --> P
     IOS --> P
     WIN --> P
@@ -191,6 +205,8 @@ const openedBy = await LaunchKit.app({
     packageName: 'com.example.myapp',
     allowAppStore: true,
     allowWebStore: true,
+    language: 'ko', // web-store UI language
+    country: 'KR',  // omit to derive from language (region subtag → Intl.Locale.maximize())
   },
   ios: {
     universal: 'https://example.com/profile/42',
@@ -207,7 +223,17 @@ Per-platform fields: Android accepts `intent` / `scheme` / `packageName` / `fall
 `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`. 
+`allowAppStore`, `allowWebStore`, `language`, `country`.
+
+`language` / `country` localize the **web-store** candidate only — `hl` / `gl` on
+Google Play and the Microsoft Store, a country path segment plus `l` on the App
+Store. When `country` is omitted it is derived from `language`: a region subtag
+wins (`ko-KR` → `KR`), then `Intl.Locale.maximize()` where the runtime supports
+it. When neither yields a region, the country is simply dropped and the store
+falls back to its own geolocation — a wrong country can land on an
+"not available in your region" page, so omission is the safe default. Native
+app-store schemes (`market://`, `itms-apps://`, …) are untouched; the OS renders
+those in the device locale.
 
 `onAttempt` fires synchronously before each candidate, which is where you drive the waiting
 UI — there is otherwise nothing on screen for the length of the timeout.
@@ -316,6 +342,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
@@ -330,6 +384,12 @@ if (LaunchKit.utils.canOpenSetting) {
   during page setup keeps `app()` from resolving the id inline. `app()` must run inside a
   user gesture, so when the id is missing it looks it up synchronously rather than awaiting
   and losing user activation. Passing `trackId` / `productId` directly skips it entirely.
+  `getProductId` also takes optional `language` / `country` to pin the Microsoft catalog
+  language and market — pass the same values you will give `app()`, since whether a lookup
+  succeeds can depend on the market and the pre-warmed cache should cover the same one.
+  When omitted, the market is derived the same way as the web-store country: explicit region
+  subtag first, then `Intl.Locale.maximize()` where the runtime supports it, then `en-US` / `US`.
+  `getTrackId` needs no locale — iTunes lookup is market-independent.
 - **Store-id lookups depend on remote APIs** (iTunes Lookup, Microsoft display catalog)
   and are cached for one hour; failures resolve to `undefined` rather than throwing.
 - **In-app browsers are gated per candidate.** Inside webviews that block launches

package/dist/index.d.ts

@@ -32,6 +32,8 @@ declare interface AppInfo {
     timeout?: number;
     allowAppStore?: boolean;
     allowWebStore?: boolean;
+    language?: string;
+    country?: string;
 }
 declare interface AndroidAppInfo extends AppInfo {
     intent?: URLCandidate;
@@ -93,12 +95,16 @@ 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>;
+    getProductId(packageFamilyName: string, language?: string, country?: string): Promise<string | undefined>;
 }
 interface LaunchKitInstance {
     readonly version: string;
@@ -113,8 +119,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 };