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

يوضّح هذا المستند كيفية دمج واجهات برمجة التطبيقات في Play Billing Library لتقديم عمليات دفع خارجية في التطبيقات المؤهَّلة. لمزيد من المعلومات حول هذا البرنامج، يُرجى الاطّلاع على متطلبات البرنامج.

إعداد Play Billing Library

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

تهيئة عميل الفوترة

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

• عليك استدعاء طريقة جديدة enableBillingProgram(EnableBillingProgramParams) للإشارة إلى أنّك تريد تقديم عمليات دفع خارجية.
• عليك تسجيل DeveloperProvidedBillingListener لـ معالجة الحالات التي يختار فيها المستخدم الدفع على موقعك الإلكتروني أو في تطبيق دفع.

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

val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // Handle new Google Play purchase.
    }

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build()
    )
    .build()
Integration.kt

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

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

بعد تهيئة BillingClient، يمكنك الربط بخدمة Google Play كما هو موضّح في الربط بخدمة Google Play.

التحقّق من أهلية المستخدم

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

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_PAYMENTS,
    object : BillingProgramAvailabilityListener {
        override fun onBillingProgramAvailabilityResponse(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            if (billingResult.responseCode != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling external payments unavailable, etc.
                return
            }

            // External payments are available. Can proceed with generating an
            // external transaction token.
        }
    }
)
Integration.kt

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

يُرجى الاطّلاع على قسم معالجة الردود للحصول على تفاصيل حول كيفية استجابة تطبيقك لرموز الاستجابة الأخرى. إذا كنت تستخدم إضافات Kotlin، يمكنك استخدام إجراءات Kotlin الفرعية حتى لا تضطر إلى تحديد مستمع منفصل.

عرض المنتجات المتاحة

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

إعداد رمز مميّز لمعاملة خارجية

للإبلاغ عن معاملة خارجية إلى Google Play، يجب أن يكون لديك رمز مميّز لمعاملة خارجية تم إنشاؤه من Play Billing Library. يجب إنشاء رمز مميّز جديد لمعاملة خارجية في كل مرة يزور فيها المستخدم موقعًا إلكترونيًا أو تطبيقًا خارجيًا من خلال واجهة برمجة التطبيقات لعمليات الدفع الخارجية. يمكن إجراء ذلك من خلال استدعاء واجهة برمجة التطبيقات createBillingProgramReportingDetailsAsync. يجب إنشاء الرمز المميّز قبل استدعاء `launchBillingFlow` مباشرةً.

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
    params,
    object : BillingProgramReportingDetailsListener {
        override fun onCreateBillingProgramReportingDetailsResponse(
            billingResult: BillingResult,
            billingProgramReportingDetails: BillingProgramReportingDetails?
        ) {
            if (billingResult.responseCode != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }
            val externalTransactionToken =
                billingProgramReportingDetails?.externalTransactionToken
            // Persist the external transaction token locally. Pass it to
            // the external website using DeveloperBillingOptionParams when
            // launchBillingFlow is called.
        }
    }
)
Integration.kt

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

إذا كنت تستخدم إضافات Kotlin، يمكنك استخدام إجراءات Kotlin الفرعية حتى لا تضطر إلى تحديد مستمع منفصل.

بدء مسار الدفع الخارجي

ابدأ مسار الدفع الخارجي من خلال استدعاء launchBillingFlow() بطريقة مشابهة لـ بدء مسار شراء عند دمج نظام الفوترة في Google Play، ولكن مع توفير مَعلمة إضافية هي DeveloperBillingOptionParams تشير إلى أنّ تطبيقك يريد تفعيل مسار الدفع الخارجي لعملية الشراء هذه.

يجب أن يحتوي DeveloperBillingOptionParams على ما يلي:

• billingProgram مضبوط على برنامج الفوترة EXTERNAL_PAYMENTS
• linkURI مضبوط على وجهة الرابط
• launchMode مضبوط على LAUNCH_IN_EXTERNAL_BROWSER_OR_APP إذا كان على Google Play بدء الرابط، أو CALLER_WILL_LAUNCH_LINK إذا كان تطبيقك سيبدأ الرابط.

