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

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

إعداد 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 Billing Library. يجب إنشاء رمز مميّز جديد للمعاملات الخارجية في كل مرة يزور فيها المستخدم موقعًا إلكترونيًا خارجيًا من خلال واجهة برمجة تطبيقات العروض الخارجية. ويمكن إجراء ذلك من خلال طلب البيانات من 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 Developer API من الخلفية. يجب الإبلاغ عن المعاملات الخارجية مع توفير externalTransactionToken يتم الحصول عليه باستخدام واجهة برمجة تطبيقات createExternalOfferReportingDetailsAsync. إذا أجرى المستخدم عدة عمليات شراء، يمكنك استخدام علامة 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 قبل إعادة المحاولة.

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

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

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

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