راهنمای یکپارچه‌سازی درون‌برنامه برای صورت‌حساب جایگزین با انتخاب کاربر

این راهنما نحوه ادغام کردن میاناهای برنامه‌سازی کاربردی را برای ارائه صورت‌حساب جایگزین با انتخاب کاربر در برنامه‌تان شرح می‌دهد.

راه‌اندازی «کتابخانه خدمات صورت‌حساب Play»

وابستگی «کتابخانه خدمات صورت‌حساب Play» را به برنامه Android خود اضافه کنید. برای استفاده از میاناهای برنامه‌سازی کاربردی صورت‌حساب جایگزین باید از نسخه ۵.۲ یا بالاتر استفاده کنید. اگر نیاز دارید از نسخه قدیمی‌تر انتقال دهید، قبل‌از اینکه بخواهید صورت‌حساب جایگزین را پیاده‌سازی کنید، دستورالعمل‌های راهنمای انتقال را دنبال کنید.

اتصال به Google Play

اولین مراحل در فرایند یکپارچه‌سازی همان مراحلی است که در راهنمای یکپارچه‌سازی «خدمات صورت‌حساب Google Play» توضیح داده شده است، با چند تغییر در هنگام راه‌اندازی BillingClient:

• باید روش جدیدی را فراخوانی کنید تا نشان دهید می‌خواهید به کاربر انتخاب گزینه‌های صورت‌حساب را پیشنهاد دهید: enableUserChoiceBilling.
• باید UserChoiceBillingListener را برای رسیدگی به مواردی که کاربر صورت‌حساب جایگزین را انتخاب می‌کند ثبت کنید.

مثال زیر مقداردهی اولیه BillingClient را با این اصلاحات نشان می‌دهد:

val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // Handle new Google Play purchase.
    }

val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Handle alternative billing choice.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build()
AlternativeBillingWithUserChoiceInApp.kt

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

پس‌از مقداردهی اولیه BillingClient، باید همان‌طور که در راهنمای یکپارچه‌سازی توضیح داده شده است، اتصالی به Google Play برقرار کنید.

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

می‌توانید محصولات دردسترس را به کاربر نمایش دهید، همان‌طور که در ادغام سیستم صورت‌حساب Google Play انجام می‌دهید. وقتی کاربرتان محصولات موجود برای خرید را دید و یکی را برای خرید انتخاب کرد، جریان صدور صورت‌حساب به‌انتخاب کاربر را همان‌طور که در بخش زیر توضیح داده شده است راه‌اندازی کنید.

راه‌اندازی جریان صدور صورت‌حساب به‌انتخاب کاربر

جریان صورت‌حساب به‌انتخاب کاربر را با فراخوانی launchBillingFlow() راه‌اندازی کنید. این کار مشابه راه‌اندازی جریان خرید با سیستم صورت‌حساب Google Play ادغام است: نمونه ProductDetails و offerToken متناظر با محصول و پیشنهاد ویژه‌ای که کاربر می‌خواهد دریافت کند ارائه می‌دهید. اگر کاربر سیستم صورت‌حساب Google Play را انتخاب کند، از این اطلاعات برای ادامه روند خرید استفاده می‌شود.

وقتی توسعه‌دهندگان با launchBillingFlow() تماس می‌گیرند، سیستم صورت‌حساب Google Play بررسی‌های زیر را انجام می‌دهد:

• سیستم بررسی می‌کند که آیا کشور Google Play کاربر جزو کشورهای پشتیبانی‌کننده صورت‌حساب جایگزین با انتخاب کاربر (یعنی کشور پشتیبانی‌شده) است یا خیر. اگر کشور کاربر در Google Play پشتیبانی شود، Google Play براساس پیکربندی BillingClient بررسی می‌کند که آیا صورت‌حساب جایگزین فعال شده است یا نه.
  • اگر صورت‌حساب جایگزین به‌انتخاب کاربر فعال شده باشد، جریان خرید تجربه کاربری انتخاب کاربر را نشان می‌دهد.
  • اگر صورت‌حساب جایگزین به‌انتخاب کاربر فعال نباشد، جریان خرید تجربه کاربری استاندارد سیستم صورت‌حساب Google Play را بدون انتخاب کاربر نشان می‌دهد.
