راهنمای بسته‌ی پرداخت در اندروید

 دریافت کد نمونه

نمونه این کد را در گیتهاب مشاهده کنید: https://github.com/nivadcloud/InAppBillingAndroidSample

file_downloadدانلود اپلیکیشن نمونه

نمونه‌ی فایل apk را می‌توانید از بخش releases گیتهاب دریافت کنید.

کتابخانه‌ی پرداخت نیواد در دو حالت ایمن و عادی قابل استفاده است.

حالت عادی اپلیکیشن یا بازی شما را از هک شدن پرداخت درون برنامه‌ای با لاکی پچر و... حفاظت نمی‌کند اما استفاده از آن نسبت به نمونه‌ای که بازار و مایکت و سایر مارکت‌های اندرویدی فراهم کرده اند (Trivial Drive) بسیار راحت‌تر است.

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

استفاده از کتابخانه‌ی پرداخت رایگان است.

راه اندازی پرداخت درون برنامه‌ای

گام اول: دریافت کلید RSA از بازار

یک نسخه‌ی apk از اپلیکیشنتان را در پنل بازار بارگزاری کنید. پس از آپلود کامل برنامه به بخش «پرداخت درون‌برنامه‌ای» وارد شوید و با کلیک روی دکمه‌ای که در بخش «کلید RSA» قرار داده شده است کلید مربوط به برنامه‌ی خود را دریافت کنید. این کلید را در جایی کپی و پیست کنید تا بعدا در برنامه استفاده شود.

info جزئیات اطلاعات برنامه در این مرحله اهمیتی ندارند

لزومی ندارد که اطلاعات اپلیکیشنتان را به صورت کامل وارد کنید یا فایل apkی که بارگزاری می‌کنید نسخه‌ی نهایی و کامل برنامه باشد. این اطلاعات در آینده قابل ویرایش هستند.

گام دوم: افزودن کتابخانه‌ی نیواد

با اضافه کردن خطوط زیر به فایل build.gradle و سپس sync کردن gradle کتابخانه‌ی نیواد به پروژه‌تان اضافه خواهد شد.

repositories {
    jcenter()
    maven { url 'http://repo.nivad.io:8081/artifactory/list/libs-release' }
}
dependencies {
    compile 'io.nivad.billing:library:+'
    compile 'com.auth0:java-jwt:2.1.0'
}

file_download دانلود فایل JAR کتابخانه از طریق پنل ممکن است

اگر از gradle استفاده نمی‌کنید و نیاز به فایل jar کتابخانه دارید، می‌توانید فایل jar را پس از عضویت در بخش «پرداخت امن» دریافت کنید. اطلاعات بیشتر

وارد Activity که می‌خواهید در آن پرداخت را اضافه کنید شوید و به خط تعریف کلاس عبارت implements BillingProcessor.IBillingHandler را اضافه کنید. قبل از تابع onCreate متغیر mNivadBilling را از نوع BillingProcessor تعریف کنید و در انتهای onCreate آن را به شکل زیر مقدار دهی کنید.

private BillingProcessor mNivadBilling; // تعریف متغیر

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNivadBilling = new BillingProcessor(this, "Bazaar RSA Key", "Nivad Application ID", "Nivad Application Secret", MarketName.CAFE_BAZAAR, this); // مقدار دهی در انتهای onCreate
}

بجای پارامتر دوم کلید RSA ای که در گام نخست از بازار دریافت کرده اید را وارد کنید. پارامترهای سوم و چهارم را هم با مقادیری که از پنل مدیریتی نیواد دریافت کرده‌اید مقدار دهی کنید. Application ID و Application Secret را می‌توانید در پنل مدیریتی، بخش پرداخت امن بیابید.

پارامتر پنجم نام مارکتی است که سرویس پرداخت باید به آن متصل شود. مارکت‌های پشتیبانی شده کافه بازار و مایکت هستند.

warning حالت غیر امن نیواد (توصیه نمی‌شود)

