راهنمای پرداخت درون‌برنامه‌ای مایکت در B4A (Basic4Android)

Basic4Android

پروژه نمونه

برای دریافت فایل‌های کامپایل‌شده کتابخانه و مشاهده پروژه نمونه کامل B4A، به مخزن رسمی در GitHub مراجعه کنید.

کتابخانه Myket In-App Billing SDK for B4A ابزار رسمی برای پیاده‌سازی پرداخت درون‌برنامه‌ای (IAB) مایکت در برنامه‌های توسعه‌یافته با محیط Basic4Android (نسخه B4A v14) است. این کتابخانه یک Wrapper روی کلاینت بومی مایکت (ir.myket.billingclient.IabHelper) نسخه ۲.۲ است و متدها، رویدادها و ویژگی‌های آن را در اختیار توسعه‌دهندگان قرار می‌دهد.

ساختار فایل‌ها و پوشه‌ها

./B4A/
├── MyketBillingLibrary/      # فایل‌های کامپایل‌شده کتابخانه (انتقال به پوشه Additional Libraries)
│   ├── MyketBilling.jar       # فایل باینری Wrapper جاوا به همراه ماکروی مانیفست
│   ├── MyketBilling.xml       # توصیف‌گر تایپ‌ها و راهنمای Autocomplete محیط B4A
│   └── MyketBilling-2.2.aar   # فایل AAR کتابخانه بومی پرداخت مایکت (نسخه ۲.۲)
│
├── MyketBillingSample/       # پروژه نمونه کامل (سناریوی TrivialDrive)
│   ├── MyketBillingSample.b4a
│   ├── MyketBillingSample.b4a.meta
│   ├── Starter.bas
│   ├── Files/                 # فایل‌های گرافیکی بازی
│   └── Objects/               # خروجی کامپایل و فایل APK
│
└── README.md

پیش‌نیازها

۱. داشتن حساب کاربری در پنل توسعه‌دهندگان مایکت.
۲. ثبت برنامه در پنل مایکت و رزرو شناسه بسته (Package Name).
۳. دریافت کلید عمومی RSA پرداخت برنامه از پنل توسعه‌دهندگان مایکت.
۴. تعریف محصولات درون‌برنامه‌ای (SKU) در پنل برنامه.
۵. نصب بودن B4A نسخه ۱۴ و ابزارهای کامپایل اندروید (Android SDK).
۶. نصب بودن آخرین نسخه برنامه مایکت روی دستگاه تست اندرویدی.

مراحل راه‌اندازی و نصب

۱. کپی فایل‌های کتابخانه در B4A

سه فایل موجود در پوشه MyketBillingLibrary را در پوشه Additional Libraries محیط B4A کپی کنید:

MyketBilling.jar
MyketBilling.xml
MyketBilling-2.2.aar

سپس در محیط B4A IDE، به برگه Libraries Manager بروید، دکمه Refresh را بزنید و تیک کتابخانه MyketBilling را فعال کنید.

۲. پیکربندی مانیفست اندروید (Manifest Editor)

از منوی B4A به مسیر Project -> Manifest Editor بروید و ماکروی زیر را اضافه کنید:

CreateResourceFromFile(Macro, MyketBilling.MyketBillingReceiver)

این ماکرو به‌صورت خودکار تمامی تنظیمات زیر را به فایل مانیفست نهایی تزریق می‌کند:

مجوزهای موردنیاز (INTERNET و ir.mservices.market.BILLING)
اعلان‌های دسترسی بسته (<queries>) برای اندروید ۱۱ و بالاتر جهت شناسایی مایکت و مرورگر Chrome
اکتیویتی‌های پرداخت بومی (ProxyBillingActivity, PaymentCallbackActivity, CustomTabLauncherActivity)
متادیتاهای اتصال بازار (market_id, market_bind_address, sdk_version)
گیرنده برودکست (IABReceiver)

۳. وابستگی‌های الزامی پروژه (`#AdditionalJar`)

خطوط زیر را در بخش #Region Project Attributes در ماژول اصلی برنامه (Main) قرار دهید:

#AdditionalJar: androidx.core:core
#AdditionalJar: androidx.browser:browser
#AdditionalJar: org.jetbrains.kotlin-kotlin-stdlib
#AdditionalJar: org.jetbrains.kotlinx-kotlinx-coroutines-core-jvm
#AdditionalJar: org.jetbrains.kotlinx-kotlinx-coroutines-android
#AdditionalJar: okhttp-4.9.0
#AdditionalJar: okio-2.8.0
#AdditionalJar: gson-2.8.5

