Offerwall Custom Choice API

مقدمة

تتيح لك واجهة برمجة التطبيقات Offerwall Custom Choice API دمج حلّ تحقيق الربح المخصّص الذي تستخدمه مع Offerwall في إدارة إعلانات Google.

لدمج حلّ تحقيق الربح الخاص بك مع Offerwall، اتّبِع خطوات إعداد الخيار المخصّص التالية. باختصار:

  1. فعِّل الخيار "اختيار مخصّص" لرسالة Offerwall من علامة التبويب الخصوصية والمراسلة في "مدير إعلانات Google".

  2. أضِف رمز JavaScript مخصّصًا بين علامتَي <head> و</head> في الموقع الإلكتروني الذي نشرت فيه Offerwall.

  3. أنشئ مثيلاً لكائن CustomOfferwallChoice كما هو موضّح في الأقسام التالية، وسجِّله في Offerwall في النافذة.

نموذج التعليمات البرمجية

للبدء بسرعة، اطّلِع على هذا المثال العملي لتنفيذ Offerwall Custom Choice API.

استخدام واجهة برمجة التطبيقات

‫CustomOfferwallChoice هو عنصر JavaScript يمكنك إضافته إلى Offerwall لدمج عملية تحقيق الربح المخصّصة.

// Define your custom choice.
class CustomOfferwallChoice {
  // Initialize your custom choice, which may include loading or preparing any
  // resources required to function.
  async initialize(params: InitializeParams): Promise<InitializeResponseEnum> {...}

  // Show your custom choice on the web page, which may be a subscription
  // service, micropayments service, rewarded ad, etc.
  async show(): Promise<boolean> {...}
}

// Register your custom choice with your Offerwall.
window.googlefc = window.googlefc || {};
window.googlefc.offerwall = window.googlefc.offerwall || {};
window.googlefc.offerwall.customchoice = window.googlefc.offerwall.customchoice || {};
window.googlefc.offerwall.customchoice.registry = new CustomOfferwallChoice();

تعريفات الطرق

يوضّح هذا القسم كل طريقة يجب أن تنفّذها CustomOfferwallChoice.

إعداد

initialize(params: InitializeParams): Promise<InitializeResponseEnum>

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

مثال

  async initialize(params: InitializeParams): Promise<InitializeResponseEnum> {
    // If your custom choice is inoperable on this page, return CUSTOM_CHOICE_DISABLED,
    // causing your Offerwall to exclude the custom choice option when rendering.
    const isCustomChoiceEnabled: boolean = await this.initializeCustomOfferwallChoice(params);
    if (!isCustomChoiceEnabled) {
      resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.CUSTOM_CHOICE_DISABLED);
    }

    // If the user should automatically be granted page access on page load, return
    // ACCESS_GRANTED, causing your Offerwall to be ineligible to render on this page.
    const isAccessGranted: boolean = await this.shouldUserBeGrantedPageAccess();
    if (isAccessGranted) {
      resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.ACCESS_GRANTED);
    }

    // If the user shouldn't automatically be granted page access on page load, return
    // ACCESS_NOT_GRANTED, causing your Offerwall to be eligible to render on this page.
    resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.ACCESS_NOT_GRANTED);
  }

إظهار

show(): Promise<boolean>

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

عند حلّ وعد الدالة show()، عليك إجراء ما يلي:

  • إخفاء حلّ تحقيق الربح الذي تم عرضه

  • إرجاع قيمة منطقية تشير إلى ما إذا كان المستخدم قد حصل على إذن بالوصول إلى محتوى الصفحة:

    • true: حصل المستخدم على إذن بالوصول إلى محتوى الصفحة. في هذه الحالة، لن يتم عرض Offerwall مرة أخرى عند حلّ الوعد.
    • ‫false: لم يتمكّن المستخدم من الوصول إلى محتوى الصفحة. في هذه الحالة، سيتم عرض Offerwall مرة أخرى عند حلّ الوعد.

مثال

  async show(): Promise<boolean> {
    // Show your custom choice dialog and hide it once the user completes an action.
    const didUserGainAccessToPage: boolean = await this.showCustomChoiceDialogUntilUserAction();

    resolve(didUserGainAccessToPage);
  }

تسجيل ميزة "الخيار المخصّص"

يتضمّن التسجيل تمرير عنصر CustomOfferwallChoice الذي تم إنشاؤه إلى سجلّ النوافذ التالي: window.googlefc.offerwall.customchoice.registry

مثال

    // Register your custom choice with your Offerwall.
    window.googlefc = window.googlefc || {};
    window.googlefc.offerwall = window.googlefc.offerwall || {};
    window.googlefc.offerwall.customchoice = window.googlefc.offerwall.customchoice || {};
    window.googlefc.offerwall.customchoice.registry = new CustomOfferwallChoice();

تعريفات أنواع واجهات برمجة التطبيقات

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

تعريف الكائنات

يصف هذا القسم تعريف كل عنصر في واجهة برمجة التطبيقات.

InitializeParams

نوع عنصر المَعلمة للدالة initialize

الموقع النوع الوصف
offerwallLanguageCode string | undefined رمز اللغة الذي يتم عرض Offerwall به، وفقًا لمعيار BCP 47

تعريفات التعداد

يصف هذا القسم كل تعريف من تعريفات التعداد في واجهة برمجة التطبيقات.

googlefc.offerwall.customchoice.InitializeResponseEnum

نوع تعداد الردّ للدالة initialize

عنصر التعداد الوصف
CUSTOM_CHOICE_DISABLED أوقِف خيار "الخيار المخصّص" في رسالة Offerwall. في حال إيقاف خيار الاختيار المخصّص، لن يتم عرض رسالة Offerwall إلا مع خيارات أخرى مؤهَّلة. وإذا لم تكن هناك خيارات أخرى مؤهَّلة، لن يتم عرض رسالة Offerwall على الصفحة مطلقًا.
ACCESS_GRANTED منح المستخدم إذن الوصول إلى الصفحة عند تحميلها لن يتم عرض Offerwall على الصفحة أبدًا إذا تم عرض هذا الردّ.
ACCESS_NOT_GRANTED لا تمنح المستخدم إذن الوصول إلى الصفحة عند تحميلها. تكون رسالة Offerwall مؤهَّلة للعرض على الصفحة إذا تم عرض هذه الاستجابة.