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 در مرجع کدهای خطا آمده است.
آنچه ماژول در یک نصب انجام میدهد
- درخواست
POST /v1/manifestباappId،versionCodeو اطلاعات دستگاه. - بررسی امضای ECDSA P-256 روی بایتهای manifest با دو کلید عمومی پینشده (کلید فعلی و بعدی، برای چرخش)؛ سپس انقضا، تطابق اطلاعات دستگاه و تطابق
appId/versionCodeبا درخواست وب. - دانلود فایلها از نشانیهای امضاشدهٔ CDN با جابهجایی خودکار بین CDNها و HTTP Range.
- بررسی SHA-256 و حجم هر فایل و گواهی امضای APK پایه؛ هر عدم تطابق ← توقف، حذف فایلها و ثبت رخداد امنیتی.
- نشست
PackageInstaller:USER_ACTION_NOT_REQUIREDبرای بهروزرسانیها روی API 31+،PACKAGE_SOURCE_STOREروی API 33+،setRequestUpdateOwnership(true)در اولین نصب روی API 34+؛ نوشتن همهٔ splitها در یک نشست. - گزارش نتیجه (
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) اجرا میشود.