راهنمای ادغام درون برنامه ای فقط برای صورتحساب جایگزین

این راهنما نحوه ادغام APIها را برای ارائه صورت‌حساب جایگزین (یعنی بدون انتخاب کاربر) در برنامه‌های واجد شرایط توضیح می‌دهد. برای کسب اطلاعات بیشتر در مورد این برنامه ها از جمله الزامات واجد شرایط بودن و محدوده جغرافیایی به «درباره صورتحساب جایگزین» مراجعه کنید.

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

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

به Google Play متصل شوید

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

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

مثال زیر راه اندازی اولیه BillingClient با این تغییرات نشان می دهد:

var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

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

بررسی در دسترس بودن

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

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

billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

گفتگوی اطلاعات برای کاربران

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

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener);

اگر این روش BillingResponseCode.OK را برگرداند، برنامه شما می‌تواند تراکنش را ادامه دهد. در مورد BillingResponseCode.USER_CANCELED ، برنامه شما باید showAlternativeBillingOnlyInformationDialog را فراخوانی کند تا دوباره گفتگو را به کاربر نشان دهد. برای سایر کدهای پاسخ به بخش رسیدگی به پاسخ مراجعه کنید.

گزارش تراکنش ها به گوگل پلی

همه تراکنش‌های انجام‌شده از طریق یک سیستم صورت‌حساب جایگزین باید با تماس با Google Play Developer API از پشتیبان خود ظرف 24 ساعت به Google Play گزارش شود ، و یک externalTransactionToken ارائه می‌کند که با استفاده از API توضیح داده شده در زیر به دست می‌آید. برای هر خرید یک‌باره، هر اشتراک جدید و برای هر ارتقا/کاهش به اشتراک موجود، باید یک خارجی TransactionToken جدید ایجاد شود. برای یادگیری نحوه گزارش یک تراکنش پس از به دست آوردن یک externalTransactionToken ، راهنمای ادغام باطن را ببینید.

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

رسیدگی به پاسخ

روش‌های بالا isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() و createAlternativeBillingOnlyReportingDetailsAsync() ممکن است در صورت بروز خطا، پاسخ‌های غیر BillingResponseCode.OK را برگردانند. مدیریت توصیه شده برای خطاها در زیر توضیح داده شده است:

• ERROR : این یک خطای داخلی است. معامله را ادامه ندهید با فراخوانی showAlternativeBillingOnlyInformationDialog() دوباره سعی کنید تا دفعه بعد که کاربر اقدام به خرید کرد، محاوره اطلاعات را به کاربر نمایش دهد.
• FEATURE_NOT_SUPPORTED : APIهای صورت‌حساب جایگزین توسط Play Store در دستگاه فعلی پشتیبانی نمی‌شوند. پردازش تراکنش را از طریق سیستم صورتحساب جایگزین ادامه دهید. این تراکنش نیازی به گزارش به Google و همچنین هرگونه تمدید برای اشتراک های تحت تأثیر نیست.
• USER_CANCELED : تراکنش را ادامه ندهید. دوباره showAlternativeBillingOnlyInformationDialog() را فراخوانی کنید تا دفعه بعد که کاربر اقدام به خرید کرد، کادر گفتگوی اطلاعات به کاربر نمایش داده شود.
• BILLING_UNAVAILABLE : تراکنش فقط برای صورت‌حساب جایگزین واجد شرایط نیست و بنابراین نباید تحت این برنامه ادامه یابد. این به این دلیل است که کاربر در کشوری واجد شرایط برای این برنامه نیست یا حساب شما با موفقیت در برنامه ثبت نام نکرده است. اگر دومی است، وضعیت ثبت نام خود را در Play Developer Console بررسی کنید.
• DEVELOPER_ERROR : در درخواست خطایی وجود دارد. قبل از ادامه، از پیام اشکال زدایی برای شناسایی و تصحیح خطا استفاده کنید.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE : اینها خطاهای گذرا هستند که باید دوباره امتحان شوند. در مورد SERVICE_DISCONNECTED قبل از تلاش مجدد، دوباره با Google Play ارتباط برقرار کنید.

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

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

مراحل بعدی

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