Monetization Provider API

الإصدار: 1.0.0

مقدمة

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

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

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

  • أضِف JavaScript مخصّصًا على الموقع الإلكتروني الذي تم نشر Offerwall عليه. يمكن العثور على تفاصيل التنفيذ في الأقسام أدناه.

  • من المفترض أن تنشئ لغة JavaScript هذه مثيلًا لموفّر تحقيق الربح المخصّص كما هو محدّد أدناه وأن تسجّل الموفّر في قسم "الخصوصية والمراسلة" في النافذة باستخدام مفتاح التسجيل: 'publisherCustom'.

مسرد المصطلحات

المصطلح التعريف
موفّر خدمة تحقيق الربح كائن JavaScript أصلي يقدّم حلّك المخصّص لتحقيق الربح على سبيل المثال، يمكنك تقديم خدمة متوفّرة من خلال اشتراك، وخدمة دفعات صغيرة، وغير ذلك. تستدعي رسائل Offerwall methods مقدّم الخدمة لتحقيق الربح من المحتوى باستخدام الحلّ المخصّص.
الاستحقاق مكافأة يمنحها حلّ تحقيق الربح للمستخدمين مقابل إكمال بعض إجراءات تحقيق الربح في نطاق واجهة برمجة التطبيقات هذه، يمنحك الإذن للمستخدمين بالوصول إلى محتوى موقعك الإلكتروني بدون رؤية جدار العروض. يمكنك تحديد عدد مرات تحميل الصفحة مجانًا أو المدة الزمنية التي يتم منحها للمستخدمين الذين يختارون خيار تحقيق الربح المخصّص الذي تقدّمه.
بوابة تحقيق الربح نقطة دخول إلى مسار تحقيق الربح تحدّد البوابات عمليات المعالجة المغيّرة التي يوفّرها حلّ تحقيق الربح. على سبيل المثال، قد تكون إحدى البوابات مخصّصة "تحقيق الربح"، حيث يمكن للمستخدم الاشتراك في خدمتك. قد تكون هناك بوابة أخرى مخصّصة لـ "تسجيل الدخول"، حيث يمكن للمستخدم تسجيل الدخول للوصول إلى اشتراك حالي.
مفتاح التسجيل معرّف مقدّم تحقيق الربح، والذي يُستخدَم لتسجيل عملية تنفيذ مقدّم الخدمة في "الخصوصية والمراسلة " من Google في وقت loading الصفحة

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

في ما يلي مثال على عملية تنفيذ ناجحة تحدّد موفّر ميزة تحقيق الربح وينشئ مثيلًا له ويُسجّله في "الخصوصية والمراسلة" من Google.