عندما يستدعي تطبيقك launchBillingFlow() مع توفير DeveloperBillingOptionParams، يُجري نظام الفوترة في Google Play عملية التحقّق التالية:

• يتحقّق النظام مما إذا كان بلد المستخدم في Google Play بلدًا يتيح عمليات الدفع الخارجية (أي بلدًا متوافقًا). إذا كان بلد المستخدم في Google Play متوافقًا، يتحقّق Google Play مما إذا كانت عمليات الدفع الخارجية مفعّلة استنادًا إلى إعدادات BillingClient وما إذا تم توفير DeveloperBillingOptionParams.
  • إذا تم تفعيل عمليات الدفع الخارجية، يعرض مسار الشراء تجربة المستخدم التي تتيح له الاختيار.
  • إذا لم يتم تفعيل عمليات الدفع الخارجية، يعرض مسار الشراء تجربة المستخدم العادية لنظام الفوترة في Google Play، بدون خيار للمستخدم.
• إذا لم يكن بلد المستخدم في Google Play بلدًا متوافقًا، يعرض مسار الشراء تجربة المستخدم العادية لنظام الفوترة في Google Play، بدون خيار للمستخدم.

يوضّح المقتطف التالي كيفية إنشاء DeveloperBillingOptionParams:

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase".toUri())
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()
Integration.kt

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

معالجة خيار المستخدم

تختلف طريقة معالجة بقية مسار الشراء استنادًا إلى ما إذا اختار المستخدم نظام الفوترة في Google Play أو الدفع على موقعك الإلكتروني.

عندما يختار المستخدم الدفع على موقعك الإلكتروني أو في تطبيق دفع

إذا اختار المستخدم الدفع على موقعك الإلكتروني، يستدعي Google Play السمة DeveloperProvidedBillingListener لإشعار التطبيق بأنّ المستخدم اختار الدفع على موقعك الإلكتروني أو في تطبيق دفع. على وجه الخصوص، يتم استدعاء الطريقة onUserSelectedDeveloperBilling().

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

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

عندما يختار المستخدم نظام الفوترة في Google Play

إذا اختار المستخدم نظام الفوترة في Google Play، سيواصل عملية الشراء من خلال Google Play.

• يُرجى الاطّلاع على مقالة معالجة عمليات الشراء في دليل دمج المكتبة لمزيد من المعلومات حول كيفية معالجة عمليات الشراء الجديدة داخل التطبيقات من خلال نظام الفوترة في Google Play.
• يُرجى الاطّلاع على مقالة الاشتراكات الجديدة في دليل إدارة الاشتراكات للحصول على إرشادات إضافية حول عمليات شراء الاشتراكات.

معالجة التغييرات في الاشتراك

بالنسبة إلى المطوّرين الذين يستخدمون عمليات الدفع الخارجية، يجب معالجة عمليات الشراء من خلال نظام الفوترة في Google Play أو الإبلاغ عنها باستخدام externalTransactionId، وذلك حسب خيار المستخدم. يمكن إجراء تغييرات على الاشتراكات الحالية التي تمت معالجتها من خلال الموقع الإلكتروني للمطوّر من خلال نظام الفوترة نفسه حتى انتهاء صلاحيتها.

يوضّح هذا القسم كيفية معالجة بعض السيناريوهات الشائعة لتغيير الاشتراكات.

مسارات الترقية والرجوع إلى إصدار سابق

يجب معالجة تغييرات خطة الاشتراك، بما في ذلك مسارات الترقية والرجوع إلى إصدار سابق، بشكل مختلف استنادًا إلى ما إذا تم شراء الاشتراك في الأصل من خلال نظام الفوترة في Google Play أو من خلال الموقع الإلكتروني للمطوّر.

