title: "مرجع پل نصب (وب ↔ بومی)" order: 12 description: "برای تیم اپ میزبان (بله) و توسعه‌دهندگان فروشگاه وب: یکپارچه‌سازی AAR، انتقال پیام، متدها، رویدادها، حالت‌های نصب و قواعد امنیتی"

مرجع پل نصب (وب ↔ بومی)

مخاطب این صفحه تیم اپ میزبان (پیام‌رسان بله یا برنامهٔ نصب‌کنندهٔ مستقل) و توسعه‌دهندگان فروشگاه وب بله‌استور هستند. توسعه‌دهندگان برنامه‌ها به این صفحه نیازی ندارند.

بله‌استور معماری ترکیبی دارد: فروشگاه، یک وب‌اپ است که داخل WebView بله اجرا می‌شود و نصب، کار یک ماژول بومی کوچک (AAR) است که در اپ میزبان قرار می‌گیرد. این دو از طریق یک پل JSON با هم حرف می‌زنند. فقط ماژول بومی (با مجوز REQUEST_INSTALL_PACKAGES) می‌تواند APK نصب کند و نصب‌کنندهٔ ثبت‌شده (installer of record) شود؛ به همین دلیل به‌روزرسانی خودکار ممکن است.

┌────────────── Bale app (host) ──────────────┐
│  WebView (https://store.<domain>)            │
│    window.BaleStoreBridge  (TS client)       │
│        │ postMessage(json)   ▲ BaleStoreBridgeReceive(json)
│        ▼                     │               │
│  BaleStoreBridgeNative  ── ir.bale.balestore.installer (AAR)
│        │ signed manifest / CDN / PackageInstaller / WorkManager
│        ▼                                     │
│  AIDL: ir.bale.balestore.billing.IBillingService  ◀── apps using the billing SDK
└──────────────────────────────────────────────┘

۱. یکپارچه‌سازی در اپ میزبان

ماژول با پکیج ir.bale.balestore.installer به‌صورت AAR تحویل می‌شود (minSdk 24؛ هدف حجم: کمتر از ۱ مگابایت افزوده به APK؛ بدون وابستگی سنگین).

// Application.onCreate
BaleStoreInstaller.init(this, InstallerConfig(
    apiBaseUrl = "https://api.<domain>",               // dev: http://10.0.2.2:18080
    allowedOrigins = listOf("https://store.<domain>"),  // dev: http://localhost:13000, http://10.0.2.2:13000
    baleVersion = BuildConfig.VERSION_NAME,
    httpClient = null,          // optional: plug the host's OkHttp via the HttpClient interface
    ssoTokenProvider = { null } // OPEN #2: supply the Bale SSO token for getCapabilities().baleSsoToken
))
// In the WebView screen
val bridge = BaleStoreInstaller.attach(webView)   // registers BaleStoreBridgeNative; origin is checked on every call

// onDestroy
bridge.detach()
پارامتر InstallerConfig توضیح
apiBaseUrl نشانی درگاه API بله‌استور (manifest، همگام‌سازی دستگاه، نتایج نصب، پرداخت)
allowedOrigins فهرست مجاز origin صفحهٔ فروشگاه؛ هر origin دیگری ERR_FORBIDDEN_ORIGIN می‌گیرد
baleVersion نسخهٔ اپ میزبان؛ در getCapabilities() برگردانده می‌شود
httpClient اختیاری؛ برای استفادهٔ دوباره از OkHttp اپ میزبان از طریق رابط HttpClient (به‌جای پشتهٔ HTTP جداگانه)
ssoTokenProvider تابعی که توکن SSO بله را برمی‌گرداند (یا null)؛ در getCapabilities().baleSsoToken قرار می‌گیرد. سازوکار SSO بله در حال نهایی‌شدن است.

مجوزهای manifest

این مجوزها از manifest خود AAR در manifest اپ میزبان ادغام می‌شوند:

مجوز دلیل
REQUEST_INSTALL_PACKAGES نصب APK با PackageInstaller
UPDATE_PACKAGES_WITHOUT_USER_ACTION به‌روزرسانی بی‌صدا (API 31+)
ENFORCE_UPDATE_OWNERSHIP درخواست مالکیت به‌روزرسانی در اولین نصب (API 34+)
INTERNET، ACCESS_NETWORK_STATE دانلود؛ رعایت تنظیم «فقط Wi-Fi»
POST_NOTIFICATIONS اعلان پیشرفت و هشدار امنیتی (API 33+)
FOREGROUND_SERVICE + FOREGROUND_SERVICE_DATA_SYNC فقط اگر دانلودهای طولانی با سرویس پیش‌زمینه انجام شوند

QUERY_ALL_PACKAGES استفاده نمی‌شود. وضعیت نصب فقط برای بسته‌های کاتالوگ و از طریق <queries> یا getPackageInfo نام‌های شناخته‌شده خوانده می‌شود.

سرویس پرداخت (AIDL)

AAR سرویس ir.bale.balestore.billing.IBillingService را با intent action ir.bale.balestore.billing.BIND در اختیار برنامه‌هایی می‌گذارد که از SDK پرداخت استفاده می‌کنند. ماژول هویت فراخواننده (نام بسته و گواهی امضا) را از Binder.getCallingUid تشخیص می‌دهد و به سرور می‌فرستد؛ برنامهٔ فراخواننده نمی‌تواند هویت جعلی اعلام کند.

متد AIDL کار
isBillingSupported(apiVersion, packageName, type) پشتیبانی از پرداخت
getSkuDetails(apiVersion, packageName, type, skus) جزئیات محصولات
getBuyIntent(apiVersion, packageName, sku, type, developerPayload) PendingIntent صفحهٔ پرداخت بله
getPurchases(apiVersion, packageName, type, continuationToken) فهرست خریدها
consumePurchase(apiVersion, packageName, purchaseToken) مصرف
acknowledgePurchase(apiVersion, packageName, purchaseToken) تأیید

صفحهٔ پرداخت بومی بله در حال نهایی‌شدن است؛ در محیط توسعه یک صفحهٔ پرداخت فارسی آزمایشی (سندباکس) نمایش داده می‌شود.

۲. انتقال پیام

  • ماژول با addJavascriptInterface شیء BaleStoreBridgeNative را با یک متد ثبت می‌کند: postMessage(json: String). (روی WebViewهایی که WebViewCompat.addWebMessageListener را پشتیبانی می‌کنند، ماژول می‌تواند با همین قالب JSON و فهرست مجاز origin از آن استفاده کند.)

  • درخواست (وب → بومی):

    {"id":"c-17","method":"install","params":{"appId":"3f6c…","versionCode":1203}}
    
  • پاسخ (بومی → وب): ماژول روی نخ اصلی window.BaleStoreBridgeReceive(json) را اجرا می‌کند:

    {"id":"c-17","result":{"ok":true,"data":{"jobId":"j-8b1e…"}}}
    {"id":"c-18","result":{"ok":false,"error":{"code":"ERR_RATE_LIMITED","message":"…"}}}
    
  • رویدادها (بدون id):

    {"event":"progress","data":{ /* ProgressEvent */ }}
    {"event":"securityAlert","data":{ /* SecurityAlertEvent */ }}
    
  • کلاینت TypeScript فروشگاه (window.BaleStoreBridge) هر فراخوانی را به یک Promise تبدیل می‌کند و اگر تا ۳۰ ثانیه پاسخی نرسد، با ERR_INTERNAL تمامش می‌کند.

  • JSON نامعتبر یا متد ناشناخته ← {ok:false, error:{code:"ERR_INTERNAL"}}؛ ماژول هرگز crash نمی‌کند.

۳. متدها

نسخهٔ پل: bridgeVersion = "1.0.0". همهٔ متدها ناهمگام‌اند و پاکت {ok:true, data} | {ok:false, error:{code, message}} برمی‌گردانند. ERR_FORBIDDEN_ORIGIN برای هر متدی ممکن است.

متد پارامترها خروجی data خطاهای ممکن در پاسخ
getCapabilities — Capabilities —
getInstalledPackages packageNames: string[] InstalledPackage[] (فقط بسته‌های کاتالوگ؛ بقیه حذف می‌شوند) —
install appId: string، versionCode: int {jobId} ERR_RATE_LIMITED، ERR_UNAUTHENTICATED، ERR_INTERNAL
cancel jobId: string {cancelled: boolean} ERR_UNKNOWN_JOB
open packageName: string {opened: boolean} ERR_NOT_IN_CATALOG
share appId: string، chatId?: string {shared: boolean} —
setAutoUpdate enabled: bool، wifiOnly: bool، perApp?: map<string,bool> {saved: true} —
getPendingJobs — ProgressEvent[] —
openUninstall packageName: string {opened: boolean} ERR_NOT_IN_CATALOG
setSession accessToken: string، apiBaseUrl: string {saved: true} —
  • install: لایهٔ وب فقط appId و versionCode می‌دهد؛ هرگز نشانی، مسیر فایل، گواهی یا نام بستهٔ دلخواه. خطاهای حین نصب از طریق رویداد progress با state: "FAILED" و errorCode می‌رسند.
  • share: برگهٔ اشتراک‌گذاری بله را باز می‌کند، یا با chatId کارت برنامه را مستقیم می‌فرستد.
  • openUninstall: صفحهٔ حذف سیستم را باز می‌کند (برای هشدارهای امنیتی). بله‌استور هرگز برنامه‌ای را بی‌صدا حذف نمی‌کند.
  • setSession: توکن نشست کاربر را به ماژول می‌دهد تا بتواند به نام کاربر از distribution و billing درخواست کند (لولهٔ لازم؛ در جدول اصلی مشخصات نیست).
  • getPendingJobs: پس از بارگذاری دوبارهٔ صفحه، وضعیت کارهای نصب در جریان را برمی‌گرداند.

انواع داده

interface Capabilities {
  bridgeVersion: string; moduleVersion: string; baleVersion: string;
  androidSdkInt: number; abis: string[]; densityDpi: number; locales: string[];
  canInstall: boolean;                 // REQUEST_INSTALL_PACKAGES granted or grantable
  canSilentUpdate: boolean;            // API 31+ and UPDATE_PACKAGES_WITHOUT_USER_ACTION declared
  canRequestUpdateOwnership: boolean;  // API 34+
  autoUpdateEnabled: boolean; wifiOnly: boolean;
  theme: "light" | "dark" | null;      // OPEN #13
  deviceIdHash: string; deviceModel: string;
  baleSsoToken?: string | null;        // OPEN #2
}

interface InstalledPackage {
  packageName: string; installed: boolean;
  versionCode: number | null; versionName: string | null;
  installerIsBale: boolean; updateOwnerIsBale: boolean;
  signingCertSha256: string | null;    // "AB:CD:…" of the current signer
}

interface ProgressEvent {
  jobId: string; appId: string; packageName: string; versionCode: number;
  state: JobState; bytesDownloaded: number; bytesTotal: number;
  errorCode?: string;                  // see /developers/docs/install-errors
}

interface SecurityAlertEvent { appId: string; packageName: string; title: string; message: string; type: "MALICIOUS" | "PULLED" }

۴. رویدادها

رویداد داده زمان
progress ProgressEvent هر تغییر حالت و پیشرفت دانلود یک کار نصب
securityAlert SecurityAlertEvent برنامهٔ نصب‌شده‌ای مخرب (MALICIOUS) یا از دسترس خارج (PULLED) اعلام شده؛ فروشگاه هشدار و دکمهٔ openUninstall را نشان می‌دهد

۵. حالت‌های کار نصب

QUEUED، FETCHING_MANIFEST، DOWNLOADING، VERIFYING، PENDING_USER_ACTION، INSTALLING، INSTALLED، FAILED، CANCELLED

QUEUED → FETCHING_MANIFEST → DOWNLOADING → VERIFYING → INSTALLING ──────────→ INSTALLED
                                                          ↕
                                                  PENDING_USER_ACTION
                                                  (system confirmation)

any non-terminal state ──→ FAILED     (errorCode = ERR_*)
                       └─→ CANCELLED  (cancel() or user declined; errorCode = ERR_USER_CANCELLED)
حالت معنی
QUEUED در صف (حداکثر ۲ دانلود هم‌زمان، ۱ نصب در هر لحظه)
FETCHING_MANIFEST دریافت و بررسی manifest امضاشده
DOWNLOADING دانلود فایل‌ها با ادامه از نقطهٔ قطع؛ bytesDownloaded/bytesTotal به‌روز می‌شوند
VERIFYING بررسی SHA-256 هر فایل و گواهی امضا
PENDING_USER_ACTION منتظر تأیید کاربر در دیالوگ سیستم
INSTALLING نشست PackageInstaller در حال commit
INSTALLED پایانی: موفق
FAILED پایانی: ناموفق با errorCode
CANCELLED پایانی: لغوشده

نکته برای رابط کاربری: PENDING_USER_ACTION ممکن است پیش یا پس از INSTALLING بیاید؛ هر دو را «در حال نصب» در نظر بگیرید و فقط به حالت‌های پایانی تکیه کنید. لغو کاربر را با errorCode === "ERR_USER_CANCELLED" تشخیص دهید (در هر دو حالت CANCELLED و FAILED) و برایش پیام خطا نشان ندهید. نگاشت وضعیت‌های PackageInstaller در مرجع کدهای خطا آمده است.

آنچه ماژول در یک نصب انجام می‌دهد

  1. درخواست POST /v1/manifest با appId، versionCode و اطلاعات دستگاه.
  2. بررسی امضای ECDSA P-256 روی بایت‌های manifest با دو کلید عمومی پین‌شده (کلید فعلی و بعدی، برای چرخش)؛ سپس انقضا، تطابق اطلاعات دستگاه و تطابق appId/versionCode با درخواست وب.
  3. دانلود فایل‌ها از نشانی‌های امضاشدهٔ CDN با جابه‌جایی خودکار بین CDNها و HTTP Range.
  4. بررسی SHA-256 و حجم هر فایل و گواهی امضای APK پایه؛ هر عدم تطابق ← توقف، حذف فایل‌ها و ثبت رخداد امنیتی.
  5. نشست PackageInstaller: USER_ACTION_NOT_REQUIRED برای به‌روزرسانی‌ها روی API 31+، PACKAGE_SOURCE_STORE روی API 33+، setRequestUpdateOwnership(true) در اولین نصب روی API 34+؛ نوشتن همهٔ splitها در یک نشست.
  6. گزارش نتیجه (POST /v1/device/install-results) و پاک کردن فایل‌های موقت.

۶. قواعد امنیتی

  • فهرست مجاز origin در هر فراخوانی بررسی می‌شود (allowedOrigins؛ در توسعه http://localhost:13000 و http://10.0.2.2:13000). origin ناشناخته ← ERR_FORBIDDEN_ORIGIN.
  • لایهٔ وب فقط appId و versionCode به install می‌دهد؛ ماژول همه‌چیز (فایل‌ها، هش‌ها، گواهی) را از manifest امضاشده درمی‌آورد.
  • فهرست مجاز کاتالوگ: getInstalledPackages، open و openUninstall فقط برای بسته‌های کاتالوگ بله‌استور کار می‌کنند (همگام‌شده از GET /v1/catalog/packages به‌علاوهٔ بسته‌هایی که ماژول خودش نصب کرده). بقیه حذف می‌شوند یا ERR_NOT_IN_CATALOG می‌گیرند.
  • محدودیت نرخ: حداکثر ۱۰ فراخوانی install در دقیقه برای هر WebView ← ERR_RATE_LIMITED.
  • مقاومت: JSON خراب یا متد ناشناخته ← ERR_INTERNAL، بدون crash.
  • TLS 1.2 به بالا در همه‌جا؛ پین کردن گواهی برای endpointهای manifest و همگام‌سازی.

۷. حالت فقط-مرور و نسخه‌بندی

bridgeVersion از semver پیروی می‌کند. فروشگاه وب در این حالت‌ها فقط-مرور است:

وضعیت رفتار فروشگاه
window.BaleStoreBridge بومی وجود ندارد یا bridgeVersion < minBridgeVersion (از پیکربندی عمومی) — اندروید دکمهٔ نصب: «برای نصب، بله را به‌روز کنید»
iOS دکمه‌های نصب پنهان؛ برچسب «فقط اندروید»
وب (خارج از بله) دعوت به «باز کردن در بله»

تغییرات افزایشی (متد یا فیلد اختیاری جدید) نسخهٔ minor را بالا می‌برند؛ فروشگاه باید فیلدهای ناشناخته را نادیده بگیرد و با getCapabilities().bridgeVersion تصمیم بگیرد.

۸. به‌روزرسانی خودکار پس‌زمینه

  • یک کار دوره‌ای WorkManager (پیش‌فرض هر ۶ ساعت با jitter حدود ۶۰ دقیقه؛ قابل تنظیم از سرور) POST /v1/device/sync را با فهرست بسته‌های کاتالوگ نصب‌شده صدا می‌زند و به‌روزرسانی‌های مجاز (طبق انتشار مرحله‌ای)، پرچم‌های امنیتی و پیکربندی را می‌گیرد.
  • ترتیب: اول اصلاحات امنیتی، سپس برنامه‌هایی که اخیراً بیشتر استفاده شده‌اند.
  • هم‌زمانی: حداکثر ۲ دانلود و ۱ نصب.
  • تنظیمات کاربر (setAutoUpdate): روشن/خاموش، فقط Wi-Fi، و تنظیم برای هر برنامه.
  • شرایط به‌روزرسانی بی‌صدا (همه لازم است، وگرنه تأیید کاربر): اپ میزبان UPDATE_PACKAGES_WITHOUT_USER_ACTION را اعلام کرده باشد؛ به‌روزرسانی باشد و بله نصب‌کنندهٔ ثبت‌شده یا مالک به‌روزرسانی باشد؛ targetSdk برنامه حداقلِ لازم برای نسخهٔ اندروید دستگاه را داشته باشد (جدول در پیکربندی راه دور؛ ببینید راهنمای انتشار).

۹. توسعهٔ محلی

  • در شبیه‌ساز اندروید: apiBaseUrl = "http://10.0.2.2:18080" و allowedOrigins = listOf("http://localhost:13000", "http://10.0.2.2:13000").
  • فروشگاه وب یک پل شبیه‌سازی‌شده دارد (?mockBridge=1 یا NEXT_PUBLIC_MOCK_BRIDGE=1) که همین رابط را در JavaScript پیاده می‌کند، manifest واقعی را می‌گیرد، پیشرفت دانلود را شبیه‌سازی و نتیجه را گزارش می‌کند؛ کل جریان در مرورگر دسکتاپ قابل آزمایش است.
  • اگر ماژول به‌موقع در بله قرار نگیرد، همین ماژول و همین قرارداد پل در برنامهٔ نصب‌کنندهٔ مستقل (ir.bale.balestore.installer) اجرا می‌شود.