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

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

إعداد 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 = ...;

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

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

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

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

بعد الانتهاء من التكامل داخل التطبيق، يمكنك دمج الخلفية.