این سند رفرنس تکنیکال برای استفاده از API نسخهٔ ۳ پرداخت درون برنامه‌ای ارائه می‌کند.
جدول زیر لیست کاملی از پاسخ‌هایی که سرور بازار به برنامهٔ شما باز می‌گرداند را ارائه می‌کند. بازار پاسخ را به صورت همزمان به صورت مقدار عددی که منطبق بر کلید RESPONSE_CODE در Bundle بازگشتی‌است، می‌فرستد. برنامهٔ شما باید تمام این مقادیر بازگشتی از سرور بازار را مدیریت کند.
جدول ۱. کدهای بازگشتی در API نسخهٔ ۳ پرداخت:
| کد بازگشتی | مقدار | توضیحات |
|---|---|---|
BILLING_RESPONSE_RESULT_OK | 0 | موفقیت در انجام عمل |
BILLING_RESPONSE_RESULT_USER_CANCELED | 1 | کاربر عملیات را متوقف کرده است |
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE | 3 | API برای درخواست ارسال شده پشتیبانی نمی‌شود |
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE | 4 | این محصول برای فروش موجود نیست |
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR | 5 | پارامترهای ارسالی به API معتبر نیستند. این خطا زمانی رخ می‌دهد که تغییرات مورد نیاز در مانیفست ایجاد نشده باشد، برنامه در پنل پرداخت بازار ثبت نشده باشد یا مجوزهای لازم برای استفاده از پرداخت را کسب نکرده باشد. |
BILLING_RESPONSE_RESULT_ERROR | 6 | خطا در هنگام عملیات پرداخت |
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED | 7 | خطا در خرید به دلیل اینکه این محصول در حال حاضر در «مالکیت» کاربر است |
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED | 8 | خطا در مصرف، زیرا این محصول مربوط به این کاربر نیست |
API نسخهٔ ۳ پرداخت درون برنامه‌ای از فایل IInAppBillingService.aidl استفاده می‌کند. برای اطلاعات بیشتر در این باره به برنامهٔ نمونه مراجعه کنید.
این متد مشخصات محصولات را به ازای هر شناسهٔ محصول برمی‌گرداند.
در Bundle بازگشتی از بازار، در یک ArrayListمنطبق شده بر DETAILS_LIST قرار گرفته‌اند. هر رشته در این آرایه حاوی اطلاعات محصول در فرمت JSON است. فیلدهای موجود در این رشتهٔ بازگشتی برای هر محصول در جدول زیر توضیح داده شده‌اند.
جدول ۲. توضیحات فیلدهای موجود در رشتهٔ JSON بازگشتی با فراخوانی متد getSkuDetails.
| کلید | توضیحات |
|---|---|
productId | شناسهٔ محصول |
type | برای خریدهای درون برنامه‌ای این مقدار باید “inapp” باشد. |
price | قیمت فرمت شده همراه با علامت ریال. توجه کنید که این قیمت همان قیمتی است که در پنل پرداخت وارید کرده‌اید. |
title | عنوان محصول |
description | توضیحاتی در مورد این محصول |
این متد یک مقدار عددی منطبق بر کلید RESPONSE_CODE و یک PendingIntent برای راه اندازی جریان خرید برای محصول مورد نظر منطبق بر کلید BUY_INTENT باز می‌گرداند. پاسخی که در Intent بازگشتی توسط بازار برگردانده می‌شود حاوی داده‌هایی است که در جدول ۳ به صورت خلاصه توضیح داده شده است.
جدول ۳. داده‌های بازگشتی بعد از درخواست خرید در APi نسخهٔ ۳
| کلید | توضیحات |
|---|---|
RESPONSE_CODE | مقدار 0 اگر خرید با موفقیت انجام شده باشد. در غیر این صورت خطا |
INAPP_PURCHASE_DATA | یک رشته حاوی اطلاعات خرید به صورت JSON که توضیحات آن در جدول ۴ آمده است. برای توضیحات بیشتر به جدول شماره ۴ مراجعه کنید. |
INAPP_DATA_SIGNATURE | یک رشته حاوی اطلاعات خرید که توسط کلید خصوصی توسعه‌دهنده امضا شده است. |
جدول ۴ فیلدهای بازگشتی از یک اطلاعات خرید در قالب JSON را به اختصار توضیح می‌دهد.
جدول ۴. توضیحات فیلدهای JSON در INAPP_PURCHASE_DATA.
| فیلد | توضیحات |
|---|---|
orderId | یک شناسهٔ منحصر به فرد برای هر سفارش |
packageName | نام بسته‌ای که توسط آن درخواست خرید صادر شده است. |
productId | شناسهٔ محصول. این همان شناسه‌ای است که در پنل مدیریت خرید بازار وارد کرده‌اید. |
purchaseTime | زمانی که خرید انجام شده است بر حسب میلی ثانیه ( از epoch (Jan 1, 1970)) |
purchaseState | وضعیت این سفارش 0 (خریداری شده)، 1 (لغو شده) یا 2 (برگشت خورده). |
developerPayload | رشتهٔ ساخته شده توسط توسعه دهنده که حاوی اطلاعات لازم برای خرید این محصول است. شما می‌توانید این رشته را زمانی که درخواست getBuyIntent می‌دهید، ارسال کنید. |
purchaseToken | یک توکن که به صورت منحصر به فرد خرید یک محصول توسط یک کاربر را مشخص می‌کند. |
این متد خریدهایی را که هنوز توسط کاربر مصرف نشده‌اند را نشان می‌دهد. جدول ۵ لیست مقادیر بازگشتی این متد را در Bundle بازگشتی نمایش می‌دهد.
جدول ۵. پاسخ بازگشتی از فراخوانی متد getPurchases.
| کلید | توضیحات |
|---|---|
RESPONSE_CODE | مقدار 0 اگر عملیات با موفقیت انجام شده باشد. در غیر این صورت خطا. |
INAPP_PURCHASE_ITEM_LIST | StringArrayList شامل لیستی از محصولات درون برنامه‌ای برای این برنامه/td> |
INAPP_PURCHASE_DATA_LIST | StringArrayList حامل جزئیات خریدهای درون این برنامه. برای باخبر شدن از جزئیات هر مورد ذخیره شده درون INAPP_PURCHASE_DATA، به جدول ۴ مراجعه کنید. |
INAPP_DATA_SIGNATURE_LIST | StringArrayList حاوی امضای خریدهای درون برنامه‌ای برای این برنامه. |
INAPP_CONTINUATION_TOKEN | یک رشته شامل توکنی برای پیگیری دستهٔ بعدی خریدهای این کاربر درون این برنامه. این فیلد در صورتی مقدار دهی می‌شود که تعداد خریدهای کاربر درون این برنامه زیاد باشد. وقتی که این توکن موجود باشد، برای دریافت بقیهٔ لیست خریدهای کاربر باید یک درخواست دیگر از طریق getPurchases بدهید و این توکن را هم همراه آن بفرستید. پاسخ بازگشتی شامل ادامهٔ لیست خریدهای کاربر خواهد بود و در صورت موجود بودن این توکن باید این روند را تا زمانی که لازم است ادامه دهید تا لیست همهٔ خریدهای کاربر را دریافت کنید. |