• اگر کشور کاربر در Google Play جزو کشورهای پشتیبانی‌شده نباشد، جریان خرید تجربه کاربری استاندارد سیستم صورت‌حساب Google Play را بدون انتخاب کاربر نشان می‌دهد.

مدیریت انتخاب کاربر

نحوه مدیریت بقیه جریان خرید بسته به اینکه کاربر سیستم صورت‌حساب Google Play یا سیستم صورت‌حساب جایگزین را انتخاب کرده باشد متفاوت است.

وقتی کاربر سیستم صورت‌حساب جایگزین را انتخاب می‌کند

اگر کاربر سیستم صورت‌حساب جایگزین را انتخاب کند، Google Play با UserChoiceBillingListener تماس می‌گیرد تا به برنامه اطلاع دهد که باید جریان خرید را در سیستم صورت‌حساب جایگزین راه‌اندازی کند. به‌طور خاص، روش userSelectedAlternativeBilling() فراخوانده می‌شود.

کد تراکنش برون‌سازمانی ارائه‌شده در شیء UserChoiceDetails نشان‌دهنده امضای انتخاب کاربر برای ورود به جریان صورت‌حساب جایگزین است. از این نشان برای گزارش هر تراکنشی که از این انتخاب ناشی می‌شود، همان‌طور که در راهنمای یکپارچه‌سازی زیرینه توضیح داده شده است، استفاده کنید.

‫UserChoiceBillingListener باید کنش‌های زیر را انجام دهد:

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

اگر کاربر خرید را بااستفاده از سیستم صورت‌حساب جایگزین تکمیل کند، باید تراکنش را با فراخوانی «میانای برنامه‌سازی کاربردی توسعه‌دهندگان Google Play» از زیرینه خود ظرف ۲۴ ساعت به Google Play گزارش دهید و externalTransactionToken و جزئیات تراکنش اضافی را ارائه دهید. برای جزئیات بیشتر، راهنمای یکپارچه‌سازی زیرینه را ببینید.

مثال زیر نحوه پیاده‌سازی UserChoiceBillingListener را نشان می‌دهد:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        DevBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }
AlternativeBillingWithUserChoiceInApp.kt

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

وقتی کاربر سیستم صورت‌حساب Google Play را انتخاب می‌کند

اگر کاربر سیستم صورت‌حساب Google Play را انتخاب کند، خرید ازطریق Google Play را ادامه می‌دهد.

• برای اطلاعات بیشتر درباره نحوه مدیریت خریدهای درون‌برنامه جدید ازطریق سیستم صورت‌حساب Google Play، بخش پردازش خریدها در راهنمای یکپارچه‌سازی کتابخانه را ببینید.
• برای راهنمایی بیشتر درباره خریدهای اشتراک، اشتراک‌های جدید را در راهنمای مدیریت اشتراک ببینید.

مدیریت تغییرات در اشتراک

برای توسعه‌دهندگانی که از سیستم صورت‌حساب جایگزین با انتخاب کاربر استفاده می‌کنند، خریدها باید یا ازطریق سیستم صورت‌حساب Google Play پردازش شوند یا با externalTransactionId گزارش شوند، که این امر به انتخاب کاربر بستگی دارد. تغییرات در اشتراک‌های موجود که ازطریق جریان انتخاب کاربر پردازش شده‌اند، تا زمان انقضا می‌توانند ازطریق همان سیستم صورت‌حساب انجام شوند.

این بخش نحوه مدیریت برخی‌از سناریوهای رایج تغییر اشتراک را توضیح می‌دهد.

جریان‌های ارتقا و تنزل

تغییرات طرح اشتراک ازجمله جریان‌های ارتقا و تنزل باید بسته به اینکه اشتراک در ابتدا ازطریق سیستم صورت‌حساب Google Play یا ازطریق سیستم صورت‌حساب جایگزین خریداری شده است، به‌صورت متفاوتی مدیریت شوند.

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

اشتراک‌های خریداری‌شده ازطریق سیستم صورت‌حساب جایگزین

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