تتم معالجة الإضافات التي تعتمد على اشتراك حالي وتستخدم طريقة الدفع نفسها وتتطابق مع الرسوم المتكرّرة كترقيات. بالنسبة إلى الإضافات الأخرى، يجب أن يتمكّن المستخدمون من اختيار نظام الفوترة الذي يريدون استخدامه. ابدأ تجربة شراء جديدة باستخدام launchBillingFlow()، كما هو موضّح في قسم بدء مسار الدفع الخارجي.

الاشتراكات التي تم شراؤها من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع

بالنسبة إلى الاشتراكات التي تم شراؤها في الأصل من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع بعد أن اختار المستخدم، يجب أن ينتقل المستخدمون الذين يطلبون ترقية أو الرجوع إلى إصدار سابق من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع بدون المرور بتجربة اختيار المستخدم مرة أخرى.

لإجراء ذلك، استدعِ launchBillingFlow() عندما يطلب المستخدم ترقية أو الرجوع إلى إصدار سابق. بدلاً من تحديد مَعلمات أخرى ضمن العنصر SubscriptionUpdateParams، استخدِم setOriginalExternalTransactionId()، مع توفير رقم تعريف المعاملة الخارجية لعملية الشراء الأصلية.

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

عند اكتمال الترقية أو الرجوع إلى إصدار سابق باستخدام الموقع الإلكتروني للمطوّر أو تطبيق دفع، عليك الإبلاغ عن معاملة جديدة باستخدام الرمز المميّز للمعاملة الخارجية الذي تم الحصول عليه من خلال الاستدعاء السابق لعملية شراء الاشتراك الجديد.

الاشتراكات التي تم شراؤها من خلال نظام الفوترة في Google Play

وبالمثل، يجب أن يمر المستخدمون الذين اشتروا اشتراكهم الحالي من خلال نظام الفوترة في Google Play بعد أن اختاروا مسار الفوترة العادي في Google Play . يجب عدم ضبط DeveloperBillingOptionParams في استدعاء launchBillingFlow.

عمليات إلغاء الاشتراكات واستعادتها

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

من الشائع أن يقرّر المستخدمون التراجع عن الإلغاء خلال هذه الفترة النشطة. في هذا الدليل، يُطلق على هذا الإجراء اسم الاستعادة. توضّح الأقسام التالية كيفية معالجة سيناريوهات الاستعادة في عملية دمج واجهة برمجة التطبيقات لعمليات الدفع الخارجية.

الاشتراكات التي تم شراؤها من خلال الموقع الإلكتروني للمطوّر

إذا كان لديك رقم تعريف معاملة خارجية لاشتراك تم إلغاؤه، ليس من الضروري استدعاء launchBillingFlow() لاستعادة الاشتراك، لذا يجب عدم استخدامه لهذا النوع من التفعيل. إذا استعاد المستخدم اشتراكه أثناء الفترة النشطة لاشتراك تم إلغاؤه، لا تحدث أي معاملة في ذلك الوقت. يمكنك فقط مواصلة الإبلاغ عن عمليات التجديد عند انتهاء الدورة الحالية وحدوث عملية التجديد التالية. ويشمل ذلك الحالات التي يحصل فيها المستخدم على رصيد أو سعر تجديد خاص كجزء من عملية الاستعادة (على سبيل المثال، عرض ترويجي لتشجيع المستخدم على مواصلة اشتراكه).

الاشتراكات التي تم شراؤها من خلال نظام الفوترة في Google Play

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

