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

يوضّح هذا الدليل كيفية الدمج مع واجهات برمجة التطبيقات لإتاحة العروض الترويجية الخارجية. في التطبيقات والمناطق المؤهَّلة مزيد من المعلومات حول برنامج العروض الترويجية الخارجية بما في ذلك متطلبات الأهلية والنطاق الجغرافي، فراجع متطلبات البرنامج.

إعداد Play Billing Library

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

الاتصال بـ Google Play

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

• يجب استدعاء طريقة جديدة للإشارة إلى أنّك تريد استخدام واجهة برمجة تطبيقات خارجية من العروض: enableExternalOffer.

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

Kotlin

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

Java

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

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

التحقق من التوفر

يجب أن يتأكّد التطبيق من توفّر العروض الترويجية الخارجية من خلال الاتصال isExternalOfferAvailableAsync

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

Kotlin

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
})

Java

billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }

});

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

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

Kotlin

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

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

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

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

Kotlin

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java

// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

إذا أرجعت هذه الطريقة القيمة BillingResponseCode.OK، يمكن لتطبيقك المتابعة إلى توجيه المستخدم إلى موقع الويب الخارجي. إذا تم إرجاع الطريقة BillingResponseCode.USER_CANCELED، يجب ألا يواصل تطبيقك فتح موقعك الإلكتروني.

إبلاغ Google Play بالمعاملات

ملاحظة: يُرجى الاطّلاع على مقالة التسجيل في برنامج العروض الترويجية الخارجية للاطّلاع على المعاملات. إعداد التقارير.

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

التعامل مع الردود

عند حدوث خطأ، تُستخدم الطريقتان isExternalOfferAvailableAsync، createExternalOfferReportingDetailsAsync و قد تعرض showExternalOfferInformationDialog ردودًا غير BillingResponseCode.OK يمكنك التعامل مع رموز الاستجابة هذه على النحو التالي:

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

اختبار العروض الترويجية الخارجية

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

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

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