En

فصل ۶: نمای کلی API

API خرید درون‌برنامه‌ای طوری طراحی شده تا به راحتی آن را به برنامه خود اضافه کنید.

محصولات

شما با استفاده از پنل توسعه‌دهندگان موجود در مایکت می‌توانید اطلاعات و جزئیات محصول دیجیتالی خود از جمله شماره شناسه محصول (SKU)، قیمت، توضیحات و غیره را تعریف نمایید. برای آشنایی با نحوه انجام این کار به فصل ۳ مراجعه نمایید. زمانی که یک کاربر محصولی را می‌خرد، مایکت تمام اطلاعات خرید را ذخیره می‌کند. این شما را قادر می‌سازد تا هر زمان که خواستید در آینده به مایکت کوئری بزنید تا اطلاعات خریدهای یک کاربر مشخص را بازیابی کنید. این اطلاعات در سرور مایکت برای همیشه باقی خواهد ماند حتی اگر کاربر برنامه را از دستگاه خود حذف کند یا حتی اقدام به تعویض دستگاهش نماید.

محصولات مصرف شدنی و نشدنی:

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

  2. محصولات مصرف نشدنی: این نوع محصولات قابل مصرف نیستند یعنی کابر فقط یک بار آنها را می‌خرد و برنامه شما برای همیشه مزایای آن را برای کاربر فراهم می‌کند. مانند حساب کاربری ویژه یا فعال کردن امکانی خاص در یک برنامه که به صورت پیش فرض غیر فعال است. برنامه شما بعد از اینکه کاربر این نوع محصول را خرید باید سرویس مربوط به آن را به کاربر بدهد، و نیازی به مصرف کردن محصول نیست.

خرید محصولات

تصویر ۲.مراحل اساسی برای یک درخواست خرید

روند یک خرید معمولاً به این صورت خواهد بود:

  1. برنامه شما یک درخواست isBillingSupported به مایکت میفرستد تا مشخص شود که مایکت از خرید درون‌برنامه‌ای که در برنامه شما وجود دارد پشتیبانی می‌کند یا خیر.
  2. زمانی که برنامه شما شروع به کار می‌کند و یا کاربر login می‌کند، زمان مناسبی‌ست تا لیست محصولاتی که کاربر خریده است را به دست آوریم. برای اینکار یک درخواست getPurchases بفرستید. اگر درخواست موفقیت آمیز باشد، مایکت یک Bundle برمی‌گرداند شامل یک لیست از شناسه محصولاتی که خریده شده، یک لیست از جزئیات هر خرید، و یک لیست از امضای دیجیتال هر محصول.
  3. غالبا شما نیاز دارید که محصولات دیجیتالی خود را به کاربران خود معرفی کنید. برای اینکه مشخصات محصولاتی که در مایکت تعریف کرده‌اید را به دست آورید، یک درخواست getSkuDetails ارسال کنید. کوئری که می‌زنید یک لیست حاوی شناسه محصولات از شما می‌خواهد. اگر درخواست موفقیت‌آمیز باشد، مایکت یک Bundle حاوی جزئیات محصولات شامل قیمت، عنوان، توضیحات را به برنامه شما برمی‌گرداند.
  4. اگر محصولی باشد که کاربر نخریده باشد، شما می‌توانید آن را به وی بفروشید. برای شروع روند خرید برنامه شما یک درخواست getBuyIntent ارسال می‌کند که در پارامترهای آن شناسه محصول مورد نظر مشخص شده.
  5. برنامه مایکت یک Bundle حاوی یک PendingIntent برمی‌گرداند که برنامه شما از آن برای باز کردن رابط گرافیکی مربوط به خرید استفاده می‌کند.
  6. برنامه شما PendingIntent را با فراخوانی متد startIntentSenderForResult راه‌اندازی می‌کند.
  7. هنگامی که مراحل پرداخت به اتمام رسید (یعنی کاربر محصول را با موفقیت خرید یا روند خرید را لغو کرد)، مایکت در پاسخ یک Intent به متد onActivityResult می‌فرستد. مقدار resultCode در ورودی onActivityResult نشان می‌دهد که خرید موفقیت آمیز بوده یا لغو شده است. Intentی که در پاسخ می‌آید حاوی اطلاعات محصول خریده شده است، شامل یک رشته purchaseToken که توسط مایکت برای این تراکنش خرید به صورت منحصر به فرد تولید شده، و امضای دیجیتالی خرید، که با کلید خصوصی شما امضا شده.

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

مصرف کردن محصولات

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

تصویر ۳.مراحل اساسی برای یک درخواست مصرف

برای بازیابی لیست محصولات متعلق به کاربر، برنامه شما یک درخواست getPurchases به مایکت می‌فرستد. برنامه شما می‌تواند با صدا زدن consumePurchase یک درخواست مصرف ارسال نماید. در آرگومان درخواست شما باید purchaseToken مربوط به خرید را که هنگام خرید از مایکت دریافت کرده‌اید بدهید. مایکت در پاسخ یک کد برمی‌گرداند که نشان می‌دهد مصرف با موفقیت ثبت شد یا خیر.

شما باید مشخص کنید که محصولی مصرف شدنی است یا مصرف نشدنی. فراهم کردن مزایای محصولات به عهده شماست و باید مطمئن شوید که اگر کاربر محصولی را خرید حتما اثر آن در برنامه اعمال شود.

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

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

مدیریت خرید محصولات مصرف شدنی

مراحل اصلی خرید یک محصول مصرف شدنی در زیر آمده است:

  1. روند خرید را با فراخوانی getBuyIntent آغاز کنید.
  2. یک Bundle پاسخ از مایکت بگیرید که نشان می‌دهد آیا عملیات خرید با موفقیت انجام شده یا خیر.
  3. در صورتی موفقیت‌آمیز بودن خرید، با صدا زدن consumePurchase آن را مصرف کنید.
  4. یک کد پاسخ از مایکت بگیرید که نشان می‌دهد مصرف محصول با موفقیت ثبت شد یا خیر.
  5. اگر مصرف موفقیت‌آمیز بود، اثر مربوط به آن را در برنامه ارائه دهید.

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

  1. ارسال یک درخواست getPurchases برای کوئری زدن محصولاتی که کاربر مالک آنهاست (یعنی خریداری شده‌اند اما مصرف نشده‌اند).
  2. اگر هر محصول مصرف شدنی وجود دارد، آنها را با صدا زدن consumePurchase مصرف کنید. این مرحله لازم است چرا که ممکن است عملیات خرید را کامل انجام داده باشد، اما قبل از اینکه فرصت فرستادن درخواست مصرف داشته باشد ارتباطش قطع شده یا به هر دلیلی متوقف شده.
  3. یک پاسخ از مایکت دریافت کنید که نشان می‌دهد مصرف محصول ثبت شده سات یا خیر.
  4. اگر مصرف موفقیت‌آمیز بود، اثر محصول را در برنامه خود اعمال کنید.

مراجعه به فصل 7

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