Агуулгыг алгасах

Gerege App дотор mini app

Юу хийх: өөрийн вэб апп-ыг Gerege App дотор нээгддэг mini app болгож, хүний нэвтрэлтийг (launch → token) авч, bridge-ээр төлбөр хүсэх. Хугацаа: ~30 минут (вэб апп тань https дээр байрласан бол). Юу хэрэгтэй: Quickstart-ийн §0–§2 (байгууллага, «Mini апп-ууд», консолын session), https origin, backend.

Mini app бол Gerege App-ын launcher-т гарч, апп дотор (WKWebView) нээгддэг таны вэб апп. Худалдагчаас ялгаа нь Худалдагч ба mini app-д. Стандарт нь OMAS 1.0-ийн Gerege хэрэгжилт — OMAS-д бичсэн backend зөвхөн утгаа сольж ажиллана.

1. Бүртгэх

curl -sS "$GEREGE/dev/apps" -H "Authorization: Bearer $GEREGE_SESSION" -H 'Content-Type: application/json' \
  -d '{"slug": "my-esim", "name": "Миний eSIM", "entry_url": "https://esim.example.mn/app",
       "category": "travel", "developer_name": "Жишээ ХХК"}' | tee app.json | jq '{id, slug, test_client_id, live_client_id, verification_token}'
export APP_ID=$(jq -r .id app.json)

Консолын (/apps/miniapp) бүртгэх цонхоор ч болно. Бүртгэлээр mapp_… (live), mapp_test_… (test) client id ба omas-verify=… token олгогдоно. Апп draft; scope нь profile.basic — төлбөр авах бол PATCH-аар payments нэмнэ (ноорог үед).

2. Manifest нийтлэх ба шалгах

Origin дээрээ /.well-known/gerege-miniapp.json-ийг нийтэлнэ (талбар бүр: Manifest):

{
  "omas_version": "1.0",
  "slug": "my-esim",
  "client_id": "mapp_…",
  "version": "1.0.0",
  "name": { "mn": "Миний eSIM", "en": "My eSIM" },
  "entry": "https://esim.example.mn/app",
  "origins": ["https://esim.example.mn"],
  "icons": [{ "src": "https://esim.example.mn/icon-512.png", "size": 512 }],
  "scopes": ["profile.basic", "payments"],
  "bridge": { "min_version": 1, "methods": ["getContext", "getLaunchCode", "requestPayment", "close"] },
  "legal": { "privacy_url": "https://example.mn/privacy", "terms_url": "https://example.mn/terms", "support_url": "https://example.mn/help" },
  "verification": "omas-verify=…"
}

curl -sS -X POST "$GEREGE/dev/apps/$APP_ID/manifest/check" -H "Authorization: Bearer $GEREGE_SESSION" | jq

Шалгалт нь origin-ыг таных гэж нотолно (verification), 512×512 PNG icon ба хуулийн гурван хуудас 200 хариулахыг шалгана. Байршуулахаас өмнө POST /dev/manifest/validate-ээр body-оор нь шалгаж болно.

3. Test credential ба тест хэрэглэгч

curl -sS "$GEREGE/dev/apps/$APP_ID/keys" -H "Authorization: Bearer $GEREGE_SESSION" \
  -H 'Content-Type: application/json' -d '{"name": "backend", "environment": "test", "preset": "miniapp_backend"}' \
  | jq '{client_id, client_secret, scopes}'

Preset «Mini app backend» = oauth:token, payments:read, payments:write, refunds:write.

Ноорог апп-ыг бүртгэсэн хүн ба тест хэрэглэгчид (таны байгууллагын идэвхтэй гишүүд, ≤ 50) Gerege App-ын launcher-тээ харж нээнэ; тэдний launch code-ийг test credential солино, мөнгө хөдлөхгүй. Тест хэрэглэгч нэмэх: POST /dev/apps/{id}/test-users {"email"} (Хөгжүүлэгчийн sandbox).

4. Нээлт → token

Gerege App апп-ыг entry?launch=<code> хаягаар нээнэ. Frontend launch-ийг URL-аас уншаад history-оос арилгаж, өөрийн backend руу илгээнэ; backend нэг удаагийн кодыг token-оор солино:

curl -sS "$GEREGE/oauth/token" -u "$GEREGE_CLIENT_ID:$GEREGE_CLIENT_SECRET" \
  -d grant_type=authorization_code -d code=gml_…

{ "token_type": "Bearer", "access_token": "gma_at_…", "expires_in": 1800, "refresh_token": "gma_rt_…",
  "scope": "profile.basic payments",
  "user": { "ref": "u_9f2c…", "sub": "u_9f2c…", "verified": true, "locale": "mn" } }

Код 60 секунд, нэг удаа; sub нь таны апп-д тогтмол, нэрээ нууцалсан хүний id. Дэлгэрэнгүй (refresh rotation, /me, consent, requires_verified/min_age): Mini app-ын нээлт ба token.

5. Төлбөр хүсэх

Backend хүний token-оор intent үүсгэнэ (presentment: "app" — анхдагч), frontend bridge-ээр төлөх цонхыг нээнэ:

curl -sS "$GEREGE/payment-intents" -H "Authorization: Bearer gma_at_…" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: order-77' \
  -d '{"amount": 45000, "description": "eSIM 7 хоног", "reference": "order-77"}' | jq '{id, status}'

const res = await window.gerege.requestPayment({ intentId: "pi_…" });
// res.status: "succeeded" | "canceled" | "failed" — ҮҮНД ИТГЭХГҮЙ: backend GET эсвэл webhook-оор шалгана

Төлбөрийн бүх API, manual capture, буцаалт: Mini app-ын төлбөр. Bridge-ийн бүх method: Bridge. Webhook: Webhook (payments scope-той апп-д заавал).

6. Review ба нийтлэх

POST /dev/apps/{id}/submit — шалгагдсан manifest, privacy/terms/support холбоос, live secret, (payments-тэй бол) webhook URL шаардана; review-ийн үед апп царцна. Батлагдмагц хүмүүсийн жагсаалтад гарна; launcher-ийн нүүрэнд хаана гарахыг оператор layout-аар шийднэ. Шаардлагын бүрэн жагсаалт: Review-ийн шаардлага. Төлөвүүд (draft → in_review → approved | rejected, suspended): Test ба live.