پرش به مطلب اصلی

راهنمای پرداخت درون‌برنامه‌ای مایکت در Unreal Engine

Unreal Engine
پروژه نمونه

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

پلاگین Myket In-App Billing SDK ابزار رسمی برای پیاده‌سازی پرداخت درون‌برنامه‌ای (IAB) مایکت در بازی‌ها و برنامه‌های اندرویدی توسعه‌یافته با موتور بازی‌سازی Unreal Engine (سازگار با نسخه ۵.۰ و نسخه‌های جدیدتر) است. این پلاگین از طریق C++ (زیرسیستم GameInstanceSubsystem) و نودهای Blueprint در دسترس است.

قابلیت‌ها​

  • پشتیبانی از خریدهای درون‌برنامه‌ای: امکان خرید محصولات مصرف‌شدنی (مانند سکه، اعتبار) و محصولات غیرمصرفی (مانند نسخه ویژه).
  • استعلام موجودی و کاتالوگ: دریافت مشخصات محصولات (عنوان، قیمت محلی، توضیحات) و خریدهای فعال کاربر.
  • مصرف تکی و گروهی: متدهای مصرف تکی (ConsumePurchase / ConsumeProduct) و مصرف هم‌زمان چند محصول.
  • پشتیبانی از C++ و Blueprint: دسترسی از طریق زیرسیستم UMyketBillingSubsystem و نودهای Myket | Billing.
  • رابط کاربری تست رویه ای (UMG/Slate): شامل ویجت تست آماده برای بررسی عملکرد پرداخت.
  • کنسول لاگ روی صفحه: نمایش لاگ رویدادها روی صفحه دستگاه برای تسهیل خطایابی.
  • حالت شبیه‌سازی در ادیتور (PIE): امکان تست منطق Blueprint و رابط کاربری در محیط Play-in-Editor بدون اختلال یا نیاز به دستگاه فیزیکی.

پیش‌نیازها​

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

ساختار پوشه‌های پروژه نمونه​

Unreal/
├── Config/                          # تنظیمات پروژه آنریل
│   ├── DefaultEngine.ini            # تنظیمات GameMode و بسته‌بندی اندروید
│   ├── DefaultGame.ini              # متادیتای پروژه
│   └── DefaultInput.ini             # تنظیمات ورودی لمسی / ماوس
├── Plugins/
│   └── MyketBilling/                # پلاگین مستقل پرداخت مایکت
│       ├── Java/                    # پل ارتباطی جاوا (MyketBillingBridge.java)
│       ├── Source/MyketBilling/     # کدهای C++ ساب‌سیستم، پل JNI و رابط کاربری تست
│       ├── MyketBilling_UPL.xml     # تنظیمات مانیفست و گریدل با زبان UPL
│       ├── MyketBilling.Build.cs    # قوانین بیلد ماژول
│       ├── MyketBilling.uplugin     # شناسه پلاگین
│       └── README.md                # راهنمای فنی اختصاصی پلاگین
├── Source/
│   ├── MyketSample/                 # ماژول بازی پروژه نمونه
│   │   ├── MyketSampleGameMode.h/.cpp # اجرای خودکار UI تست در ابتدای بازی
│   │   ├── MyketSampleModule.h/.cpp
│   │   └── MyketSample.Build.cs
│   ├── MyketSample.Target.cs
│   └── MyketSampleEditor.Target.cs
├── MyketSample.uproject             # فایل پروژه آنریل انجین
└── README.md

اجرای سریع پروژه نمونه​

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

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

۱. اجرای در محیط ادیتور (Play-in-Editor / PIE)​

۱. مخزن پروژه را دریافت کنید:

git clone https://github.com/myketstore/billing-sample-unrealengine.git

۲. فایل MyketSample.uproject را در نسخه سازگار Unreal Engine باز کنید.
۳. دکمه Play را در ویرایشگر بزنید.
۴. کلاس MyketSampleGameMode به‌صورت خودکار پنل تعاملی تست را روی صفحه نمایش می‌دهد. در محیط PIE کدهای شبیه‌ساز امن اجرا می‌شوند تا بدون خطا منطق برنامه را بررسی کنید.

۲. بسته‌بندی و اجرا روی دستگاه اندروید​