برای انجام این کار، وقتی کاربر درخواست ارتقا یا تنزل می‌دهد، با launchBillingFlow() تماس بگیرید. به‌جای مشخص کردن شیء SubscriptionUpdateParams در پارامترها، از setOriginalExternalTransactionId استفاده کنید و شناسه تراکنش خارجی برای خرید اصلی را ارائه دهید. این کار صفحه انتخاب کاربر را نمایش نمی‌دهد، زیرا انتخاب کاربر برای خرید اصلی برای ارتقا و تنزل حفظ می‌شود. تماس با launchBillingFlow() در این مورد یک رمز تراکنش خارجی جدید برای تراکنشی که می‌توانید از پاسخ‌به‌تماس بازیابی کنید ایجاد می‌کند.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = "your_external_transaction_id"

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.
AlternativeBillingWithUserChoiceInApp.kt

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync.
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build()
            )
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

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

اشتراک‌های خریداری‌شده ازطریق سیستم صورت‌حساب Google Play

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

1. ‫offerToken پیشنهاد ویژه انتخابی را برای طرح جدید مشخص کنید:

   کاتلین

   val offerTokenNewPlan = productDetailsNewPlan.getSubscriptionOfferDetails()
       ?.getOrNull(selectedOfferIndex)
       ?.offerToken
       ?: ""
   AlternativeBillingWithUserChoiceInApp.kt

   جاوا

   String offerTokenNewPlan = productDetailsNewPlan
           .getSubscriptionOfferDetails(selectedOfferIndex)
           .getOfferToken();
   

2. اطلاعات صحیح را به سیستم صورت‌حساب Google Play ارسال کنید تا خرید جدید را پردازش کند، ازجمله کد خرید برای اشتراک موجود:

   کاتلین

   val billingFlowParams =
       BillingFlowParams.newBuilder()
           .setProductDetailsParamsList(
               listOf(
                   BillingFlowParams.ProductDetailsParams.newBuilder()
                       // Fetched using queryProductDetailsAsync
                       .setProductDetails(productDetailsNewPlan)
                       .setSubscriptionProductReplacementParams(
                           SubscriptionProductReplacementParams.newBuilder()
                               .setReplacementMode(
                                   SubscriptionProductReplacementParams.ReplacementMode.CHARGE_FULL_PRICE
                               )
                               .setOldProductId("old_product_id")
                               .build()
                       )
                       // offerIdToken can be found in
                       // ProductDetails=>SubscriptionOfferDetails.
                       .setOfferToken(offerTokenNewPlan)
                       .build()
               )
           )
           .setSubscriptionUpdateParams(
               BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                   // purchaseToken can be found in
                   // Purchase#getPurchaseToken
                   .setOldPurchaseToken(oldToken)
                   .build()
           )
           .build()
   
   val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
   AlternativeBillingWithUserChoiceInApp.kt

   جاوا

   BillingFlowParams billingFlowParams =
       BillingFlowParams.newBuilder()
           .setProductDetailsParamsList(
               ImmutableList.of(
                   ProductDetailsParams.newBuilder()
                       // Fetched using queryProductDetailsAsync
                       .setProductDetails(productDetailsNewPlan)
                       // offerIdToken can be found in
                       // ProductDetails=>SubscriptionOfferDetails.
                       .setOfferToken(offerTokenNewPlan)
                       .build()
               )
           )
           .setSubscriptionUpdateParams(
               SubscriptionUpdateParams.newBuilder()
                   // purchaseToken can be found in
                   // Purchase#getPurchaseToken
                   .setOldPurchaseToken(oldToken)
                   .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                   .build()
           )
           .build();
   
   BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
   

این خرید در سیستم صورت‌حساب Google Play انجام می‌شود و برنامه شما تماس PurchasesUpdatedListener.onPurchaseUpdated را با نتیجه خرید دریافت می‌کند. اگر خرید موفقیت‌آمیز باشد، روش onPurchaseUpdated() نیز اطلاعات خرید جدید را دریافت می‌کند و زیرینه شما SUBSCRIPTION_PURCHASED «اعلان بی‌درنگ توسعه‌دهنده» دریافت می‌کند. هنگام دریافت وضعیت خرید جدید، یک ویژگی linkedPurchaseToken به خرید اشتراک قدیمی پیوند می‌دهد تا بتوانید آن را طبق توصیه غیرفعال کنید.

