إرشادات الدمج داخل التطبيق لنظام الفوترة البديل فقط

يصف هذا الدليل كيفية دمج واجهات برمجة التطبيقات لتقديم نظام فوترة بديل فقط (أي بدون خيار المستخدم) في التطبيقات المؤهَّلة. لمعرفة المزيد من المعلومات عن هذه البرامج ، بما في ذلك متطلبات الأهلية والنطاق الجغرافي، يُرجى الاطّلاع على مقالة لمحة عن نظام الفوترة البديل.

إعداد Play Billing Library

يجب إضافة تبعية Play Billing Library إلى تطبيق Android. ولاستخدام واجهات برمجة التطبيقات لنظام الفوترة البديل، يجب استخدام الإصدار 6.1 أو إصدار أحدث.

الربط بخدمة Google Play

تتطابق الخطوات الأولى في عملية التكامل مع الخطوات الموضّحة في دليل تكامل نظام الفوترة في Google Play، مع إجراء بعض التعديلات عند تهيئة BillingClient:

  • يجب استدعاء طريقة جديدة للإشارة إلى أنّ تطبيقك يستخدم نظام فوترة بديلاً فقط: enableAlternativeBillingOnly.

يوضّح المثال التالي كيفية تهيئة BillingClient مع إجراء هذه التعديلات:

Kotlin

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

Java

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

بعد تهيئة BillingClient، يجب إنشاء اتصال بخدمة Google Play كما هو موضّح في دليل التكامل.

التحقق من التوفّر

يجب أن يؤكّد تطبيقك توفّر نظام الفوترة البديل فقط من خلال استدعاء isAlternativeBillingOnlyAvailableAsync.

ستعرض واجهة برمجة التطبيقات هذه BillingResponseCode.OK إذا كان نظام الفوترة البديل فقط متوفّرًا. يُرجى الرجوع إلى قسم معالجة الاستجابة للحصول على تفاصيل حول كيفية استجابة تطبيقك لرموز الاستجابة الأخرى.

Kotlin

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

Java


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 قبل بدء عملية الفوترة البديلة في كل مرة. إذا كان المستخدم قد وافق على مربّع الحوار من قبل، لن يؤدي استخدام واجهة برمجة التطبيقات هذه عادةً إلى عرض مربّع الحوار مرة أخرى. قد يتم عرض مربّع الحوار مرة أخرى للمستخدم في بعض الحالات، مثلاً إذا محا المستخدم ذاكرة التخزين المؤقت على جهازه.

Kotlin

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

Java


// 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 بجميع المعاملات التي يتم إجراؤها من خلال نظام فوترة بديل يجب الإبلاغ عنها إلى Google Play من خلال استدعاء Google Play Developer API من الخلفية خلال 24 ساعة، مع تقديم externalTransactionToken الذي يتم الحصول عليه باستخدام واجهة برمجة التطبيقات الموضّحة أدناه. يجب إنشاء externalTransactionToken جديد لكل عملية شراء لمرة واحدة ولكل اشتراك جديد ولأي ترقية/تخفيض لاشتراك حالي. لمعرفة كيفية الإبلاغ عن معاملة بعد الحصول على externalTransactionToken، يُرجى الاطّلاع على دليل تكامل الخلفية.

Kotlin

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

Java


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: واجهات برمجة التطبيقات لنظام الفوترة البديل غير متاحة في متجر Google Play على الجهاز الحالي. يجب عدم متابعة المعاملة.
  • USER_CANCELED: يجب عدم متابعة المعاملة. يجب استدعاء showAlternativeBillingOnlyInformationDialog() مرة أخرى لعرض مربّع حوار المعلومات على المستخدم في المرة التالية التي يحاول فيها إجراء عملية شراء.
  • BILLING_UNAVAILABLE: المعاملة غير مؤهَّلة لنظام الفوترة البديل فقط، وبالتالي يجب عدم متابعتها بموجب هذا البرنامج. يرجع ذلك إما إلى أنّ المستخدم ليس في بلد مؤهَّل لهذا البرنامج أو لم يتم تسجيل حسابك بنجاح في البرنامج. في الحالة الأخيرة، يُرجى التحقّق من حالة التسجيل في Play Console.
  • DEVELOPER_ERROR: هناك خطأ في الطلب. يجب استخدام رسالة تصحيح الأخطاء لتحديد الخطأ وتصحيحه قبل المتابعة.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: هذه أخطاء مؤقتة يجب إعادة المحاولة في حال حدوثها. في حال حدوث SERVICE_DISCONNECTED، يجب إعادة إنشاء اتصال بخدمة Google Play قبل إعادة المحاولة.

اختبار نظام الفوترة البديل

يجب استخدام مختبِري التراخيص لاختبار عملية تكامل نظام الفوترة البديل. لن يتم إصدار فاتورة لك مقابل المعاملات التي بدأتها حسابات مختبِري التراخيص. يُرجى الاطّلاع على مقالة اختبار الفوترة داخل التطبيقات من خلال ترخيص التطبيق لمزيد من المعلومات حول إعداد مختبِري التراخيص.

الخطوات التالية

بعد الانتهاء من التكامل داخل التطبيق، يصبح كل شيء جاهزًا لـ دمج الخلفية.