۱. دستگاه اندرویدی را به سیستم وصل کنید (حالت Developer Mode و USB Debugging فعال باشد).
۲. مطمئن شوید برنامه مایکت روی دستگاه نصب است.
۳. از منوی اصلی به مسیر Platforms → Android → Package Project بروید (یا از دکمه Quick Launch برای نصب مستقیم استفاده کنید).
۴. برنامه را روی گوشی باز کنید. ابتدا روی دکمه Initialize IAB بزنید و پس از دریافت پیام اتصال موفق، عملیات خرید و استعلام را تست کنید.

افزودن پلاگین به پروژه موجود​

برای افزودن پلاگین مایکت به پروژه جاری خود:

۱. انتقال پوشه پلاگین​

پوشه Plugins/MyketBilling را از مخزن نمونه به پوشه Plugins/ در ریشه پروژه خود کپی کنید (اگر این پوشه وجود ندارد، آن را بسازید).

۲. فعال‌سازی در فایل .uproject​

فایل پروژه (.uproject) را در یک ادیتور متن باز کرده و پلاگین را اضافه کنید:

{
  "Plugins": [
    {
      "Name": "MyketBilling",
      "Enabled": true
    }
  ]
}

اگر فایل شما از قبل دارای بخش Plugins است، ورودی فوق را به همان آرایه اضافه کنید و کل فایل را بازنویسی نکنید.

۳. افزودن ماژول به Build.cs​

در فایل [ProjectName].Build.cs ماژول بازی خود، نام ماژول MyketBilling را به وابستگی‌های عمومی اضافه کنید:

PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject",
    "Engine",
    "InputCore",
    "MyketBilling"
});

۴. تنظیمات اندروید در پروژه​

در تنظیمات پروژه (Project Settings > Platforms > Android):

  • مقدار Android Package Name را دقیقاً با پکیج ثبت‌شده در مایکت یکسان قرار دهید.
  • حداقل نسخه Target SDK را ۳۰ یا بالاتر تنظیم کنید.
  • فایل UPL پلاگین (MyketBilling_UPL.xml) به‌صورت خودکار مخازن Maven مایکت، وابستگی کلاینت پرداخت، مجوز BILLING و اعلان‌های دسترسی بسته (<queries>) را در زمان بیلد به پروژه اندروید اضافه می‌کند.

راهنمای استفاده از API​

پلاگین یک Subsystem در سطح GameInstance به نام UMyketBillingSubsystem ارائه می‌دهد که مدیریت سراسری چرخه پرداخت را بر عهده دارد.

۱. پیاده‌سازی در C++​

مقداردهی اولیه و اتصال​

در یکی از کلاس‌های بازی (مانند GameMode، PlayerController یا اسکریپت فروشگاه):

#include "MyketBillingSubsystem.h"
#include "Kismet/GameplayStatics.h"

void AMyGameMode::InitBilling()
{
    UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
    if (!GameInstance) return;

    UMyketBillingSubsystem* Billing = GameInstance->GetSubsystem<UMyketBillingSubsystem>();
    if (!Billing) return;

    // متصل شدن به رویدادهای بازگشتی
    Billing->OnBillingSupported.AddDynamic(this, &AMyGameMode::HandleBillingSupported);
    Billing->OnBillingNotSupported.AddDynamic(this, &AMyGameMode::HandleBillingNotSupported);
    Billing->OnPurchaseFinished.AddDynamic(this, &AMyGameMode::HandlePurchaseFinished);
    Billing->OnConsumeFinished.AddDynamic(this, &AMyGameMode::HandleConsumeFinished);
    Billing->OnQueryInventoryFinished.AddDynamic(this, &AMyGameMode::HandleInventoryFinished);

    // راه‌اندازی با کلید عمومی Base64 مایکت
    Billing->Init(TEXT("YOUR_MYKET_BASE64_PUBLIC_KEY"));
}

استعلام موجودی و محصولات​

پس از موفقیت رویداد OnBillingSupported، اطلاعات محصولات و خریدهای قبلی را استعلام کنید:

void AMyGameMode::HandleBillingSupported()
{
    UMyketBillingSubsystem* Billing = GetGameInstance()->GetSubsystem<UMyketBillingSubsystem>();
    if (Billing)
    {
        TArray<FString> Skus = { TEXT("gem_pack_100"), TEXT("premium_upgrade") };
        Billing->QueryInventory(Skus);
    }
}

شروع فرآیند خرید​

void AMyGameMode::BuyProduct(FString Sku)
{
    UMyketBillingSubsystem* Billing = GetGameInstance()->GetSubsystem<UMyketBillingSubsystem>();
    if (Billing)
    {
        FString DeveloperPayload = TEXT("unique_order_payload_123");
        Billing->PurchaseProduct(Sku, DeveloperPayload);
    }
}
نکته

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