وابستگی‌های پیش‌فرض

تمامی فایل‌های JAR و AAR فوق به‌صورت پیش‌فرض در SDK همراه B4A v14 موجود هستند و نیاز به دانلود جداگانه ندارند.

راهنمای کدنویسی و متدهای API

۱. تعریف متغیر و راه‌اندازی اولیه

Sub Globals
    Private mHelper As MyketIabHelper ' یا MyketBilling
End Sub

Sub Activity_Create(FirstTime As Boolean)
    ' مقداردهی اولیه با پیشوند نام رویداد (EventName) و کلید عمومی Base64
    mHelper.Initialize("IabHelper", "YOUR_BASE64_PUBLIC_KEY")
    mHelper.EnableDebugLogging(True)
    mHelper.StartSetup
End Sub

۲. رویدادهای اتصال و استعلام موجودی

' رویداد پایان راه‌اندازی و برقراری ارتباط
Private Sub IabHelper_SetupFinished (Result As MyketIabResult)
    If Result.Success Then
        Log("اتصال به سرویس پرداخت مایکت با موفقیت برقرار شد.")
        
        ' استعلام خریدهای فعال و مشخصات محصولات
        Dim skuList As List
        skuList.Initialize
        skuList.Add("gas")
        skuList.Add("premium")
        mHelper.QueryInventoryAsync3(True, skuList)
    Else
        Log("راه‌اندازی پرداخت ناموفق بود: " & Result.Message)
    End If
End Sub

' رویداد دریافت اطلاعات موجودی و خریدهای قبلی
Private Sub IabHelper_QueryInventoryFinished (Result As MyketIabResult, Inventory As MyketInventory)
    If Result.Success Then
        ' ۱. بررسی و مصرف خریدهای مصرفی پردازش‌نشده قبلی
        If Inventory.HasPurchase("gas") Then
            Dim gasPurchase As MyketPurchase = Inventory.GetPurchase("gas")
            mHelper.ConsumeAsync(gasPurchase)
        End If

        ' ۲. بررسی مالکیت محصول غیرمصرفی
        If Inventory.HasPurchase("premium") Then
            Log("کاربر مالک نسخه پرمیوم است.")
            ' فعال‌سازی قابلیت ویژه
        End If
    Else
        Log("دریافت موجودی ناموفق بود: " & Result.Message)
    End If
End Sub

۳. شروع فرآیند خرید و مصرف محصول

' شروع خرید محصول با شناسه SKU و Developer Payload اختیاری
Sub BuyGas_Click
    mHelper.LaunchPurchaseFlow("gas", "payload_tracking_123")
End Sub

' رویداد پایان فرآیند خرید
Private Sub IabHelper_PurchaseFinished (Result As MyketIabResult, Purchase As MyketPurchase)
    If Result.Success Then
        Log("خرید با موفقیت انجام شد: " & Purchase.Sku)
        
        ' در صورتی که محصول مصرفی باشد (مانند بنزین یا سکه):
        If Purchase.Sku = "gas" Then
            mHelper.ConsumeAsync(Purchase)
        Else
            ' محصول ماندگار / غیرمصرفی (مانند پرمیوم)
            UnlockFeature
        End If
    Else
        Log("خطا در خرید محصول: " & Result.Message)
    End If
End Sub

' رویداد پایان عملیات مصرف محصول
Private Sub IabHelper_ConsumeFinished (Purchase As MyketPurchase, Result As MyketIabResult)
    If Result.Success Then
        Log("محصول با موفقیت مصرف شد: " & Purchase.Sku)
        ' اعطای اعتبار یا شارژ بنزین به کاربر
    Else
        Log("خطا در مصرف محصول: " & Result.Message)
    End If
End Sub

نکته

توجه کنید که مقدار طول رشته‌ی developerPayload نمی‌تواند بیش‌تر از ۸۰۰ کاراکتر باشد.

اخطار مهم

محصولات غیرمصرفی (Non-consumable مانند «ارتقا به نسخه پرمیوم») را هرگز مصرف نکنید. متد ConsumeAsync باید صرفاً برای محصولات مصرف‌شدنی فراخوانی شود.

۴. آزادسازی منابع در چرخه حیات Activity

برای آزادسازی اتصال و جلوگیری از نشت حافظه، در رویداد Activity_Pause متد Dispose را فراخوانی کنید:

Sub Activity_Pause (UserClosed As Boolean)
    If UserClosed And mHelper.IsInitialized Then
        mHelper.Dispose
    End If
End Sub

جدول متدهای API (`MyketIabHelper`)

