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

يوضّح هذا الدليل طريقة دمج واجهات برمجة التطبيقات لتقديم نظام فوترة بديل مع اختيار المستخدم في تطبيقك.

إعداد Play Billing Library

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

الاتصال بـ Google Play

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

• يلزمك استدعاء طريقة جديدة للإشارة إلى أنك تريد تقديم أحد خيارات الفوترة: enableUserChoiceBilling.
• يجب تسجيل UserChoiceBillingListener لمعالجة الطلبات. حيث يختار المستخدم نظام فوترة بديلاً.

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

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

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

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

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

عرض المنتجات المتوفّرة

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

بدء مسار الفوترة حسب اختيار المستخدم

يمكنك بدء مسار الفوترة حسب اختيار المستخدم من خلال الاتصال بالرقم launchBillingFlow(). يعمل هذا الإجراء هو نفسه بدء مسار الشراء باستخدام نظام الفوترة في Google Play التكامل: تقدم مثيل ProductDetails وofferToken المقابلة للمنتج والعرض الذي يريد المستخدم الحصول عليه. في حال حذف يختار المستخدم نظام الفوترة في Google Play، ويتم استخدام هذه المعلومات مواصلة عملية الشراء

عندما يتصل المطوّرون بـ "launchBillingFlow()"، فإنّ نظام الفوترة في Google Play إجراء الفحص التالي:

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

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

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

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

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

الرمز المميّز للمعاملة الخارجية المقدَّم في العنصر UserChoiceDetails توقيعًا لاختيار المستخدم لإدخال نظام الفوترة البديل التدفق. استخدم هذا الرمز للإبلاغ عن أي معاملة تنتج عن هذا الخيار في دليل الدمج مع الخلفية.

على "UserChoiceBillingListener" تنفيذ الإجراءات التالية:

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

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

يوضح المثال التالي كيفية تنفيذ UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

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

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

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

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

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

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

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

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

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

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

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

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

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

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

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

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

1. حدِّد offerToken من العرض المحدّد للخطة الجديدة:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. عليك إرسال المعلومات الصحيحة إلى نظام الفوترة في Google Play لمعالجة عملية شراء جديدة، بما في ذلك الرمز المميز للشراء للاشتراك الحالي:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

ستتم مواصلة عملية الشراء هذه في نظام الفوترة في Google Play، وسيتلقّى تطبيقك طلب PurchasesUpdatedListener.onPurchaseUpdated مع نتيجة عملية الشراء. إذا تمت عملية الشراء بنجاح، سيتم أيضًا استخدام طريقة onPurchaseUpdated() تلقّي معلومات الشراء الجديدة وتتلقّى الخلفية SUBSCRIPTION_PURCHASED إشعار في الوقت الفعلي للمطوّرين عند سحب حالة عملية الشراء الجديدة، أو السمة linkedPurchaseToken ترتبط بعملية الشراء القديمة لشراء اشتراك، بحيث يمكنك سحبه التي ننصح بها.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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