En

فصل ۸: مرجع API

در این فصل اطلاعات کامل ورودی‌ها و خروجی‌های متدهای API خرید درون‌برنامه‌ای آورده شده.

کدهای بازگشتی از سرور

جدول زیر لیست تمام کدهایی است که مایکت به برنامه شما می‌فرستد. تمام کدهای پاسخ یک عدد هستند که مایکت در Bundleی که به عنوان پاسخ برمی‌گرداند در کلید RESPONSE_CODE آن را قرار می‌دهد. برنامه شما باید تمام این کدها را اداره کند. می‌توانید به برنامه مثال TrivialDrive نگاهی بیاندازید که این کار در آن شده است.

جدول ۱. خلاصه ای از کدهای پاسخ در *خرید درون‌برنامه‌ای*

کد بازگشتی مقدار توضیحات
BILLING_RESPONSE_RESULT_OK 0 با موفقیت انجام شد
BILLING_RESPONSE_RESULT_USER_CANCELED 1 کاربر عملیات را لغو کرد
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 خرید درون‌برنامه‌ای پشتیبانی نمی‌شود
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

API خرید درون‌برنامه‌ای در فایل IInAppBillingService.aidl تعریف شده است، که در برنامه نمونه TrivialDrive وجود دارد.

متد getSkuDetails():

این متد جزئیات یک لیست از محصولات را با گرفتن شناسه آنها برمی‌گرداند. درBundle دریافتی از مایکت، نتایج کوئری در یک ArrayList که کلید آن DETAILS_LIST است ذخیره می‌شوند. هر رشته در این لیست حاوی اطلاعات محصول در قالب JSON است. فیلدهای رشته JSON در جدول زیر توضیح داده شده‌اند.

جدول ۲. شرح فیلدهای JSON بازگشتی با فراخوانی متد getSkuDetails

کلید توضیحات
productId شناسه محصول که SKU نیز نام دارد
type مقدار «inapp» برای محصولات مصرف شدنی و نشدنی، و مقدار «subs» برای اشتراک. از آنجایی که در حال حاضر اشتراک پیشتیبانی نمی‌شود تنها مقدار درست این فیلد «inapp» می‌باشد.
price قیمت محصول به ریال
title عنوان محصول
description توضیحات درباره محصول

متد getBuyIntent():

این متد یک عدد با کلید RESPONSE_CODE و یک PendingIntent برای آغاز خرید محصول با کلید BUY_INTENT را در یک Bundle برمی‌گرداند. مایکت بعد از دریافت PendingIntent واسط کاربری خرید را به کاربر نشان می‌دهد، و نتیجه‌ی کار را به متد onActivityResult در Activity صدا زننده برمی‌گرداند. در Intentی که به onActivityResult داده می‌شود داده‌های خرید وجود دارند. جزئیات این داده‌ها در جدول ۳ ذکر شده‌اند.

جدول 3.*داده‌های بازگشتی بعد از یک درخواست خرید*

کلید توضیحات
RESPONSE_CODE اگر 0 باشد خرید موفقیت‌آمیز بوده، در غیر اینصورت خطایی رخ داده.
INAPP_PURCHASE_DATA یک رشته از نوع JSON که حاوی جزئیات سفارش خرید می‌باشد. برای توضیحات فیلدهای این JSON به جدول ۴ مراجعه کنید.
INAPP_DATA_SIGNATURE رشته‌ای که حاوی امضای دیجیتال رشته بالایی است، که با کلید خصوصی توسعه دهنده امضا شده است. امضای دیجیتال داده‌ها از RSASSA-PKCS1-v1_5 استفاده می‌کند.

جدول ۴ فیلدهای JSON حاوی جزئیات یک سفارش را توصیف می‌کند.

جدول 4. شرح فیلدهای JSON برای INAPP_PURCHASE_DATA

فیلد توضیحات
orderId شناسه منحصر بفرد تراکنش
packageName نام بسته برنامه‌ای که خرید از آن انجام شده
productId شناسه محصول؛ هر محصول شناسه‌ای دارد که شما باید آن را در پنل توسعه‌دهندگان مشخص کنید.
purchaseTime این فیلد زمان خرید را بر حسب میلی ثانیه نمایش می‌دهد. (از تاریخ 1 ژانویه 1970)
purchaseState وضعیت خرید سفارش (در حال حاضر فقط یک مقدار دارد): 0: خریده شده
developerPayload رشته‌ای که توسعه‌دهنده ساخته و حاوی اطلاعات کاملی درباره خرید است. شما می‌توانید این فیلد را هنگامی که یک درخواست getBuyIntent می‌کنید ارسال نمایید.
purchaseToken یک شناسه که برای هر جفت محصول و کاربر داده شده، یک خرید را مشخص می‌کند.

متد getPurchases():این متد محصولاتی که در حال حاضر کاربر خریداری کرده ولی هنوز مصرف نکرده را برمی‌گرداند. جدول 5 مقادیری که در Bundle بازگشتی وجود دارند را نشان می‌دهد.

جدول 5:پاسخ‌های دریافتی از یک درخواست getPurchases

کلید توضیحات
RESPONSE_CODE 0 اگر درخواست موفقیت‌آمیز باشد، در غیر اینصورت خطایی رخ داده
INAPP_PURCHASE_ITEM_LIST ArrayList حاوی لیستی از شناسه محصولات
INAPP_PURCHASE_DATA_LIST ArrayList حاوی جزئیات خریدها. جدول ۴ را برای لیستی از جزئیات ذخیره شده در هر INAPP_PURCHASE_DATA این لیست ببینید.
INAPP_DATA_SIGNATURE_LIST ArrayList حاوی امضای دیجیتال خریدها
INAPP_CONTINUATION_TOKEN رشته‌ای حاوی یک شناسه برای بازیابی مجموعه محصولات بعدی که این کاربر مالک آنهاست. این رشته زمانی از سمت مایکت مقدار می‌گیرد که تعداد خریدهای این کاربر خیلی زیاد باشد (مثلا بیشتر از ۷۰۰). وقتی که این شناسه در پاسخ باشد، شما باید یک بار دیگر getPurchases را فراخوانی کنید و این شناسه را به آن بدهید. این فراخوانی به شما ادامه لیست خرید را برمی‌گرداند و همینطور احتمالا یک شناسه دیگر. برای مشاهده لیست تمام خریدها باید این کار تا زمانی ادامه دهید که در پاسخ مایکت برای این کلید مقداری نباشد.

کلیه حقوق متعلق به مایکت می باشد.