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

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

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

وابستگی «کتابخانه خدمات صورت‌حساب Play» را به برنامه Android خود اضافه کنید. برای استفاده از میاناهای برنامه‌سازی کاربردی صورت‌حساب جایگزین باید از نسخه ۶.۱ یا بالاتر استفاده کنید.

اتصال به Google Play

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

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

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

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

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.
    }
})
AlternativeBillingWithoutUserChoiceInApp.kt

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

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

val listener: AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { billingResult ->
        // check billingResult
    }

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(
        activity,
        listener
    )
AlternativeBillingWithoutUserChoiceInApp.kt

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

همه تراکنش‌های انجام‌شده ازطریق سیستم صورت‌حساب جایگزین باید با فراخوانی Google Play Developer 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.
    }
})
AlternativeBillingWithoutUserChoiceInApp.kt

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

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

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

مراحل بعدی

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