مدیریت نتیجه خرید و مصرف محصول​

void AMyGameMode::HandlePurchaseFinished(const FMyketPurchase& Purchase, const FMyketResult& Result)
{
    if (Result.bIsSuccess)
    {
        // در صورت مصرفی بودن (مانند سکه، بنزین):
        if (Purchase.ProductId == TEXT("gem_pack_100"))
        {
            UMyketBillingSubsystem* Billing = GetGameInstance()->GetSubsystem<UMyketBillingSubsystem>();
            if (Billing)
            {
                Billing->ConsumeProduct(Purchase.ProductId);
            }
        }
        else
        {
            // محصول غیرمصرفی (مانند حذف تبلیغات)
            UnlockFeature();
        }
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("خرید ناموفق: %s"), *Result.Message);
    }
}

void AMyGameMode::HandleConsumeFinished(const FMyketPurchase& Purchase, const FMyketResult& Result)
{
    if (Result.bIsSuccess)
    {
        UE_LOG(LogTemp, Log, TEXT("محصول با موفقیت مصرف شد: %s"), *Purchase.ProductId);
        // اعطای جم یا سکه به بازیکن
    }
}
اخطار مهم

محصولات غیرمصرفی (Non-consumable مانند «ارتقا به نسخه ویژه») را هرگز مصرف نکنید. مصرف کالا آن را از لیست خریدهای فعال کاربر حذف می‌کند.

۲. پیاده‌سازی در Blueprint​

تمامی متدها و رویدادهای پلاگین در محیط Blueprint در دسترس هستند:

۱. با گره Get Myket Billing Subsystem به زیرسیستم پرداخت دسترسی پیدا کنید.
۲. رویدادهای زیر را Bind کنید:

  • On Billing Supported
  • On Billing Not Supported
  • On Query Inventory Finished
  • On Purchase Finished
  • On Consume Finished ۳. گره Init را با کلید عمومی مایکت فراخوانی کنید.
    ۴. برای خرید، گره Purchase Product و برای مصرف، گره Consume Product یا Consume Purchase را به کار ببرید.

امکانات ویجت تست نمونه (UMyketTestWidget)​

ویجت تست نمونه به صورت کاملاً کدنویسی‌شده در Slate/UMG پیاده‌سازی شده و امکانات زیر را ارائه می‌دهد:

۱. Initialize IAB: مقداردهی اولیه سرویس پرداخت با کلید عمومی برنامه.
۲. Query Inventory: استعلام هم‌زمان اطلاعات و خریدهای فعال ۵ محصول آزمایشی.
۳. Query SkuDetails: استعلام عنوان، قیمت و توضیحات محصولات.
۴. Query Purchases: استعلام خریدهای فعال کاربر.
۵. Purchase Product Test1 / Test2: آغاز خرید محصولات تستی test1 و test2.
۶. Consume Purchase Test1 / Test2: مصرف خریدهای تستی برای امکان خرید مجدد.
۷. Consume Multiple Purchases: مصرف هم‌زمان چندین محصول به‌صورت گروهی.
۸. Test Unavailable Item: بررسی رفتار برنامه در هنگام درخواست محصول ناموجود (unavailable).
۹. Custom SKU Field: امکان وارد کردن دستی هر SKU دلخواه و تست خرید و مصرف آن بدون نیاز به کامپایل مجدد.
۱۰. Live On-Screen Log Console: پنجره متنی زنده روی صفحه دستگاه برای مشاهده تمامی رویدادها و خطاها بدون نیاز به کابل یا ADB.

نکات امنیتی و رفع خطا​

  • تست واقعی: عملیات پرداخت واقعی را تنها روی دستگاه فیزیکی اندرویدی که برنامه مایکت روی آن نصب و لاگین‌شده است تست کنید؛ محیط Play-in-Editor صرفاً یک شبیه‌ساز برای بررسی منطق برنامه است.
  • اعتبارسنجی سمت سرور: برای تراکنش‌های بااهمیت، مقادیر Purchase.OriginalJson و Purchase.Signature را به سرور بفرستید تا با کلید عمومی RSA مایکت اعتبارسنجی شوند.
  • جلوگیری از تحویل تکراری: توکن خرید (Purchase.PurchaseToken) را در دیتابیس ثبت کنید تا با فراخوانی مجدد رویدادها، محصول دو بار تحویل داده نشود.