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

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

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

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

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

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

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

برای ادغام با Alternative Billing Only، برنامه واجد شرایط شما باید یک صفحه اطلاعات نشان دهد که به کاربران کمک کند تا متوجه شوند که صورتحساب توسط Google Play مدیریت نخواهد شد. صفحه اطلاعات باید با فراخوانی API showAlternativeBillingOnlyInformationDialog قبل از شروع جریان Alternative Billing هر بار به کاربران نشان داده شود. اگر کاربر قبلاً کادر محاوره‌ای را تأیید کرده باشد، استفاده از این 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 را فراخوانی کند تا دوباره کادر محاوره‌ای را به کاربر نشان دهد. برای سایر کدهای پاسخ، به بخش مدیریت پاسخ مراجعه کنید.

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

تمام تراکنش‌های انجام‌شده از طریق یک سیستم پرداخت جایگزین باید ظرف ۲۴ ساعت با فراخوانی API توسعه‌دهنده Google Play از بک‌اند شما، به گوگل پلی گزارش شوند و یک externalTransactionToken که با استفاده از API شرح داده‌شده در زیر دریافت می‌شود، ارائه شود. یک externalTransactionToken جدید باید برای هر خرید یک‌باره، هر اشتراک جدید و برای هرگونه ارتقا/تنزل به اشتراک موجود ایجاد شود. برای یادگیری نحوه گزارش تراکنش پس از دریافت 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 در دستگاه فعلی پشتیبانی نمی‌شوند. تراکنش را ادامه ندهید.
• USER_CANCELED : تراکنش را ادامه ندهید. تابع showAlternativeBillingOnlyInformationDialog() را دوباره فراخوانی کنید تا دفعه‌ی بعدی که کاربر سعی در خرید دارد، کادر محاوره‌ای اطلاعات به او نمایش داده شود.
• BILLING_UNAVAILABLE : این تراکنش واجد شرایط دریافت صورتحساب جایگزین نیست و بنابراین نباید تحت این برنامه انجام شود. این یا به این دلیل است که کاربر در کشور واجد شرایط این برنامه نیست یا حساب شما با موفقیت در این برنامه ثبت نشده است. اگر مورد دوم باشد، وضعیت ثبت نام خود را در کنسول توسعه‌دهندگان Play بررسی کنید.
• DEVELOPER_ERROR : خطایی در درخواست وجود دارد. قبل از ادامه، از پیام اشکال‌زدایی برای شناسایی و اصلاح خطا استفاده کنید.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE : این‌ها خطاهای گذرا هستند که باید دوباره امتحان شوند. در مورد SERVICE_DISCONNECTED قبل از امتحان مجدد، اتصال با Google Play را دوباره برقرار کنید.

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

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

مراحل بعدی

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