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

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

إعداد Play Billing Library

أضِف تبعية "مكتبة الفوترة في Play" إلى تطبيق 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()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

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(
      billingProgram: Int, billingResult: BillingResult) {
        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.
})

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

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 على وجهة الرابط
• اضبط القيمة على LAUNCH_IN_EXTERNAL_BROWSER_OR_APP إذا كان من المفترض أن يفتح Google Play الرابط، أو على CALLER_WILL_LAUNCH_LINK إذا كان تطبيقك سيفتح الرابط.launchMode

عندما يطلب تطبيقك 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")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("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، يمكن للمستخدم اختيار التراجع عن الإلغاء أثناء نشاط الاشتراك من خلال ميزة إعادة الاشتراك في Google Play. في هذه الحالة، ستتلقّى إشعارًا في الوقت الفعلي للمطوّر بعنوان 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 قبل إعادة المحاولة.

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

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

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

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