لغو و بازگرداندن اشتراک

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

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

اشتراک‌های خریداری‌شده ازطریق سیستم صورت‌حساب جایگزین

اگر شناسه تراکنش خارجی برای اشتراک لغوشده دارید، برای بازیابی اشتراک نیازی به تماس با launchBillingFlow() نیست، بنابراین نباید برای این نوع فعال‌سازی استفاده شود. اگر کاربری اشتراک خود را درحالی‌که هنوز در دوره فعال اشتراک لغوشده است بازیابی کند، در آن زمان هیچ تراکنشی انجام نمی‌شود؛ شما می‌توانید زمانی که چرخه فعلی منقضی می‌شود و تمدید بعدی انجام می‌شود، تمدیدها را گزارش کنید. این شامل مواردی می‌شود که کاربر به‌عنوان بخشی از بازگرداندن اشتراک، اعتبار یا قیمت ویژه تمدید دریافت می‌کند (برای مثال، تبلیغی برای تشویق کاربر به ادامه اشتراک).

اشتراک‌های خریداری‌شده ازطریق سیستم صورت‌حساب Google Play

به‌طورکلی، کاربران می‌توانند اشتراک‌ها را در سیستم صورت‌حساب Google Play بازیابی کنند. برای اشتراک‌های لغوشده که دراصل در سیستم صورت‌حساب Google Play خریداری شده‌اند، کاربر می‌تواند درحالی‌که اشتراک ازطریق ویژگی اشتراک مجدد Google Play فعال است، لغو را واگرد کند. در این حالت، شما یک SUBSCRIPTION_RESTARTED اعلان بی‌درنگ توسعه‌دهنده در زیرینه خود دریافت می‌کنید و یک کد خرید جدید صادر نمی‌شود—از کد اصلی برای ادامه اشتراک استفاده می‌شود. برای آشنایی با نحوه مدیریت بازیابی در سیستم صورت‌حساب Google Play، بخش بازیابی‌ها را در راهنمای مدیریت اشتراک ببینید.

همچنین می‌توانید با فراخوانی launchBillingFlow()، بازگرداندن را در سیستم صورت‌حساب Google Play از برنامه راه‌اندازی کنید. برای توضیح نحوه انجام این کار، به قبل‌از انقضای اشتراک - درون‌برنامه مراجعه کنید. در مورد کاربرانی که جریان انتخاب کاربر را برای خرید اصلی (که لغو شده اما هنوز فعال است) طی کرده‌اند، سیستم به‌طور خودکار انتخاب آن‌ها را تشخیص می‌دهد و میانای کاربر را برای بازیابی این خریدها نمایش می‌دهد. از آن‌ها خواسته می‌شود که خرید مجدد اشتراک ازطریق Google Play را تأیید کنند، اما لازم نیست دوباره جریان انتخاب کاربر را طی کنند. در این مورد، کد خرید جدیدی برای کاربر صادر می‌شود. پشتیبان شما SUBSCRIPTION_PURCHASED اعلان بی‌درنگ توسعه‌دهنده را دریافت می‌کند و مقدار linkedPurchaseToken برای وضعیت خرید جدید مانند ارتقا یا تنزل سطح، با کد خرید قدیمی برای اشتراکی که لغو شده است تنظیم می‌شود.

ازسرگیری اشتراک‌ها

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

همچنین می‌توان با پردازش آن به‌طور مشابه با ثبت‌نام استاندارد، امکان اشتراک مجدد را ازطریق برنامه فعال کرد. کاربران باید بتوانند سیستم صورت‌حساب موردنظرشان را برای استفاده انتخاب کنند. همان‌طور که در راه‌اندازی جریان صورت‌حساب به‌انتخاب کاربر توضیح داده شده است، ممکن است در این مورد launchBillingFlow() فراخوانده شود.

آزمایش صورت‌حساب جایگزین

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

مراحل بعدی

پس‌از تکمیل ادغام درون‌برنامه‌ای، آماده ادغام زیرینه خود هستید.