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

محصول

شما با استفاده از پنل پرداخت بازار اطلاعات محصول خود را شامل شناسهٔ محصول (SKU)، توضیحات٬ قیمت و... معرفی می‌کنید. برای اطلاعات بیشتر مدیریت پرداخت درون برنامه‌ای را مشاهده کنید.

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

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

اشتراک‌ها

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

خرید محصولات

روند معمول خرید به صورت زیر است:

  1. برنامهٔ شما درخواست isBillingSupported را به برنامهٔ بازار می‌فرستد تا مطمئن شود نسخه‌ای از پرداخت درون‌برنامه‌ای که در برنامه پیاده شده است، توسط بازار پشتیبانی می‌شود یا خیر.
  2. وقتی‌ برنامه شما شروع می‌شود یا کاربر وارد برنامه می‌شود، فرصت مناسبی برای شناسایی محصولات متعلق به کاربر از طریق برنامهٔ بازار است. برای اطلاع از خریدهای درون برنامه‌ای کاربر، درخواست getPurchases را بفرستید. اگر درخواست موفقیت آمیز باشد، بازار یک Bundle شامل لیستی از شناسهٔ محصولات خریداری شده، یک لیست از جزئیات خرید هر فرد، و یک لیست از امضای محصولات خریداری شده به برنامهٔ شما باز می‌گرداند.

    iab_v3_purchase_flow

    شکل ۱. مراحل پایه‌ای برای درخواست خرید

  3. معمولاً شما می‌خواهید کاربر را از محصولات موجود برای خرید آگاه کنید. برای دریافت جزئیات محصولات درون‌برنامه‌ای که در بازار تعریف کرده‌اید، لازم است تا درخواست getSkuDetails را ارسال کنید. شما باید یک لیست از شناسهٔ محصولاتتان را در درخواستان مشخص کنید. اگر درخواست موفقیت آمیز بود، بازار یک Bundle شامل جزئیات محصولات مانند قیمت، اسم، و توضیحات برای شما می‌فرستد.
  4. اگر محصول درون‌برنامه‌ای متعلق به کاربر نباشد، شما می‌توانید فروش آن را آغاز کنید. برای شروع، برنامهٔ شما یک درخواست getBuyIntent می‌فرستد، که در آن شناسهٔ محصول برای فروش و سایر پارامتر‌ها مشخص است. شما باید شناسهٔ محصول را هنگام ساخت محصول جدید درون‌برنامه‌ای در پنل پرداخت بازار ثبت کرده باشید.
    1. بازار Bundleی شامل PendingIntent بازمی‌گرداند که برنامهٔ شما برای آغاز عملیات پرداخت از آن استفاده می‌کند.
    2. برنامهٔ شما با فراخوانی متد startIntentSenderForResult، PendingIntent‏ را اجرا می‌کند.
    3. وقتی‌ روند پرداخت پایان یافت (یعنی‌ زمانی‌ که کاربر محصول را خرید یا از آن صرف‌نظر کرد) بازار پاسخ را در قالب یک Intent به متد onActivityResult می‌فرستد. کد نتیجهٔ onActivityResult شامل پاسخ خرید موفق محصول یا لغو عملیات است. پاسخ Intent شامل اطلاعاتی درباره محصول خریداری شده، از جمله رشتهٔ purchaseToken است که توسط بازار برای شناسایی تراکنش خرید، به طور منحصر به فرد ساخته شده است. این Intent همچنین شامل امضای خرید است که توسط کلید خصوصی توسعه‌دهنده امضا شده ‏است.
  5. برای یادگیری بیشتر فراخوانی‌های API و پاسخ‏های سرور، API Reference را مشاهده کنید.

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

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

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

    برای بازیابی لیست محصولات متعلق به کاربر، برنامهٔ شما با فراخوانی getPurchases درخواستی را به بازار می‌فرستد. برنامهٔ شما می‌تواند درخواست مصرف را با فراخوانی consumePurchase بدهد. در آرگومان درخواست، شما باید code>purchaseToken مربوط به هر خرید را که هنگام خرید از بازار دریافت کرده‌اید، مشخص کنید. در نهایت بازار کد وضعیتی را که مشخص می‌‏کند آیا مصرف با موفقیت ذخیره شده ‏است یا خیر، بازمی‌گرداند.

    iab_v3_consumption_flow

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

    محصولات قابل مصرف و غیر قابل مصرف

    این تصمیم شماست که محصولات درون‌برنامه‌ای خود را به طور قابل مصرف یا غیر قابل مصرف به کاربر عرضه کنید.

    محصولات غیر قابل مصرف

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

    محصولات قابل مصرف

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

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

    مدیریت خریدهای قابل مصرف

    در ادامه، روند پایه برای خرید یک محصول قابل مصرف را مرور می‌کنیم:

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

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

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