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

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

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

وابستگی Play Billing Library را به برنامه Android خود اضافه کنید . برای استفاده از APIهای صورتحساب جایگزین، باید از نسخه 5.2 یا بالاتر استفاده کنید. اگر نیاز به مهاجرت از نسخه قبلی دارید، قبل از اقدام به اجرای صورت‌حساب جایگزین، دستورالعمل‌های راهنمای مهاجرت را دنبال کنید.

به 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.
   }

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

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

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

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

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

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

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

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

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

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

اگر کاربر خرید را با استفاده از سیستم صورت‌حساب جایگزین انجام دهد، باید طی 24 ساعت با تماس با Google Play Developer 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.
    }
};

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

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

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

کنترل تغییرات در اشتراک

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

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

ارتقاء و کاهش جریان

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

برافزاهایی که به اشتراک موجود وابسته هستند، روش پرداخت یکسانی را به اشتراک می‌گذارند، و هزینه‌های تکراری را هم‌تراز می‌کنند، به‌عنوان ارتقاء استفاده می‌شوند. برای سایر افزونه ها، کاربران باید بتوانند انتخاب کنند که از کدام سیستم صورتحساب می خواهند استفاده کنند. یک تجربه خرید جدید را با استفاده از 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 via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .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 via 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(selectedOfferIndex)
             .getOfferToken()

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

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

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

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

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

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

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

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

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

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

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

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

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

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

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

اشتراک مجدد را نیز می توان از طریق برنامه با پردازش آن به طور مشابه با یک ثبت نام استاندارد فعال کرد. کاربران باید بتوانند انتخاب کنند که از کدام سیستم صورتحساب می خواهند استفاده کنند. launchBillingFlow() ممکن است در این مورد فراخوانی شود، همانطور که در Launch the user option billing flow توضیح داده شده است.

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

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

مراحل بعدی

هنگامی که یکپارچه سازی درون برنامه ای را به پایان رساندید، آماده ادغام باطن خود هستید.