Bridge — `window.gerege`, `bridge_version: 1`¶

Mini app frontend ↔ host (Gerege App) хоорондын JSON гүүр. OMAS bridge-ийн порт: ижил method, ижил алдааны код, ижил семантик; нэр нь openpay → gerege. Host-ийн хэрэгжүүлэх нарийн гэрээ (тээвэр, origin шалгалт, тусгаарлалт): native-apps/shared/MINIAPP_BRIDGE.md.

Host	Төлөв
iOS (`WKWebView`)	✓
Android (`WebView`, `addWebMessageListener`)	«удахгүй» — гэрээ бэлэн, код алга
Вэб (iframe)	«удахгүй»

1. Илрүүлэх ба дуудах¶

Host нь document-start үед, зөвхөн main frame-д, баримтын origin нь апп-ын зөвшөөрөгдсөн origin байх үед shim inject хийнэ:

if (window.gerege?.bridgeVersion === 1) {
  const ctx = await window.gerege.getContext();
  await window.gerege.ready();
} else {
  // standalone хөтөч (хөгжүүлэлт) — өөрийн mock руу ун
}

window.gerege = {
  bridgeVersion: 1,
  platform: "ios" | "android",
  call(method, params) → Promise<result>,   // алдаа: Error, .code = §4
  ready(), getContext(), getLaunchCode(), requestPayment({ intentId }), …   // call-ын товчлол
}

SDK-гүйгээр (shim-ийн доорх түвшин): iOS — window.webkit.messageHandlers.gerege.postMessage({id, method, params}), хариуг host window.__geregeBridge.receive(reply)-аар өгнө. Хариуны envelope:

{"gerege_bridge": 1, "id": "…", "ok": true,  "result": {}}
{"gerege_bridge": 1, "id": "…", "ok": false, "error": {"code": "not_allowed", "message": "…"}}

2. Мессеж¶

id: string (≤ 128) эсвэл тоо, хүсэлт бүрт өвөрмөц. params: object (байхгүй бол {}).
Хариу бүр яг нэг удаа. Timeout нь дуудагчийнх: 15 с; requestPayment, share — 10 мин; getLaunchCode — 30 с.
Host мэдэхгүй method → unknown_method. Апп-ын bridge_methods-д (manifest-ийн bridge.methods-оос) байхгүй → not_allowed. Үл хамаарах: ready, getContext, close үргэлж зөвшөөрөгдөнө.
safe_area.top = 0 (host-ийн толгой эзэлнэ); bottom = home indicator — доод padding-аа өөрөө хий.

3. Method-ууд¶

Method	params	result	Тэмдэглэл
`ready`	`{}`	`{}`	Анхны дэлгэц зурагдсан — host loader-ыг нууна. 10 с-д ирэхгүй бол алдааны дэлгэц
`getContext`	`{}`	`{bridge_version, platform, app_version, locale, theme, safe_area:{top,bottom,left,right}, capabilities}`	`locale`: `mn`, `en`, `ru`, `zh`, `fr`, `es`, `ar`. `capabilities` = энэ апп-д зөвшөөрөгдсөн ба host-ийн дэмждэг method-ууд
`getLaunchCode`	`{}`	`{launch_code, expires_at}`	Session шинэчлэх (шинэ нээлт). Consent / maintenance → `not_allowed`
`requestPayment`	`{intentId}`	`{status: "succeeded"\\|"canceled"\\|"failed", intentId}`	Host-ийн төлбөрийн самбар (payments.md §3). `succeeded`-д итгэхгүй — backend-ээр шалгана. Нэгэн зэрэг 1
`openExternal`	`{url}`	`{}`	https; host-ийн глобал жагсаалт эсвэл апп-ын `external_urls` prefix
`share`	`{text?, url?}`	`{shared}`	Системийн хуваалцах цонх. `url` нь https
`copy`	`{text}`	`{}`	≤ 4 KB (UTF-8)
`haptic`	`{kind: "light"\\|"medium"\\|"success"\\|"warning"\\|"error"}`	`{}`
`setTitle`	`{text}`	`{}`	≤ 32 тэмдэгт (урт нь тасарна)
`close`	`{}`	`{}`	Mini app хаагдана
`openMiniApp`	`{slug, path?}`	`{}`	Өөр mini app (шинэ нээлт, шинэ consent шалгалт)

Host → mini app event (themeChange, resume) — v1-д байхгүй; visibilitychange-д getContext-ийг дахин дууд.

4. Алдааны код¶

code	Утга
`not_allowed`	Manifest / origin / апп-ын төлөв зөвшөөрөхгүй
`invalid_params`	Параметр буруу
`canceled`	Хүн цуцалсан
`unknown_method`	Host энэ method-ийг мэдэхгүй
`unsupported`	Энэ платформ дээр боломжгүй
`timeout`	Хариу ирээгүй (дуудагч талд)
`internal`	Host-ийн алдаа

5. Аюулгүй байдал (mini app-д хамаарах)¶

Гүүрээр нууц дамжихгүй (token, данс, үлдэгдэл). launch_code ганцаараа ашиггүй — client secret хэрэгтэй, 60 с.
Mini app нь host-ийн session, cookie, storage-д хүрэхгүй — тусгаарлагдсан (non-persistent) WebView.
Зөвшөөрөгдсөн origin-оос гадуурх main frame навигаци → openExternal-ийн дүрмээр системийн хөтөч, бусад нь хориг. window.open шинэ цонх нээхгүй.
Mini app дотор нууц үг, карт, ПИН асуух ХОРИГЛОНО — төлбөр зөвхөн requestPayment.

6. Туршилт¶

native-apps/shared/miniapp-test/index.html — бүх method-ыг дарж үзэх хуудас. iOS Debug build-д http://localhost зөвшөөрөгдөнө (Release-д үгүй):

cd native-apps/shared/miniapp-test && python3 -m http.server 8765

Bridge — window.gerege, bridge_version: 1¶