يمكنك أيضًا بدء عملية استعادة في نظام الفوترة في Google Play من التطبيق من خلال استدعاء launchBillingFlow(). يُرجى الاطّلاع على مقالة قبل انتهاء صلاحية الاشتراك - داخل التطبيق للحصول على شرح حول كيفية إجراء ذلك. في حالة المستخدمين الذين مرّوا بمسار اختيار المستخدم لعملية الشراء الأصلية (التي تم إلغاؤها ولكنها لا تزال نشطة)، يرصد النظام تلقائيًا خيارهم ويعرض واجهة المستخدم لاستعادة عمليات الشراء هذه. يُطلب منهم تأكيد إعادة شراء الاشتراك من خلال Google Play، ولكن ليس عليهم المرور بمسار اختيار المستخدم مرة أخرى. يتم إصدار رمز مميّز جديد للشراء للمستخدم في هذه الحالة. يتلقّى نظامك الخلفي إشعارًا في الوقت الفعلي للمطوّر SUBSCRIPTION_PURCHASED، ويتم ضبط قيمة `linkedPurchaseToken` لحالة الشراء الجديدة كما هو الحال في الترقية أو الرجوع إلى إصدار سابق، مع الرمز المميّز القديم للشراء للاشتراك الذي تم إلغاؤه.

عمليات إعادة الاشتراك

إذا انتهت صلاحية الاشتراك تمامًا، سواء كان ذلك بسبب الإلغاء أو رفض الدفع بدون استرداد (فترة تعليق منتهية الصلاحية)، يجب على المستخدم إعادة الاشتراك إذا أراد إعادة تفعيل الحق.

يمكن أيضًا تفعيل إعادة الاشتراك من خلال التطبيق عن طريق معالجته بطريقة مشابهة لعملية التسجيل العادية. يجب أن يتمكّن المستخدمون من اختيار نظام الفوترة الذي يريدون استخدامه. يمكن استدعاء launchBillingFlow() في هذه الحالة، كما هو موضّح في قسم بدء مسار الدفع الخارجي.

معالجة الردود

عند حدوث خطأ، قد توفّر الطرق isBillingProgramAvailableAsync() و createBillingProgramReportingDetailsAsync() وlaunchBillingFlow() رمز BillingResponseCode آخر غير BillingResponseCode.OK. يُرجى مراعاة معالجة رموز الاستجابة هذه على النحو التالي:

• BillingResponseCode.ERROR: هذا خطأ داخلي. لا تتابع المعاملة أو فتح الموقع الإلكتروني الخارجي. أعِد المحاولة من خلال استدعاء واجهة برمجة التطبيقات مرة أخرى.
• BillingResponseCode.FEATURE_NOT_SUPPORTED: واجهات برمجة التطبيقات لعمليات الدفع الخارجية غير متاحة في متجر Play على الجهاز الحالي. لا تتابع المعاملة أو فتح الموقع الإلكتروني الخارجي.
• BillingResponseCode.DEVELOPER_ERROR: هناك خطأ في الطلب. استخدِم رسالة تصحيح الأخطاء لتحديد الخطأ وتصحيحه قبل المتابعة.
• BillingResponseCode.USER_CANCELED: لا تتابع فتح الموقع الإلكتروني أو التطبيق الخارجي. استدعِ launchBillingFlow() مرة أخرى لعرض مربّع الحوار المعلوماتي للمستخدم في المرة التالية التي تحاول فيها توجيه المستخدم إلى خارج التطبيق.
• BillingResponseCode.BILLING_UNAVAILABLE: المعاملة غير مؤهَّلة لعمليات الدفع الخارجية، وبالتالي لن تكون الفوترة الخاصة بالمطوّر متاحة بموجب هذا البرنامج. يرجع ذلك إما إلى أنّ المستخدم ليس في بلد مؤهَّل لهذا البرنامج أو لم يتم تسجيل حسابك بنجاح في البرنامج. إذا كان السبب هو الأخير، تحقَّق من حالة التسجيل في Play Console.
• BillingResponseCode.NETWORK_ERROR و BillingResponseCode.SERVICE_DISCONNECTED و BillingResponseCode.SERVICE_UNAVAILABLE: هذه أخطاء مؤقتة يجب معالجتها باستخدام سياسة مناسبة لإعادة المحاولة. في حالة SERVICE_DISCONNECTED، أعِد إنشاء اتصال بخدمة Google Play قبل إعادة المحاولة.

اختبار روابط الدفع الخارجية

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

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

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