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

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

إعداد Play Billing Library

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

الربط بمتجر Google Play

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

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

يوضّح المثال التالي إعداد BillingClient باستخدام هذه التعديلات:

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

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

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

جارٍ التحقّق من مدى التوفّر

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

ستعرض واجهة برمجة التطبيقات هذه 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.
        }
    });

مربّع حوار المعلومات للمستخدمين

لدمج نظام الفوترة البديل فقط، يجب أن يعرض تطبيقك المؤهَّل شاشة معلومات تساعد المستخدمين في معرفة أنّ الفوترة لن تتم إدارتها من خلال Google Play. يجب عرض شاشة المعلومات للمستخدمين من خلال طلب بيانات من واجهة برمجة التطبيقات showAlternativeBillingOnlyInformationDialog قبل بدء عملية الفوترة البديلة في كل مرة. وإذا وافق المستخدم بالفعل على مربع الحوار، فلن يؤدي استخدام واجهة برمجة التطبيقات هذه عادةً إلى عرض مربع الحوار مرة أخرى. في بعض الأحيان، قد يظهر مربّع الحوار مرة أخرى للمستخدم في بعض الحالات، مثل ما إذا كان المستخدم يمحو ذاكرات التخزين المؤقت على جهازه.

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

إعداد تقارير عن المعاملات إلى Google Play

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

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

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

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

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