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

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

راه‌اندازی کتابخانه پرداخت بازی

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

اتصال به گوگل پلی

مراحل اولیه فرآیند ادغام، همان مراحلی است که در راهنمای ادغام صورتحساب گوگل پلی توضیح داده شده است، با این تفاوت که هنگام مقداردهی اولیه 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()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

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() راه‌اندازی کنید. این کار مشابه راه‌اندازی جریان خرید با یکپارچه‌سازی سیستم پرداخت گوگل پلی است: شما یک نمونه ProductDetails و یک offerToken مربوط به محصول و پیشنهادی که کاربر می‌خواهد دریافت کند، ارائه می‌دهید. اگر کاربر سیستم پرداخت گوگل پلی را انتخاب کند، از این اطلاعات برای ادامه جریان خرید استفاده می‌شود.

وقتی توسعه‌دهندگان تابع launchBillingFlow() فراخوانی می‌کنند، سیستم پرداخت گوگل پلی بررسی‌های زیر را انجام می‌دهد:

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

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

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

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

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

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

UserChoiceBillingListener باید اقدامات زیر را انجام دهد:

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

اگر کاربر خرید را با استفاده از سیستم پرداخت جایگزین تکمیل کند، شما باید ظرف ۲۴ ساعت با فراخوانی API توسعه‌دهنده 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.
    }

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.
    }
};

وقتی کاربر سیستم پرداخت گوگل پلی را انتخاب می‌کند

اگر کاربر سیستم پرداخت گوگل پلی را انتخاب کند، خرید خود را از طریق گوگل پلی ادامه می‌دهد.

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

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

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

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

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

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

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

اشتراک‌هایی که از طریق یک سیستم پرداخت جایگزین خریداری شده‌اند

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

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

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

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.

// 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.

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

اشتراک‌های خریداری‌شده از طریق سیستم پرداخت گوگل پلی

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

1. offerToken پیشنهاد انتخاب شده برای طرح جدید را شناسایی کنید:

   کاتلین

   val offerTokenNewPlan = productDetailsNewPlan
        .getSubscriptionOfferDetails(selectedOfferIndex)
        .getOfferToken()
   

   جاوا

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

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

   کاتلین

   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()
                   // purchaseToken can be found in
                   // Purchase#getPurchaseToken
                   .setOldPurchaseToken(oldToken)
                   .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                   .build()
           )
           .build()
   
   val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
   

   جاوا

   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);
   

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

لغو و بازیابی اشتراک

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

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

اشتراک‌هایی که از طریق یک سیستم پرداخت جایگزین خریداری شده‌اند

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

اشتراک‌های خریداری‌شده از طریق سیستم پرداخت گوگل پلی

به‌طورکلی، کاربران می‌توانند اشتراک‌های خود را در سیستم صورتحساب گوگل پلی بازیابی کنند. برای اشتراک‌های لغو شده‌ای که در ابتدا در سیستم صورتحساب گوگل پلی خریداری شده‌اند، کاربر می‌تواند در حین فعال بودن اشتراک، از طریق ویژگی «اشتراک مجدد» گوگل پلی، لغو لغو را لغو کند. در این صورت، شما یک اعلان توسعه‌دهنده بلادرنگ SUBSCRIPTION_RESTARTED در پنل مدیریت خود دریافت می‌کنید و توکن خرید جدیدی صادر نمی‌شود - توکن اصلی برای ادامه اشتراک استفاده می‌شود. برای یادگیری نحوه مدیریت بازیابی در سیستم صورتحساب گوگل پلی، به بخش «بازیابی‌ها» در راهنمای مدیریت اشتراک مراجعه کنید.

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

اشتراک‌های مجدد

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

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

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

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

مراحل بعدی

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