در صورتی که می‌خواهید از حالت عادی (غیر ایمن) کتابخانه‌ی پرداخت استفاده کنید پارامتر‌های سوم و چهارم (Nivad Application ID و Nivad Application Secret) را حذف کنید و بجای آن‌ها null قرار دهید.

به انتهای کلاس چهار متد زیر را اضافه کنید:

@Override
public void onProductPurchased(String productId, TransactionDetails details) {

}

@Override
public void onBillingError(int errorCode, Throwable error) {

}

@Override
public void onBillingInitialized() {

}

@Override
public void onPurchaseHistoryRestored() {

}

chevron_left توضیح بیشتر دربارهٔ این ۴ متد به همراه جدول کدهای خطا

برای اطلاعات بیشتر از کارکرد این متدها و کدهای خطای متد onBillingError صفحه‌ی راهنمای توابع و کدهای خطای پرداخت را مطالعه فرمایید

تابع onActivityResult را مانند کد زیر ایجاد کنید

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (!mNivadBilling.handleActivityResult(requestCode, resultCode, data))
        super.onActivityResult(requestCode, resultCode, data);
}

 برای آزاد کردن حافظه‌ی گوشی پس از اتمام عملیات پرداخت، متد onDestroy را نیز به صورت زیر به کلاس اضافه کنید:

@Override
public void onDestroy() {
    if (mNivadBilling != null)
        mNivadBilling.release();
    super.onDestroy();
}

گام سوم: اضافه کردن Permission ها

دو اجازه‌ی زیر را به فایل AndroidManifest.xml اضافه کنید.

warning پرمیژن‌ها در حالت غیر ایمن (توصیه نمی‌شود)

در صورتی که از حالت ایمن کتابخانه استفاده نمی‌کنید فقط اجازه‌ی اول (PAY_THROUGH_BAZAAR) لازم است.
<uses-permission android:name="com.farsitel.bazaar.permission.PAY_THROUGH_BAZAAR" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

اگر از مایکت استفاده می‌کنید بجای اجازهٔ کافه بازار باید از permission مایکت استفاده کنید:

<uses-permission android:name="ir.mservices.market.BILLING" />

اکنون اپلیکیشن یا بازی شما آماده‌ی خرید است.

انجام یک خرید

برای آغاز فرایند خرید و هدایت کاربر به بازار باید از متدهای purchase و subscribe استفاده کنید. این دو متد به عنوان پارامتر ورودی به ترتیب Activity (معمولا this) و شناسه‌ی محصول(productId یا sku) را دریافت می‌کنند.

info شناسهٔ محصول چیست؟

شناسه‌ی محصول رشته‌ی منحصر به فردی است که محصولات مختلف را از یکدیگر متمایز می‌کند. این شناسه را در بخش «پرداخت درون‌برنامه‌ای» در پنل بازار زمانی که محصولات و اشتراک‌های اپلیکیشنتان را تعریف می‌کنید خودتان تعیین می‌کنید. شناسه‌ی محصول حداکثر 100 حرف می‌تواند داشته باشد و قابل تغییر نیست.

مثال:

mNivadBilling.purchase(this, "product_1000_coins");
mNivadBilling.subscribe(this, "monthly_subscription");

برای مصرف یک محصول مصرف شدنی از متد consumePurchase استفاده کنید. این متد به عنوان پارامتر ورودی شناسه‌ی محصول را دریافت می‌کند.

پارامتر سوم این متدها (Webhook Payload) اختیاری است و رشته‌ای است که در بدنهٔ وب‌هوک پرداخت به سرور شما پاس داده می‌شود. برای اطلاعات بیشتر دربارهٔٔ وب‌هوک‌های نیواد می‌توانید به صفحهٔ راهنمای webhookهای نیواد مراجعه کنید.

برای چک کردن اینکه کاربر یک محصول (یا اشتراک) را خریداری کرده باید از متدهای isPurchased و isSubscribed استفاده کنید.