<script>
  // This class defines a monetization provider by implementing four core functions that every provider
  // must support: initialize, getUserEntitlementState, monetize, and destroy.
  class CustomMonetizationProvider {
    userEntitlementState;

    async initialize(initializeParams) {
      // Replace this function's code with your implementation of the initialize function.
      this.userEntitlementState = googlefc.monetization.UserEntitlementStateEnum.ENTITLED_NO;
      return {initializeSuccess: true, apiVersionInUse: "1.0.0", signInMonetizationPortalSupported: false};
    }

    async getUserEntitlementState() {
      // Replace this function's code with your implementation of the getUserEntitlementState function.
      return this.userEntitlementState;
    }

    async monetize(monetizeParams) {
      // Replace this function's code with your implementation of the monetize function.
      if (monetizeParams.monetizationPortal == googlefc.monetization.MonetizationPortalEnum.PORTAL_PRIMARY_ACCESS) {
        return await this.showSubscriptionPrompt();
      } else {
        console.log('Unsupported monetization portal.');
      }
    }

    async destroy(destructionParams) {
      // Replace this function's code with your implementation of the destroy function.
      console.log('Custom provider is no longer initialized.');
    }

    // ==== The helper functions in this section are only used for this demo, and should be omitted from your actual implementation. ===
    async showSubscriptionPrompt() {
      return new Promise(resolve => {
        const sharedStyles = 'border: 2px solid #6b6e7666; border-radius: 8px; padding: 10px; background: white;';
        const modalStyles =  'width: 500px; z-index: 100; top: 50%; left: 50%; position: absolute; transform: translate(-50%, -50%);';
        const overlayStyles = 'height: 100%; width: 100%; background: black; opacity: 0.6; z-index: 99; position: absolute; top: 0;';

        const modal = this.createElement("div", modalStyles + sharedStyles);
        const overlay = this.createElement("div", overlayStyles);
        const header = this.createElement("h1", 'text-align: center; color: black;', "Subscribe for access.");
        const subscribeButton = this.createElement("button", sharedStyles + 'color: #5499C7; margin-left: 40%;', "Subscribe");
        const backButton = this.createElement("button", sharedStyles + 'color: #5499C7;', "Back");

        this.exitSubscriptionPromptOnButtonClick(subscribeButton, resolve, googlefc.monetization.UserEntitlementStateEnum.ENTITLED_YES, modal, overlay);
        this.exitSubscriptionPromptOnButtonClick(backButton, resolve, googlefc.monetization.UserEntitlementStateEnum.ENTITLED_NO,modal, overlay);

        modal.append(backButton, header, subscribeButton);
        document.body.append(overlay, modal);
      });
    }

    createElement(tag, styles = '', textContent ='') {
      const element = document.createElement(tag);
      element.style.cssText = styles;
      element.textContent = textContent;
      return element;
    }

    exitSubscriptionPromptOnButtonClick(button, resolve, userEntitlementStateEnum, modal, overlay) {
      button.addEventListener("click", () => {
        document.body.removeChild(modal);
        document.body.removeChild(overlay);
        this.userEntitlementState = userEntitlementStateEnum;
        resolve({userEntitlementState: userEntitlementStateEnum});
      });
    }
    // =============================================================================================================================
  };

  // Important: code to register a custom monetization provider with Google Privacy & messaging.
  window.googlefc = window.googlefc || {};
  window.googlefc.monetization = window.googlefc.monetization || {};
  window.googlefc.monetization.providerRegistry =
    window.googlefc.monetization.providerRegistry || new Map();

  window.googlefc.monetization.providerRegistry.set(
    'publisherCustom', new CustomMonetizationProvider());
</script>

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

ملخّص الطريقة

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

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

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

في ما يلي تعريف كل طريقة من طرق موفّري تحقيق الربح.

إعداد

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

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

مثال:

  async initialize(initializeParams: InitializeParams): Promise<InitializeResponse> {
    const isInitializationSuccessful = await this.initializeMyProvider(initializeParams);
    const initializeResponse = {initializeSuccess: isInitializationSuccessful,
                                                   apiVersionInUse: "1.0.0",
                                                   signInMonetizationPortalSupported: true};
    resolve(initializeResponse);
  }

getUserEntitlementState

getUserEntitlementState(): Promise<UserEntitlementStateEnum>

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

مثال:

  async getUserEntitlementState(): Promise<googlefc.monetization.UserEntitlementStateEnum> {
      resolve(this.isUserLoggedIn() ? this.isUserEntitledOnThisPage()
        : googlefc.monetization.UserEntitlementStateEnum.ENTITLED_NO);
  }

تحقيق الربح

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

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

ننصحك بشدة باستخدام رمز اللغة والأنماط المقترَحة المقدَّمة في InitializeParams ضمن حلّ تحقيق الربح. ويضمن ذلك تجربة مرئية سلسة بين الحائط الإعلاني ومورّد المحتوى.

تضبط ميزة Offerwall مَعلمة بوابة تحقيق الربح للإشارة إلى البوابة التي تريد الوصول إليها. يتوفّر نوعان من البوابات: PORTAL_PRIMARY_ACCESS غير اختياري، و PORTAL_SIGN_IN اختياري. يمكنك الإشارة إلى ما إذا كان تطبيقك يتوافق مع البوابة الاختيارية PORTAL_SIGN_IN في الردّ على الدالة initialize.

بعد حلّ المشكلة المتعلّقة بوظيفة تحقيق الربح، عليك تنفيذ ما يلي:

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

  • عرض ما إذا كان المستخدم مؤهلاً للوصول إلى محتوى الصفحة أم لا يحدِّد ذلك ما إذا كان سيتم مواصلة عرض جدار العروض الترويجية أو إخفاؤه.

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

