تعاریف و مفاهیم اولیه وب سرویس پرداخت درون برنامه
درمقاله قبل در مورد مقدمه وب سرویس پرداخت درون برنامه صحبت کردیم در این مقاله در مورد تعاریف و مفاهیم API پرداخت درون برنامه صحبت میکنیم.
تعاریف و مفاهیم پایه
در این بخش مفاهیم پایه‌ای شرح داده می‌شوند که برای اضافه کردن پرداخت درون‌برنامه‌ای بایستی با آن‌ها آشنا باشید.
API پرداخت درون‌برنامه‌ای
API پرداخت درون‌برنامه‌ای اول مارکت، ارائه ی پرداخت درون‌برنامه‌ای در برنامه‌تان را ساده میکند. با استفاده از API پرداخت درون‌برنامه‌ای اول مارکت میتوانید جزئیات محصول را از اول مارکت بپرسید، سفارش خرید محصول درون‌برنامه‌ای را بدهید، و فهرست محصولاتی که کاربر صاحب آن‌ها است را از اول مارکت بپرسید. برنامهٔ اول مارکت درخواست‌ها و پاسخ‌های پرداخت، بین برنامهٔ شما و سِرور اول مارکت را مدیریت میکند. در عمل برنامهٔ شما هیچ‌گاه با سِروِراول مارکت به طور مستقیم در ارتباط نیست و هیچ ارتباط شبکه‌ای بین خودش و سِروِر اول مارکت را مدیریت نمی‌کند. در عوض برنامهٔ شما درخواست‌های پرداخت را (توسط ارتباطات بین پردازشی IPC) به برنامه اول مارکت می‌فرستد و پاسخ‌ها را از آن دریافت میکند. برنامهٔ اول مارکت برای تکمیل درخواست‌های پرداخت درون‌برنامه‌ای باید بتواند از طریق اینترنت به سِروِر اول مارکت دسترسی پیدا کند.
محصولات درون‌برنامه‌ای
محصولات درون‌برنامه‌ای، کالاها یا خدمات دیجیتالی هستند که از درون برنامهٔ خود برای فروش به کاربر عرضه می‌کنید. مثال‌هایی از کالاهای دیجیتال عبارتند از: سکهٔ درون بازی، به‌روزرسانی برخی از بخش‌های برنامه که باعث ایجاد تجربهٔ بهتری برای کاربر میشود، محتوای جدید برای برنامه. پرداخت درون‌برنامه‌ای فقط برای فروش محتوای دیجیتالی است. در حال حاضر نمی‌توانید از پرداخت درون‌برنامه‌ای برای فروش خدمات شخصی، محصولات فیزیکی یا هر چیزی که نیاز به تحویل فیزیکی داشته باشد، استفاده کنید. شما مسئول تحویل محتوای دیجیتالی هستید که در برنامهٔ خود به فروش می‌رسانید. اول مارکت هیچ مسئولیتی در قبال تحویل محتوا به کاربر برنامهٔ شما ندارد. محصولات درون‌برنامه‌ای همیشه تنها در یک برنامه قابل فروش هستند؛ یعنی، یک برنامه نمی‌تواند محصول درون‌برنامه‌ای برنامهٔ دیگری را بفروشد، حتی اگر آن محصول متعلق به توسعه‌دهنده‌ای واحد باشد.
انواع محصولات درون‌برنامه‌ای
اول مارکت از انواع مختلف محصولات درون‌برنامه‌ای پشتیبانی میکند تا شما دستِ بازی در طرح‌ریزی مالی برنامهٔ خود داشته باشید. تمام این محصولات را در پنل پرداخت اول مارکت(بخش محصولات/خدمات) تعریف می‌کنید. برای هر یک از محصولات میتوانید اطلاعاتی مانند شناسهٔ منحصر به فرد (SKU)، قیمت، عنوان و توضیح و … را تعریف کنید. محصولات درون‌برنامه‌ای در حالت کلی در دسته‌های «فروشی» و «اشتراک» قابل تعریف هستند.
محصولات فروشی
محصولات فروشی، محصولاتی هستند که هنگام خرید یک مرتبه پرداخت برای آن‌ها صورت می‌گیرد و به صورت مفهومی به دو دستهٔ محصولات «مصرفی» و «غیرمصرفی» تقسیم می‌شوند.شما میتوانید محصولات خود را به دو صورت مصرفی و غیرمصرفی به کاربر عرضه کنید.
محصولات مصرفی
محصولات مصرفی، کاربر می‌تواند چندین مرتبه این محصولات را خریداری کند (مانند سکهٔ داخل بازی، سوخت یا طلسم جادویی). لازم است پس از اتمام فرآیند خرید این نوع محصول توسط کاربر، خرید را اصطلاحاً مصرف کنید. در صورتی که پس از اتمام خرید این نوع محصول، خرید انجام شده را در برنامهٔ خود مصرف نکنید، اول مارکت اجازه نمی‌دهد کاربر مجدداً محصول مورد نظر را خریداری کند. برای یادگیری بیشتر دربارهٔ مصرف کردن خرید محصولات درون برنامه‌ای، مصرف کردن خرید را مشاهده کنید.
محصولات غیرمصرفی
محصولات غیر مصرفی، هستند که کاربر یک مرتبه آن‌ها را خریداری میکند اما تأثیر این خرید همیشگی است. مثل حذف تبلیغات از برنامه یا ارتقاء برنامه از نسخهٔ آزمایشی به نسخهٔ کامل است. این محصولات را نباید مصرف کنید تا برای همیشه دراول مارکت در حساب کاربر بمانند. بدین صورت اثر خرید این نوع محصولات دائمی خواهد بود و با حذف و نصب مجدد برنامهٔ شما از بین نخواهد رفت.
اشتراک (ماهانه|سالانه)
اشتراک محصولی است که به شما امکان می‌دهد محتوا، خدمات، یا ویژگی‌هایی را به کاربران برنامه‌تان با صورت‌حساب‌های دوره‌ای ماهانه یا سالانه بفروشید. میتوانید اشتراک‌ها را تقریباً برای تمام انواع محتوای دیجیتال در بازی یا برنامهٔ خود تعریف کنید و بفروشید. برای اطلاع از روش انجام کار، بخش راهنمای اشتراک‌ها را ببینید. شما میتوانید از جریان پرداخت مشابهی که برای محصولات درون‌برنامه‌ای فروشی استفاده میشود برای خرید اشتراک‌ها و بازیابی اطلاعات اشتراک استفاده کنید. مثالی از کد پیاده‌سازی اشتراک را در اینجا ببینید.
هشدار
برخلاف محصولات درون‌برنامه‌ای مصرفی، اشتراک‌ها قابل مصرف نیستند. برای کسب اطلاعات بیشتر در مورد انواع محصولات، شکل ۱ را ببینید.
مصرف کردن خرید
زمانی که کاربر محصول درون برنامه ای خرید میکند، بلافاصله پس از خرید باید مصرف شود در غیر این صورت اول مارکت مانع از خرید مجدد آن میشود. درخواست مصرف را فقط برای محصولات مصرفی برنامه‌تان بفرستید.
توجه
برای کسب اطلاعات بیشتر در مورد انواع محصولات، شکل ۱ را ببینید.
پنل پرداخت اول مارکت
پنل پرداخت اول مارکت محلی‌ست که از طریق آن میتوانید محصولات درون‌برنامه‌ای که برای فروش در نظر دارید را مدیریت کنید. برای کسب اطلاعات بیشتر مستندات مربوط به تعریف محصولات درون‌برنامه‌ای دراول مارکت را مشاهده کنید.
شناسهٔ محصول (SKU)
شناسهٔ یکتایی است که در زمان تعریف محصولات درون‌برنامه‌ای خود در پنل پرداخت، به آن‌ها اختصاص می‌دهید. شناسهٔ محصول در تشخیص یکتای یک محصول هنگام ایجاد درخواست و ارسال پاسخ‌های مربوط به پرداخت درون‌برنامه‌ای کاربرد دارد. این شناسه متفاوت از نام محصول است و کاربر برنامه هنگام فرآیند پرداخت آن را نخواهد دید. دقت داشته باشید که شناسه‌ها پس از تعریف قابل تغییر نیستند.
توکن خرید (purchaseToken)
رشته‌‌ای است که توسط اول مارکت برای شناسایی یکتای یک تراکنش پرداخت ساخته میشود.
اطلاعات اضافی توسعه‌دهنده (Developer Payload)
رشتهٔ دلخواهی است که حاوی اطلاعات تکمیلی مربوط به سفارش خرید است. به طور معمول این رشته به عنوان یک نشانه است که منحصراً این درخواست خرید را شناسایی میکند. توسعه‌دهنده هنگام ارسال درخواست خرید می‌تواند علاوه بر پارامترهای دیگر این رشته را نیز به اول مارکت بفرستد. در صورتی که این رشته مقداردهی شده باشد، اول مارکت به همراه پاسخ پرداخت این رشته را نیز برمی‌گرداند.
کلید عمومی پرداخت
زمانی که برای اولین بار پیشنویس برنامهٔ خود را در اول مارکت قرار می‌دهید، اول مارکت به صورت خودکار یک کلید گواهی عمومی (Public license key) برای آن تولید میکند. برای برقراری یک ارتباط امن بین برنامهٔ خود و سِروِرهای اول مارکت به این کلید نیاز دارید. این کلید برای هر برنامه یک مرتبه تولید میشود و زمانی که فایل APK برنامه را به‌روز می‌کنید این کلید تغییر نخواهد کرد.
خرید محصولات
در این بخش به ترتیب: روند خرید، روند مصرف کردن خرید، و مراحل مدیریت خریدهای محصولات مصرفی شرح داده می‌شوند.
روند خرید
- در اولین گام روند خرید، برنامهٔ شما بایستی به گونه‌ای بفهمد که آیا نسخهٔ API پرداخت درون‌برنامه‌ای که استفاده میکند توسط اول مارکت پشتیبانی میشود یا خیر. برای این منظور یک درخواست isBillingSupported به اول مارکت می‌فرستد.
- وقتی برنامهٔ شما شروع میشود یا کاربر وارد برنامه میشود (لاگین میکند)، فرصت مناسبی است که فهرست محصولاتی که کاربر صاحب آن‌ها است را از اول مارکت بپرسید. برای این منظور یک درخواست getPurchases بفرستید. در صورتی که درخواست موفقیت‌آمیز باشد، اول مارکت یک Bundle حاوی فهرستی از شناسهٔ محصولات خریداری شده، فهرستی از جزئیات یک خرید و فهرستی از امضاهای خریدها را به برنامهٔ شما برمی‌گرداند.
- معمولاً می‌خواهید کاربر را از محصولاتی که می‌تواند بخرد مطلع سازید. برنامهٔ شما می‌تواند یک درخواست getSkuDetails برای گرفتن جزئیات محصولات درون‌برنامه‌ای که در اول مارکت تعریف کرده‌اید بفرستد. برای این منظور بایستی فهرستی از شناسهٔ کالاهایی که می‌خواهید جزئیاتشان را بدانید را در درخواست خود مشخص کنید. در صورتی که درخواست موفقیت‌آمیز باشد، اول مارکت یک Bundle شامل جزئیات محصول (از قبیل قیمت، عنوان، توضیحات و نوع محصول) را برمی‌گرداند.
- در صورتی که کاربر صاحب یک محصول درون‌برنامه‌ای نباشد (یعنی قبلاً آن را خریداری نکرده یا در صورت خرید محصولی از نوع مصرفی، خرید مورد نظر در برنامه مصرف شده باشد)، می‌تواند آن را خریداری کند. برای این منظور برنامهٔ شما یک درخواست getBuyIntent که در آن شناسهٔ محصول و سایر پارمترها مشخص شده است را به اول مارکت می‌فرستد.
- اول مارکتBundle ای که حاوی یک PendingIntent است را برمی‌گرداند. برنامهٔ شما برای آغاز عملیات پرداخت از این Bundle استفاده میکند.
- برنامهٔ شما با فراخوانی متد startIntentSenderForResult، اینتنت ارسال شده از اول مارکت PendingIntent را اجرا میکند.
- وقتی روند پرداخت پایان یافت (یعنی زمانی که کاربر محصول را خرید یا از خرید آن صرف‌نظر کرد) اول مارکت پاسخ را در قالب یک Intent به متد onActivityResult برنامهٔ شما می‌فرستد. کد نتیجهٔ onActivityResult کدی است که بیانگر خرید موفق محصول یا لغو عملیات است. پاسخ Intent شامل اطلاعاتی دربارهٔ محصول خریداری شده، از جمله رشتهٔ purchaseToken است که توسط اول مارکت برای شناسایی یکتای این تراکنش خرید ساخته شده است. این Intent همچنین شامل امضای خرید است که توسط کلید خصوصی توسعه‌دهنده امضا شده است.
توجه
برای یادگیری بیشتر در مورد فراخوانی‌های API و پاسخ‌های سرور، بخش API Reference را مشاهده کنید.
روند مصرف کردن خرید
میتوانید از مکانیزم مصرف ارائه شده در API پرداخت درون برنامه‌ای اول مارکت برای پیگیری مالکیت کاربر بر محصولات درون‌برنامه‌ای استفاده کنید. پس از اتمام یک خرید موفق توسط کاربر، خرید مورد نظر در اول مارکت ذخیره میشود. زمانی که کاربرِ برنامهٔ شما یک محصول درون‌برنامه‌ای را خریداری میکند از دید اول مارکت «صاحب آن» خواهد بود. کاربر نمی‌تواند محصولاتی که هم‌اکنون صاحب آن‌ها می‌باشد را مجدداً خریداری کند. برای این که امکان خرید مجدد این محصول توسط کاربری که هم‌اکنون صاحب آن است فراهم شود، باید در برنامه‌تان یک درخواست مصرف برای آن محصول درون‌برنامه‌ای بدهید.
توجه
مصرف کردن محصول درون‌برنامه‌ای سبب میشود که اول مارکت دیگر کاربر را مالک آن محسوب نکند و اطلاعات خرید آن را دور بریزد.
هشدار
از بین انواع محصولات درون‌برنامه‌ای، فقط محصولات درون برنامه‌ای مصرفی را مصرف کنید. اشتراک و محصولات درون‌برنامه‌ای غیرمصرفی را نباید مصرف کنید.
برای واضح‌تر شدن این مفهوم دیدن اینفوگرافیک تهیه شده در شکل ۱ می‌تواند مفید باشد. برنامهٔ شما برای گرفتن فهرست محصولاتی که کاربر صاحب آن‌ها است، یک درخواست getPurchases به اول مارکت می‌فرستد. همچنین برنامهٔ شما می‌تواند برای مصرف محصولاتی که کاربر صاحب آن‌ها است، یک درخواست مصرف توسط فراخوانی consumePurchase به اول مارکت بفرستد. در آرگومان درخواست مصرف، بایستی توکن خرید (purchaseToken) آن (رشتهٔ یکتایی که هنگام خرید آن محصول از اول مارکت دریافت کرده‌اید) را مشخص کنید. در نهایت، اول مارکت کد وضعیتی که مشخص میکند آیا مصرف با موفقیت ذخیره شده است یا خیر را بازمی‌گرداند.
شما تصمیم می‌گیرید که محصولات درون‌برنامه‌ای خریداری شده را به چه شکلی در برنامه‌تان برای کاربر فراهم کنید (به این امر به اصطلاح «تأمین کردن محصول» می‌گوییم) و خود مسئول کنترل و پیگیری آن هستید. برای مثال، در صورتی که کاربر سکه‌‌ی داخل بازی را خریداری کرده، بایستی مقدار دارایی سکهٔ کاربر در بازی‌تان را به میزان سکه‌ای که خریداری کرده افزایش دهید.
هشدار
قبل از تأمین محصولات مصرفی در برنامه‌تان، شما باید درخواست مصرف را به اول مارکت فرستاده و پاسخی موفق از این‌که مصرف ذخیره شده است، دریافت کرده باشید.
مراحل مدیریت خریدهای محصولات مصرفی
در ادامه، روند پایه برای خرید یک محصول درون‌برنامه‌ای از نوع مصرفی را مرور میکنیم:
- روند خرید را با فراخوانی getBuyIntent آغاز کنید.
- پاسخ Bundle را از اول مارکت دریافت کنید. این پاسخ شامل اطلاعاتی مبنی بر موفقیت‌آمیز بودن یا نبودن فرآیند خرید است.
- اگر خرید موفقیت‌آمیز بود، خرید را با دستور consumePurchase مصرف کنید.
- کد پاسخی که مشخص میکند مصرف موفقیت‌آمیز بوده است یا خیر را ازاول مارکت دریافت کنید.
- اگر مصرف موفقیت‌آمیز بود، محصول را در برنامهٔ خود تأمین کنید (عملیاتی که قرار بود با خرید محصول اتفاق بیفتد را انجام دهید).
متعاقباً، هنگامی که کاربر برنامه را اجرا میکند یا به برنامه وارد میشود (لاگین میکند)، باید وضعیت دارایی‌های کاربر را بررسی نمایید، این‌که چه محصولات مصرفی و یا غیرمصرفی دارد و آن‌ها را چگونه باید تأمین کنید. روند پیشنهادی شروع برنامه برای زمانی که محصول مصرفی در برنامه‌تان دارید را در زیر مشاهده می‌کنید:
- برای دریافت محصولاتی که کاربر صاحب آن‌ها است، درخواست getPurchases را به اول مارکت ارسال کنید.
- اگر محصول قابل مصرفی وجود داشت، محصول را با دستور consumePurchase مصرف کنید. به این دلیل لازم است این کار را بکنید که ممکن است خرید محصول کامل شده باشد، اما قبل از ارسال درخواست مصرف آن، ارتباط قطع شده باشد.
- کد پاسخی که مشخص میکند مصرف محصول موفقیت آمیز بود یا خیر را از اول مارکت دریافت کنید.
- اگر مصرف موفقیت آمیز بود، محصول را در برنامهٔ خود تأمین کنید.
در این مقاله در مورد تعاریف و مفاهیم API پرداخت درون برنامه صحبت کردیم در مقاله بعد در مورد پنل مدیریت api پرداخت درون برنامه صحبت میکنیم.
برای دریافت مستندات کامل این وب سرویس از این لینک اقدام نمایید