title: "افزونهٔ Unity" order: 4 description: "پرداخت درون‌برنامه‌ای و اشتراک بله‌استور در بازی‌های Unity اندروید"

افزونهٔ Unity

افزونهٔ Unity بله‌استور یک لایهٔ نازک C# روی SDK اندروید است. کد منبع آن (به‌همراه نمونهٔ کامل) به‌صورت متن‌باز منتشر می‌شود و در مخزن در مسیر android/unity-plugin/ قرار دارد.

بخش مسیر
API سی‌شارپ (namespace BaleStore.Billing) Runtime/BaleStoreBilling.cs
پل جاوا Android/ir/bale/balestore/unity/BaleStoreUnityBridge.java
اکتیویتی واسط شفاف برای خرید Android/ir/bale/balestore/unity/BaleStoreProxyActivity.java
قطعهٔ manifest Android/AndroidManifest.xml
وابستگی‌ها برای EDM4U Editor/BaleStoreBillingDependencies.xml
نمونه Samples/BillingSample.cs

نحوهٔ کار

  • C# با AndroidJavaClass متدهای ایستای BaleStoreUnityBridge را صدا می‌زند و نتیجه را از طریق یک AndroidJavaProxy (رابط BaleStoreUnityBridge$Callback) دریافت می‌کند. به GameObject نام‌دار یا UnitySendMessage نیازی نیست.
  • همهٔ کال‌بک‌ها روی نخ اصلی Unity اجرا می‌شوند (یک GameObject پنهان با DontDestroyOnLoad صف را خالی می‌کند)؛ پس داخل کال‌بک می‌توانید آزادانه با اشیای Unity کار کنید.
  • SDK برای خرید به ActivityResultRegistry نیاز دارد. چون اکتیویتی Unity لزوماً ComponentActivity نیست، پل یک اکتیویتی شفاف (BaleStoreProxyActivity) باز می‌کند که صفحهٔ پرداخت بله را با registry خودش اجرا می‌کند، نتیجه را دقیقاً یک بار برمی‌گرداند و بسته می‌شود.
  • در Editor و پلتفرم‌های غیراندرویدی، همهٔ فراخوانی‌ها بلافاصله با خطای NOT_SUPPORTED_PLATFORM تمام می‌شوند و هیچ استثنایی پرتاب نمی‌شود.