مثال:

  async monetize(monetizeParams: MonetizeParams): Promise<MonetizeResponse> {
    const result;
    if (monetizeParams.monetizationPortal == googlefc.monetization.MonetizationPortalEnum.PORTAL_PRIMARY_ACCESS) {
      result = await this.showMyBuyFlow();
    } else if (monetizeParams.monetizationPortal == googlefc.monetization.MonetizationPortalEnum.PORTAL_SIGN_IN) {
      result = await this.showMySignInFlow();
    }

    if (!result.monetized) {
      resolve({userEntitlementState: googlefc.monetization.UserEntitlementStateEnum.ENTITLED_NO});
    }

    const monetizeResponse = {
      userEntitlementState: googlefc.monetization.UserEntitlementStateEnum.ENTITLED_YES,
      newlyGrantedUserEntitlementType: googlefc.monetization.EntitlementTypeEnum.TYPE_PAGEVIEW_COUNT,
      newlyGrantedUserEntitlementValue: 4,
      newlyPaidAmountByUser: {currencyCode: "USD", units: 5, nanos: 0},
      // This monetization event does not auto-recur, so leaving property
      // recurrenceOfNewMonetizationEvent undefined.
    }
    resolve(monetizeResponse);
  }

إتلافه

destroy(destroyParams:DestroyParams): void

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

مثال:

  destroy(destroyParams: DestroyParams): void {
    this.recordDestroyReason(destroyParams.destroyReason);
    this.destroyAllOfMyResourcesOnPage();
  }

تعريفات الأنواع

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

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

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

InitializeParams

نوع المَعلمة لدالة initialize.

interface InitializeParams {
  // The loaded monetization provider API version. i.e. "1.0.0"
  currentApiVersion: string;
  // The language code suggested for the provider to use, as defined by BCP 47.
  suggestedLanguageCode?: string;
  // The styles suggested for the provider to use.
  suggestedStyles?: Styles;
  // The publisher's logo url.
  publisherLogoUrl?: string;
}

Styles

نوع تحديد الأنماط

interface Styles {
  // The primary color of the Offerwall.
  primaryColor?: string;
  // The background color of the Offerwall.
  backgroundColor?: string;
}

InitializeResponse

نوع الاستجابة لدالة initialize.

interface InitializeResponse {
  // Whether or not initialization was successful. If initialization is
  // unsuccessful, the Offerwall does not proceed to call other provider methods
  // except for destroy.
  initializeSuccess: boolean;
  // The monetization provider API version that the provider is using. If the
  // indicated major version is not equal to the major version of the API
  // currently on the page, provider execution is halted.
  apiVersionInUse: string;
  // Whether or not the optional sign-in monetization portal is supported. If
  // you indicate that it is supported, the Offerwall renders a sign-in link
  // that will invoke your sign-in portal upon user click.
  signInMonetizationPortalSupported: boolean;
  // Whether or not the provider is disabled. If disabled, the Offerwall can
  // only render with other eligible choices; if no other choices are eligible,
  // the Offerwall won't ever render on the page.
  isProviderDisabled?: boolean;
}

MonetizeParams

نوع المَعلمة لدالة تحقيق الربح.

interface MonetizeParams {
  // The monetization portal that the Offerwall wants to invoke. You can
  // indicate whether you support any optional portals in your
  // InitializeResponse; the only portal that isn't optional is
  // MonetizationPortalEnum.PORTAL_PRIMARY_ACCESS. The Offerwall provides the
  // portal enum for the flow requested by the user.
  monetizationPortal: googlefc.monetization.MonetizationPortalEnum;
}

MonetizeResponse

نوع الاستجابة لدالة تحقيق الربح

interface MonetizeResponse {
  // The user's current entitlement state.
  userEntitlementState: googlefc.monetization.UserEntitlementStateEnum;
  // The user's granted entitlement type, only populated if an entitlement was
  // granted within the scope of the current MonetizationProvider.monetize
  // invocation.
  newlyGrantedUserEntitlementType?: googlefc.monetization.EntitlementTypeEnum;
  // The user's granted entitlement value, only populated if an entitlement was
  // granted within the scope of the current MonetizationProvider.monetize
  // invocation.
  newlyGrantedUserEntitlementValue?: number;
  // The amount paid by the user, only populated if a payment occurred within
  // the scope of the current MonetizationProvider.monetize invocation.
  newlyPaidAmountByUser?: Money;
  // The recurrence of the monetization event, populated only if the
  // monetization event occurred within the scope of the current
  // MonetizationProvider.monetize invocation & the monetization event is
  // expected to auto-recur without further action from the user (e.g.
  // registering for a monthly subscription)
  recurrenceOfNewMonetizationEvent?: googlefc.monetization.MonetizationRecurrenceEnum;
}

Money

نوع تحديد مبلغ مالي بعملة معيّنة. اطّلِع على التعريف الأصلي لملف money.proto.

