title: "SDK پرداخت درونبرنامهای اندروید" order: 3 description: "نصب، اتصال، جزئیات محصول، خرید، مصرف و تأیید، اشتراک، تشخیص منبع نصب، کوروتین، تأیید محلی، سندباکس و لایهٔ چندفروشگاهی"
SDK پرداخت درونبرنامهای اندروید
SDK بلهاستور به سرویس پرداخت داخل بله (یا برنامهٔ نصبکنندهٔ مستقل بلهاستور) وصل میشود و خرید محصول درونبرنامهای و اشتراک را ممکن میکند. API آن عمداً شبیه Poolakey طراحی شده تا مهاجرت در چند ساعت انجام شود (ببینید: مهاجرت از Poolakey).
- مختصات Gradle:
ir.bale.balestore:billing-sdk:1.0.0 - پکیج Kotlin:
ir.bale.balestore.sdk(افزونههای کوروتین درir.bale.balestore.sdk.ktx، لایهٔ چندفروشگاهی درir.bale.balestore.sdk.store)
نحوهٔ کار
برنامهٔ شما ──(SDK)──▶ سرویس AIDL داخل بله ──▶ سرور پرداخت بلهاستور
▲ │
└──── PurchaseInfo ◀─── صفحهٔ پرداخت بله (کیف پول / شاپرک)
SDK با intent action ir.bale.balestore.billing.BIND به سرویس ir.bale.balestore.billing.IBillingService وصل میشود. سرویس هویت برنامهٔ شما را از روی UID فراخواننده (نام بسته و گواهی امضا) تشخیص میدهد؛ بنابراین برنامهای که با کلید دیگری امضا شده، نمیتواند به نام شما خرید کند. اطلاعات کارت هرگز به برنامهٔ شما نمیرسد.
۱. نصب
مخزن Maven بلهاستور را اضافه کنید (نشانی نهایی در حال نهاییشدن است؛ تا آن زمان میتوانید فایل AAR را دستی در پوشهٔ libs بگذارید):
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven("https://maven.<domain>/releases") // Bale Store Maven repository (URL being finalized)
}
}
// app/build.gradle.kts
dependencies {
implementation("ir.bale.balestore:billing-sdk:1.0.0")
}
از اندروید ۱۱ (API 30) به بعد، برنامهها فقط بستههایی را میبینند که در <queries> اعلام کرده باشند. این ورودیها را به manifest برنامه اضافه کنید (اگر manifest خود AAR هم آنها را داشته باشد، ادغام manifest موارد تکراری را یکی میکند):
<!-- AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<queries>
<!-- Bale messenger (hosts the Bale Store billing service) -->
<package android:name="ir.nasim" />
<!-- standalone Bale Store installer app -->
<package android:name="ir.bale.balestore.installer" />
<intent>
<action android:name="ir.bale.balestore.billing.BIND" />
</intent>
</queries>
<!-- … -->
</manifest>
۲. پیکربندی و اتصال
import ir.bale.balestore.sdk.*
class ShopActivity : ComponentActivity() {
private lateinit var payment: BaleStorePayment
private lateinit var connection: Connection
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
payment = BaleStorePayment(
context = this,
config = PaymentConfiguration(
// per-app public key from the console (Monetization → Keys). Or SecurityCheck.Disable
localSecurityCheck = SecurityCheck.Enable(publicKeyPem = BuildConfig.BALESTORE_PUBLIC_KEY_PEM)
)
)
connection = payment.connect {
connectionSucceed {
// ready: query sku details / pending purchases
}
connectionFailed { throwable ->
when (throwable) {
is BaleStoreNotFoundException -> showInstallBaleHint()
is BillingNotSupportedException -> hideShop()
else -> showError(throwable)
}
}
disconnected {
// the service went away (e.g. Bale was updated); reconnect when needed
}
}
}
override fun onDestroy() {
connection.disconnect()
super.onDestroy()
}
}
وضعیت اتصال را هر زمان با connection.getState() بخوانید: ConnectionState.Connected، ConnectionState.Disconnected یا ConnectionState.FailedToConnect.
کلید عمومی مخصوص هر برنامه است و از کنسول (یا GET /console/v1/billing/apps/{appId}/keys) گرفته میشود. این کلید محرمانه نیست، اما آن را از منبع مطمئن (همان کنسول) بردارید و در کد قرار دهید. جزئیات و چرخش کلید: تأیید توکن خرید.
۳. جزئیات محصول
محصولات را در کنسول تعریف میکنید (نوع CONSUMABLE، NON_CONSUMABLE یا SUBSCRIPTION؛ امکان ورود گروهی از CSV).
payment.getInAppSkuDetails(skuIds = listOf("coins_100", "remove_ads")) {
getSkuDetailsSucceed { list: List<SkuDetails> ->
list.forEach { sku ->
// sku.priceText is ready-to-show Persian Toman text; sku.priceRials is the integer amount in Rials
addRow(sku.title, sku.description, sku.priceText)
}
}
getSkuDetailsFailed { throwable -> showError(throwable) }
}
payment.getSubscriptionSkuDetails(listOf("vip_monthly")) {
getSkuDetailsSucceed { list -> /* sku.period, e.g. "P1M" */ }
getSkuDetailsFailed { throwable -> showError(throwable) }
}
data class SkuDetails(
val sku: String,
val type: String, // "inapp" | "subs"
val title: String,
val description: String,
val priceRials: Long, // integer Rials
val priceText: String, // Persian, in Toman (Rials / 10)
val period: String?, // subscriptions: ISO-8601 period such as "P1W", "P1M", "P3M", "P6M", "P1Y"
)
همهٔ مبالغ در API به ریال (عدد صحیح) هستند و رابط کاربری تومان (ریال ÷ ۱۰) نشان میدهد. برای نمایش، از
priceTextاستفاده کنید.
۴. خرید
خرید به ActivityResultRegistry نیاز دارد (هر ComponentActivity یا Fragment آن را دارد):
payment.purchaseProduct(
registry = activityResultRegistry,
request = PurchaseRequest(productId = "coins_100", payload = "order-42")
) {
purchaseFlowBegan { /* Bale payment sheet is shown */ }
failedToBeginFlow { throwable -> showError(throwable) }
purchaseSucceed { purchase: PurchaseInfo ->
// 1) send purchase.purchaseToken to YOUR server → verify (S2S) → grant the item
// 2) then consume (consumable) or acknowledge (non-consumable)
onPurchased(purchase)
}
purchaseCanceled { /* user closed the sheet */ }
purchaseFailed { throwable -> showError(throwable) }
}
payloadیک رشتهٔ دلخواه شماست (مثلاً شناسهٔ سفارش در سیستم خودتان) که در خرید و توکن خرید (developerPayload) برمیگردد.- صفحهٔ پرداخت، صفحهٔ بومی بله است (کیف پول بله یا درگاه شاپرکی). در محیط توسعه و سندباکس یک صفحهٔ پرداخت فارسی آزمایشی نمایش داده میشود.
data class PurchaseInfo(
val orderId: String,
val purchaseToken: String, // compact JWS (ES256) — send this to your server
val payload: String, // your developerPayload
val packageName: String,
val purchaseState: PurchaseState,
val purchaseTime: Long, // epoch millis
val productId: String,
val originalJson: String,
val dataSignature: String,
)
enum class PurchaseState { PENDING, PURCHASED, ACKNOWLEDGED, CONSUMED, REFUNDED, AUTO_REFUNDED }
۵. مصرف (consume) و تأیید (acknowledge)
پس از اینکه محصول را به کاربر دادید، باید خرید را نهایی کنید:
| نوع محصول | کار لازم | نتیجه |
|---|---|---|
مصرفی (CONSUMABLE)، مثل سکه |
consumeProduct |
کاربر میتواند دوباره بخرد |
غیرمصرفی (NON_CONSUMABLE)، مثل حذف تبلیغات |
acknowledge |
خرید برای همیشه در فهرست خریدها میماند |
اشتراک (SUBSCRIPTION) |
acknowledge |
— |
payment.consumeProduct(purchase.purchaseToken) {
consumeSucceed { /* done */ }
consumeFailed { throwable -> retryLater(purchase, throwable) }
}
payment.acknowledge(purchase.purchaseToken) {
acknowledgeSucceed { }
acknowledgeFailed { throwable -> retryLater(purchase, throwable) }
}
⚠️ مهلت نهاییسازی: خریدی که تا مهلت مقرر (پیشفرض ۳ روز، قابل تنظیم) نه مصرف شود و نه تأیید، خودکار بازپرداخت میشود و وضعیتش
AUTO_REFUNDEDمیشود. این از کاربر در برابر برنامهای که پول گرفته ولی محصول را نداده محافظت میکند.
تأیید را میتوانید از سرور خودتان هم انجام دهید: POST /s2s/v1/apps/{packageName}/purchases/{purchaseToken}:acknowledge (API سرور).
چرخهٔ عمر خرید: PENDING → PURCHASED → (ACKNOWLEDGED | CONSUMED) → (REFUNDED)؛ و در صورت گذشتن مهلت: AUTO_REFUNDED.
پردازش خریدهای ناتمام
اگر برنامه بعد از پرداخت و پیش از مصرف بسته شود، خرید ناتمام میماند. هر بار پس از اتصال فهرست خریدها را بخوانید و موارد نهایینشده را پردازش کنید:
payment.getPurchasedProducts {
querySucceed { purchases: List<PurchaseInfo> ->
purchases.filter { it.purchaseState == PurchaseState.PURCHASED }
.forEach { onPurchased(it) } // verify on server → grant → consume/acknowledge
}
queryFailed { throwable -> showError(throwable) }
}
۶. اشتراک
payment.subscribeProduct(activityResultRegistry, PurchaseRequest("vip_monthly")) {
purchaseFlowBegan { }
failedToBeginFlow { t -> showError(t) }
purchaseSucceed { purchase -> activateVipOnServer(purchase) } // then acknowledge
purchaseCanceled { }
purchaseFailed { t -> showError(t) }
}
payment.getSubscribedProducts {
querySucceed { subs -> /* currently owned subscriptions */ }
queryFailed { t -> }
}
- دورهها:
P1W،P1M،P3M،P6M،P1Y. - دورهٔ مهلت (grace): اگر تمدید ناموفق باشد، اشتراک وارد
IN_GRACEمیشود (پیشفرض ۳ روز، قابل تنظیم برای هر محصول) و سپسON_HOLDیاEXPIRED. - کاربر میتواند اشتراک را از بخش اشتراکهای بلهاستور لغو کند؛ در این حالت (
CANCELED) تا پایان دورهٔ جاری فعال میماند. - وضعیت معتبر اشتراک (تاریخ انقضا، تمدید خودکار، مهلت) را از سرور بگیرید:
GET /s2s/v1/apps/{packageName}/subscriptions/{purchaseToken}و رویدادهایsubscription.*در Webhookها. - دورهٔ آزمایشی رایگان (free trial) هنوز پشتیبانی نمیشود.
۷. تشخیص منبع نصب
if (BaleStoreInstallSource.isInstalledFromBaleStore(context)) {
// installed (or last updated as installer of record) by Bale Store
}
val installer: String? = BaleStoreInstallSource.getInstallerPackageName(context)
when (BaleStoreInstallSource.detect(context)) {
InstallSource.BALE_STORE -> { }
InstallSource.BAZAAR -> { }
InstallSource.MYKET -> { }
InstallSource.GOOGLE_PLAY -> { }
InstallSource.OTHER -> { } // another installer / sideload
InstallSource.UNKNOWN -> { } // no installer information
}
روی API 30 به بالا از PackageManager.getInstallSourceInfo و پایینتر از getInstallerPackageName استفاده میشود.
| فروشگاه | نام بستهٔ نصبکننده |
|---|---|
| بلهاستور | ir.nasim (پیامرسان بله) یا ir.bale.balestore.installer (برنامهٔ نصبکنندهٔ مستقل) |
| بازار | com.farsitel.bazaar |
| مایکت | ir.mservices.market |
۸. کوروتین و Flow
افزونههای ir.bale.balestore.sdk.ktx همهٔ APIها را به شکل suspend و Flow در اختیارتان میگذارند:
import ir.bale.balestore.sdk.ktx.*
lifecycleScope.launch {
// connects on collect, disconnects when the coroutine is cancelled
payment.connectionFlow().collect { state ->
if (state == ConnectionState.Connected) {
val skus = payment.awaitInAppSkuDetails(listOf("coins_100"))
val pending = payment.awaitPurchasedProducts()
pending.filter { it.purchaseState == PurchaseState.PURCHASED }.forEach { handle(it) }
}
}
}
fun buy(productId: String) = lifecycleScope.launch {
payment.purchaseFlow(activityResultRegistry, PurchaseRequest(productId, payload = "order-42"))
.collect { event ->
when (event) {
PurchaseEvent.FlowBegan -> showProgress()
is PurchaseEvent.Succeeded -> {
verifyOnServer(event.purchase) // your backend
payment.awaitConsume(event.purchase.purchaseToken)
}
PurchaseEvent.Canceled -> hideProgress()
is PurchaseEvent.Failed -> showError(event.error)
}
}
}
| تابع | خروجی |
|---|---|
connectionFlow() |
Flow<ConnectionState> |
awaitInAppSkuDetails(skuIds) / awaitSubscriptionSkuDetails(skuIds) |
List<SkuDetails> |
awaitPurchasedProducts() / awaitSubscribedProducts() |
List<PurchaseInfo> |
awaitConsume(purchaseToken) / awaitAcknowledge(purchaseToken) |
Unit |
purchaseFlow(registry, request) / subscribeFlow(registry, request) |
Flow<PurchaseEvent> |
توابع await… در صورت خطا همان استثناهای بخش خطاها را پرتاب میکنند.
۹. تأیید محلی توکن خرید
با SecurityCheck.Enable(publicKeyPem)، SDK امضای ES256 هر توکن خرید را با کلید عمومی برنامه بررسی میکند و تطابق نام بسته و شناسهٔ محصول را میسنجد. اگر بررسی شکست بخورد، purchaseFailed با PurchaseHijackedException فراخوانی میشود.
برای بررسی دستی (مثلاً توکنی که از جای دیگری آمده):
try {
val v: VerifiedPurchaseToken = PurchaseTokenVerifier.verify(purchase.purchaseToken, publicKeyPem)
// v.kid, v.orderId, v.packageName, v.productId, v.purchaseTime, v.purchaseState,
// v.developerPayload, v.userHash, v.type ("inapp" | "subs" | "app"), v.expiryTime (subscriptions)
} catch (e: PurchaseTokenVerificationException) {
// invalid signature, unknown kid, malformed token…
}
تأیید روی دستگاه را میتوان روی گوشی روتشده دور زد. مرجع نهایی، تأیید در سرور شماست (S2S یا بررسی امضا در سرور). ببینید: تأیید توکن خرید.
۱۰. سندباکس و آزمون
بدون پول واقعی میتوانید SDK را از ابتدا تا انتها آزمایش کنید:
- آزمایشگرهای مجوز (License testers): در کنسول، کاربران بله را به فهرست آزمایشگرهای برنامه اضافه کنید (
/console/v1/billing/apps/{appId}/license-testers). خریدهای آنها رایگان است و با پرچم آزمایشی ثبت میشود (در پاسخ S2S:"test": true)؛ سرور شما میتواند با همین پرچم خریدهای آزمایشی را از خریدهای واقعی جدا کند. - محصولات آزمایشی: هنگام تعریف محصول، گزینهٔ «آزمایشی» (
isTest) را بزنید تا فقط برای آزمون باشد. - صفحهٔ پرداخت سندباکس: در محیط سندباکس، بهجای صفحهٔ پرداخت بله یک صفحهٔ فارسی آزمایشی باز میشود که میتوانید نتیجه را انتخاب کنید:
| نتیجه | رفتار |
|---|---|
success |
پرداخت موفق؛ purchaseSucceed |
insufficient_funds |
موجودی ناکافی؛ purchaseFailed |
failed |
خطای پرداخت؛ purchaseFailed |
پیشنهاد میکنیم این سناریوها را آزمایش کنید: خرید موفق، لغو کاربر، موجودی ناکافی، بسته شدن برنامه پیش از consume (و پردازش در اجرای بعدی)، و قطع اتصال سرویس (disconnected).
۱۱. پشتیبانی همزمان از چند فروشگاه (StoreRouter)
اگر برنامهٔ شما در بازار و مایکت هم منتشر میشود، لایهٔ انتزاعی متنباز ir.bale.balestore.sdk.store کمک میکند با یک کد، پرداخت فروشگاهی را استفاده کنید که برنامه از آن نصب شده است:
import ir.bale.balestore.sdk.store.*
interface BillingBackend {
val store: StoreId
suspend fun connect(): Boolean
suspend fun skuDetails(type: ProductType, skus: List<String>): List<SkuDetails>
suspend fun purchase(registry: ActivityResultRegistry, type: ProductType, request: PurchaseRequest): PurchaseInfo
suspend fun purchases(type: ProductType): List<PurchaseInfo>
suspend fun consume(purchaseToken: String)
suspend fun acknowledge(purchaseToken: String)
fun disconnect()
}
enum class StoreId { BALE_STORE, BAZAAR, MYKET }
enum class ProductType { INAPP, SUBS }
val backend: BillingBackend = StoreRouter(
context,
baleStore = BaleStoreBackend(payment),
bazaar = PoolakeyBackend(context, bazaarRsaKey), // optional: your adapter
myket = null // optional
).select()
lifecycleScope.launch {
if (!backend.connect()) return@launch
val coins = backend.skuDetails(ProductType.INAPP, listOf("coins_100"))
val p = backend.purchase(activityResultRegistry, ProductType.INAPP, PurchaseRequest("coins_100"))
verifyOnServer(backend.store, p)
backend.consume(p.purchaseToken)
}
select() بر اساس منبع نصب انتخاب میکند؛ اگر منبع نامعلوم باشد یا آداپتر فروشگاه مربوط را نداده باشید، بلهاستور را برمیگرداند. آداپترهای بازار و مایکت جزو SDK نیستند (تا وابستگی اضافه نداشته باشید)؛ نمونهٔ آداپتر Poolakey در راهنمای مهاجرت از Poolakey آمده است.
سرور شما باید بداند خرید از کدام فروشگاه آمده (
backend.store) تا آن را با API همان فروشگاه بررسی کند.
<a id="errors"></a>
۱۲. خطاها
| استثنا | معنی | پیشنهاد |
|---|---|---|
BaleStoreNotFoundException |
بله (یا نصبکنندهٔ بلهاستور) روی دستگاه نیست یا نسخهٔ آن سرویس پرداخت ندارد | دکمهٔ خرید را پنهان کنید یا راهنمای نصب/بهروزرسانی بله را نشان دهید |
BillingNotSupportedException |
پرداخت برای این برنامه یا نوع محصول فعال نیست | فروشگاه درونبرنامه را پنهان کنید |
DisconnectedException |
اتصال به سرویس قطع است | دوباره connect کنید |
PurchaseHijackedException |
بررسی امنیتی محلی شکست خورد (امضا یا اطلاعات توکن نامعتبر) | محصول را ندهید؛ رخداد را ثبت کنید |
BaleStoreBillingException(code, message) |
خطای سمت سرور با یک کد دامنه؛ message فارسی و قابل نمایش است |
بر اساس code تصمیم بگیرید |
کدهای رایج در BaleStoreBillingException.code:
| کد | معنی |
|---|---|
BILLING_DISABLED |
پرداخت موقتاً غیرفعال است (نصب برنامههای رایگان ادامه دارد) |
SKU_NOT_FOUND |
شناسهٔ محصول وجود ندارد یا غیرفعال است |
ALREADY_OWNED |
کاربر این محصول غیرمصرفی را قبلاً خریده است |
INSUFFICIENT_FUNDS |
موجودی کافی نیست |
PAYMENT_FAILED |
پرداخت ناموفق بود |
PURCHASE_NOT_FOUND |
توکن خرید یافت نشد |
ALREADY_CONSUMED |
این خرید قبلاً مصرف شده است |
UNAUTHORIZED |
کاربر در بله وارد حساب نیست |
RATE_LIMITED |
درخواستها بیش از حد مجاز است؛ کمی بعد تلاش کنید |
۱۳. ProGuard / R8
AAR قواعد consumer لازم را همراه دارد و معمولاً کاری لازم نیست. اگر در بیلد minifyشده خطایی مثل ClassNotFoundException یا AbstractMethodError در اتصال به سرویس دیدید، این قواعد را اضافه کنید:
-keep class ir.bale.balestore.billing.** { *; } # AIDL interface
-keep class ir.bale.balestore.sdk.** { *; }
اگر SDK را از طریق بازتاب (reflection) یا JNI صدا میزنید (مثل Unity)، کلاسهای پل خودتان را هم keep کنید.
چکلیست انتشار
- کلید عمومی تولیدی (نه سندباکس) در بیلد انتشار است.
- هر خرید پیش از دادن محصول در سرور تأیید میشود.
- همهٔ خریدها مصرف یا تأیید میشوند (مهلت پیشفرض ۳ روز).
- پس از هر اتصال، خریدهای ناتمام پردازش میشوند.
-
connection.disconnect()درonDestroyصدا زده میشود. - Webhook برای
purchase.refundedتنظیم شده تا محصول بازپرداختشده پس گرفته شود.