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تمام میشوند و هیچ استثنایی پرتاب نمیشود.
نصب
پوشه را در پروژه کپی کنید، مثلاً در
Assets/Plugins/BaleStoreBilling/.فایلهای جاوا را در
Assets/Plugins/Android/BaleStoreBilling/بگذارید (Unity فایلهای.javaرا در بیلد Gradle کامپایل میکند؛ در Inspector، پلتفرم Android باید فعال باشد).در 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>وابستگیهای بومی را اضافه کنید (یکی از این راهها):
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/بگذارید. این روش خطاپذیر است.
اگر 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بازیابی میشود. - دورهٔ آزمایشی رایگان اشتراک هنوز پشتیبانی نمیشود.