interface Money {
  // The three-letter currency code defined in ISO 4217.
  currencyCode: string;
  // The whole units of the amount.
  // For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
  units?: number;
  // Number of nano (10^-9) units of the amount.
  // The value must be between -999,999,999 and +999,999,999 inclusive.
  // If `units` is positive, `nanos` must be positive or zero.
  // If `units` is zero, `nanos` can be positive, zero, or negative.
  // If `units` is negative, `nanos` must be negative or zero.
  // For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
  nanos?: number;
}

DestroyParams

نوع المَعلمة لدالة destroy.

interface DestroyParams {
  // The reason for destroying the provider.
  destroyReason: googlefc.monetization.DestroyReasonEnum;
}

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

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

googlefc.monetization.UserEntitlementStateEnum

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

googlefc.monetization.UserEntitlementStateEnum {
  ENTITLED_UNKNOWN = 0,
  // The user is currently entitled to access page content.
  ENTITLED_YES = 1,
  // The user is not currently entitled to access page content.
  ENTITLED_NO = 2,
}

googlefc.monetization.MonetizationPortalEnum

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

googlefc.monetization.MonetizationPortalEnum {
  PORTAL_UNKNOWN = 0,
  // The primary access portal represents a provider's main entry point into a
  // monetization flow, and must always be supported.
  PORTAL_PRIMARY_ACCESS = 1,
  // The sign in portal represents a provider's monetization entry point that
  // usually begins with the user performing some sign-in or registration
  // action. Provider support for this monetization portal type is optional.
  PORTAL_SIGN_IN = 2,
}

googlefc.monetization.EntitlementTypeEnum

قائمة بأنواع الأذونات المختلفة التي يمكن لموفّر تحقيق الربح منح المستخدمين

googlefc.monetization.EntitlementTypeEnum {
  TYPE_UNKNOWN = 0,
  // This type is used if the user is awarded a positive integer value of
  // Offerwall-free pageviews.
  TYPE_PAGEVIEW_COUNT = 1,
  // This type is used if the user is awarded a positive integer value of
  // seconds (duration) in which they can access Offerwall-free page content any
  // number of times.
  TYPE_DURATION_SECONDS = 2,
}

googlefc.monetization.DestroyReasonEnum

قائمة بأسباب إلغاء اعتماد مزوّد خدمة تحقيق الربح

googlefc.monetization.DestroyReasonEnum {
  REASON_UNKNOWN = 0,
  // The Offerwall no longer needs to invoke the monetization provider on the
  // pageview.
  REASON_CALLER_FINISHED = 1,
  // The Offerwall encountered an erroneous state with the monetization provider
  // in the midst of the provider's lifecycle.
  REASON_ERROR_STATE = 2,
  // The API version that the monetization provider is currently using is no
  // longer supported.
  REASON_UNSUPPORTED_API_VERSION = 3,
}

googlefc.monetization.MonetizationRecurrenceEnum

قائمة بمعدلات تكرار تحقيق الربح المختلفة التي يمكن بدؤها عند تنفيذ أحد إجراءات المستخدمين

googlefc.monetization.MonetizationRecurrenceEnum {
  MONETIZATION_RECURRENCE_UNKNOWN = 0,
  MONETIZATION_RECURRENCE_WEEKLY = 1,
  MONETIZATION_RECURRENCE_MONTHLY = 2,
  MONETIZATION_RECURRENCE_ANNUALLY = 3,
}

تسجيل مقدّم الخدمة

googlefc.monetization.providerRegistry?: Map<string, Object>

عنصر JavaScript على مستوى النافذة المستخدَم لتسجيل مزوّدي تحقيق الربح يتضمّن التسجيل تمرير عنصر موفِّر تم إنشاؤه باستخدام مفتاح تسجيل static إلى سجلّ يقع ضمن مساحة أسماء النافذة: window.googlefc.monetization

// Register a custom monetization provider with Google Privacy & messaging.
window.googlefc = window.googlefc || {};
window.googlefc.monetization = window.googlefc.monetization || {};
window.googlefc.monetization.providerRegistry =
                            window.googlefc.monetization.providerRegistry || new Map();

window.googlefc.monetization.providerRegistry.set(
                            'publisherCustom', new CustomMonetizationProvider());

تاريخ الإصدار

الإصدار تاريخ الإصدار ملخّص
1.0.0 ‎24/07/2023 الإصدار الأولي من واجهة برمجة التطبيقات لمقدّمي خدمة تحقيق الربح