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 تنظیم شده تا محصول بازپرداخت‌شده پس گرفته شود.