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

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

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

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 يجب أن يستدعي تطبيقك showAlternative BillingOnlyInfoDialog لعرض مربع الحوار للمستخدم مرة أخرى. للحصول على رموز الاستجابة الأخرى، يمكنك الاطّلاع على مقالة معالجة الردود. .

الإبلاغ عن المعاملات في 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() ردود non-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 قبل إعادة المحاولة.

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

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

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

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