نام متد	توضیحات
`Initialize(EventName, Base64PublicKey)`	مقداردهی اولیه Helper با پیشوند رویداد و کلید عمومی RSA
`EnableDebugLogging(Enable)`	فعال یا غیرفعال کردن لاگ‌های دیباگ در Logcat
`EnableDebugLogging2(Enable, Tag)`	فعال‌سازی لاگ‌ها با تگ سفارشی
`StartSetup()`	برقراری ارتباط غیرهم‌زمان با سرویس پرداخت مایکت
`StartSetup2(EventName)`	برقراری ارتباط با تعریف پیشوند رویداد سفارشی
`LaunchPurchaseFlow(Sku, DeveloperPayload)`	شروع فرآیند خرید محصول همراه با Payload
`LaunchPurchaseFlow2(Sku)`	شروع فرآیند خرید محصول بدون Payload
`LaunchPurchaseFlowCustom(EventName, Sku, ItemType, Payload)`	شروع خرید با تعریف رویداد و نوع آیتم سفارشی
`QueryInventoryAsync()`	استعلام غیرهم‌زمان خریدهای کاربر و اطلاعات محصولات
`QueryInventoryAsync2(QuerySkuDetails)`	استعلام خریدهای کاربر با تعیین دریافت یا عدم دریافت اطلاعات کاتالوگ
`QueryInventoryAsync3(QuerySkuDetails, SkuList)`	استعلام خریدهای کاربر به همراه لیست مشخصی از SKUها از نوع `List`
`QueryInventoryAsync4(QuerySkuDetails, SkuIds)`	استعلام خریدهای کاربر به همراه آرایه‌ای از SKUها از نوع `String[]`
`ConsumeAsync(Purchase)`	مصرف غیرهم‌زمان محصول خریداری‌شده
`ConsumeAsync2(EventName, Purchase)`	مصرف غیرهم‌زمان محصول با رویداد بازگشتی سفارشی
`Dispose()`	بستن ارتباط سرویس پرداخت و آزادسازی منابع
`GetResponseDesc(Code)`	تبدیل کد عددی پاسخ به متن پیام توصیفی

رویدادهای بازگشتی (Events)

ساختار رویداد	زمان فراخوانی
`Sub EventName_SetupFinished (Result As MyketIabResult)`	پایان موفق یا ناموفق برقراری ارتباط با سرویس مایکت
`Sub EventName_QueryInventoryFinished (Result As MyketIabResult, Inventory As MyketInventory)`	پایان استعلام موجودی و خریدهای فعال کاربر
`Sub EventName_PurchaseFinished (Result As MyketIabResult, Purchase As MyketPurchase)`	پایان فرآیند خرید (موفقیت، انصراف یا خطا)
`Sub EventName_ConsumeFinished (Purchase As MyketPurchase, Result As MyketIabResult)`	پایان عملیات مصرف محصول

پروژه نمونه (TrivialDrive)

پشتیبانی از اشتراک

وجود سناریوی اشتراک در کد نمونه به معنی پشتیبانی فعلی مایکت از اشتراک نیست. طبق مستندات فعلی، مایکت از محصولات اشتراکی پشتیبانی نمی‌کند؛ بنابراین بخش مربوط به اشتراک را برای محصول واقعی استفاده نکنید.

پروژه نمونه کامل موجود در پوشه B4A/MyketBillingSample/ سناریوی TrivialDrive را پیاده‌سازی کرده است:

بنزین مصرفی (gas): با هر بار خرید و مصرف، یک‌چهارم باک پر می‌شود.
ارتقای دائمی (premium): ماشین را به‌صورت دائمی به مدل قرمز ارتقا می‌دهد.
رابط کاربری کامپوننت‌های B4A: طراحی کاملاً واکنش‌گرا با گرافیک باکیفیت و بدون وابستگی‌های اضافی.

ساختار فایل‌ها و پوشه‌ها​

پیش‌نیازها​

مراحل راه‌اندازی و نصب​

۱. کپی فایل‌های کتابخانه در B4A​

۲. پیکربندی مانیفست اندروید (Manifest Editor)​

۳. وابستگی‌های الزامی پروژه (#AdditionalJar)​

راهنمای کدنویسی و متدهای API​

۱. تعریف متغیر و راه‌اندازی اولیه​

۲. رویدادهای اتصال و استعلام موجودی​

۳. شروع فرآیند خرید و مصرف محصول​

۴. آزادسازی منابع در چرخه حیات Activity​

جدول متدهای API (MyketIabHelper)​

رویدادهای بازگشتی (Events)​

پروژه نمونه (TrivialDrive)​