نصب

  1. پوشه را در پروژه کپی کنید، مثلاً در Assets/Plugins/BaleStoreBilling/.

  2. فایل‌های جاوا را در Assets/Plugins/Android/BaleStoreBilling/ بگذارید (Unity فایل‌های .java را در بیلد Gradle کامپایل می‌کند؛ در Inspector، پلتفرم Android باید فعال باشد).

  3. در Player Settings → Publishing Settings گزینهٔ Custom Main Manifest را فعال کنید و بلوک <queries> و عنصر <activity … BaleStoreProxyActivity …/> را از Android/AndroidManifest.xml به Assets/Plugins/Android/AndroidManifest.xml اضافه کنید:

    <queries>
        <package android:name="ir.nasim" />
        <package android:name="ir.bale.balestore.installer" />
        <intent><action android:name="ir.bale.balestore.billing.BIND" /></intent>
    </queries>
    <application>
        <activity
            android:name="ir.bale.balestore.unity.BaleStoreProxyActivity"
            android:exported="false"
            android:excludeFromRecents="true"
            android:theme="@android:style/Theme.Translucent.NoTitleBar"
            android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation|uiMode|density|locale|layoutDirection|fontScale" />
    </application>
    
  4. وابستگی‌های بومی را اضافه کنید (یکی از این راه‌ها):

    • EDM4U (پیشنهادی): External Dependency Manager for Unity را نصب کنید، نشانی مخزن Maven بله‌استور را در Editor/BaleStoreBillingDependencies.xml بگذارید (نشانی در حال نهایی‌شدن است) و Android Resolver → Resolve را بزنید. وابستگی‌های گذرا (Kotlin stdlib، kotlinx-coroutines، AndroidX) خودکار می‌آیند.

    • قالب Gradle: گزینهٔ Custom Main Gradle Template را فعال کنید و این‌ها را اضافه کنید:

      dependencies {
          implementation 'ir.bale.balestore:billing-sdk:1.0.0'
          implementation 'androidx.activity:activity:1.8.2'
      }
      
    • دستی: فایل AAR بیلینگ را به‌همراه همهٔ وابستگی‌های گذرایش (حداقل kotlin-stdlib، kotlinx-coroutines، androidx.activity، androidx.core و androidx.lifecycle) در Assets/Plugins/Android/ بگذارید. این روش خطاپذیر است.

  5. اگر minify فعال است، این قواعد را به proguard-user.txt اضافه کنید (پل با نام از C# صدا زده می‌شود):

    -keep class ir.bale.balestore.unity.** { *; }
    -keep class ir.bale.balestore.sdk.** { *; }
    -keep class ir.bale.balestore.billing.** { *; }
    

API

namespace BaleStore.Billing
{
    public static class BaleStoreBilling
    {
        public static event Action<string> Disconnected;
        public static bool IsConnected { get; }

        public static void Initialize(string publicKeyPem, Action<bool, string> onConnected);
        public static void GetSkuDetails(string[] skus, bool subs, Action<SkuDetails[], string> callback);
        public static void Purchase(string productId, string payload, Action<PurchaseInfo, string> callback);
        public static void Subscribe(string productId, string payload, Action<PurchaseInfo, string> callback);
        public static void GetPurchases(bool subs, Action<PurchaseInfo[], string> callback);
        public static void Consume(string purchaseToken, Action<bool, string> callback);
        public static void Acknowledge(string purchaseToken, Action<bool, string> callback);
        public static bool IsInstalledFromBaleStore();
        public static InstallSource GetInstallSource(); // BALE_STORE, BAZAAR, MYKET, GOOGLE_PLAY, OTHER, UNKNOWN
        public static void Disconnect();
    }

    [Serializable] public class SkuDetails
    { public string sku, type /* "inapp" | "subs" */, title, description; public long priceRials; public string priceText, period; }

    [Serializable] public class PurchaseInfo
    {
        public string orderId, purchaseToken, payload, packageName, purchaseState;
        public long purchaseTime;          // epoch ms
        public string productId, originalJson, dataSignature;
        public PurchaseState State { get; } // PENDING, PURCHASED, ACKNOWLEDGED, CONSUMED, REFUNDED, AUTO_REFUNDED
    }
}

در همهٔ کال‌بک‌ها، آرگومان آخر error است: در صورت موفقیت null، و در صورت خطا رشته‌ای به شکل "CODE: پیام فارسی". با BaleStoreErrors.CodeOf(error) کد و با BaleStoreErrors.MessageOf(error) پیام قابل نمایش را جدا کنید.

نمونهٔ استفاده

using BaleStore.Billing;
using UnityEngine;

public class Shop : MonoBehaviour
{
    [TextArea] public string publicKeyPem; // from the console: Monetization → Keys

    void Start()
    {
        BaleStoreBilling.Initialize(publicKeyPem, (connected, error) =>
        {
            if (!connected) { Debug.Log("shop disabled: " + error); return; } // e.g. BALE_STORE_NOT_FOUND
            // finish purchases interrupted by a crash, restore non-consumables
            BaleStoreBilling.GetPurchases(false, (list, err) =>
            {
                if (err == null) foreach (var p in list) Handle(p);
            });
        });
    }

    public void BuyCoins()
    {
        BaleStoreBilling.Purchase("coins_100", "order-42", (p, error) =>
        {
            if (error != null)
            {
                if (BaleStoreErrors.CodeOf(error) != BaleStoreErrors.UserCancelled)
                    ShowToast(BaleStoreErrors.MessageOf(error));
                return;
            }
            Handle(p);
        });
    }

    void Handle(PurchaseInfo p)
    {
        if (p.State != PurchaseState.PURCHASED) return;
        // send p.purchaseToken to your server → S2S verify → grant, then:
        BaleStoreBilling.Consume(p.purchaseToken, (ok, err) => { if (ok) AddCoins(100); });
    }

    void OnApplicationQuit() => BaleStoreBilling.Disconnect();

    void ShowToast(string m) { }
    void AddCoins(int n) { }
}

نمونهٔ کامل‌تر (جزئیات محصول، اشتراک، تأیید غیرمصرفی‌ها، بازیابی خریدها و تشخیص منبع نصب) در Samples/BillingSample.cs است.

کدهای خطا

کد معنی
NOT_SUPPORTED_PLATFORM اجرا در Editor یا پلتفرم غیراندرویدی
NOT_INITIALIZED پیش از Initialize صدا زده شده
BALE_STORE_NOT_FOUND بله یا نصب‌کنندهٔ بله‌استور روی دستگاه نیست یا قدیمی است
BILLING_NOT_SUPPORTED پرداخت برای این برنامه فعال نیست
DISCONNECTED اتصال به سرویس قطع شد؛ دوباره Initialize کنید
PURCHASE_HIJACKED بررسی امنیتی محلی توکن خرید شکست خورد؛ محصول را ندهید
USER_CANCELLED کاربر صفحهٔ پرداخت را بست
PURCHASE_IN_PROGRESS یک خرید دیگر در جریان است
PURCHASE_INTERRUPTED روند خرید نیمه‌کاره ماند؛ با GetPurchases وضعیت را بررسی کنید
INVALID_ARGUMENT ورودی خالی یا نامعتبر
کدهای سرور مثل SKU_NOT_FOUND، ALREADY_OWNED، INSUFFICIENT_FUNDS، PAYMENT_FAILED، ALREADY_CONSUMED، BILLING_DISABLED (ببینید: SDK اندروید)

نکته‌های مهم

  • قیمت‌ها ریال هستند (priceRials)؛ برای نمایش از priceText (متن فارسی به تومان) استفاده کنید.
  • محصولات مصرفی را Consume و غیرمصرفی‌ها و اشتراک‌ها را Acknowledge کنید. خریدی که تا مهلت (پیش‌فرض ۳ روز، قابل تنظیم) نهایی نشود، خودکار بازپرداخت می‌شود.
  • پس از هر Initialize موفق، GetPurchases را صدا بزنید تا خریدهای ناتمام پردازش شوند.
  • هر خرید را پیش از دادن محصول در سرور خودتان تأیید کنید (API سرور).
  • برای آزمون بدون پول، حساب بلهٔ خود را در کنسول به فهرست آزمایشگرهای مجوز اضافه کنید؛ خریدهای شما رایگان و آزمایشی ثبت می‌شوند.

محدودیت‌ها

  • فقط اندروید؛ بستهٔ منبع است (هنوز .unitypackage یا بستهٔ UPM آماده منتشر نشده).
  • در هر لحظه فقط یک خرید.
  • اگر اندروید فرایند بازی را هنگام باز بودن صفحهٔ پرداخت ببندد، کال‌بک از دست می‌رود؛ خرید در اجرای بعدی با GetPurchases بازیابی می‌شود.
  • دورهٔ آزمایشی رایگان اشتراک هنوز پشتیبانی نمی‌شود.