API ارائه دهنده کسب درآمد

نسخه: 1.0.0

معرفی

API مشتری ارائه‌دهنده کسب درآمد به شما امکان می‌دهد راه‌حل کسب درآمد خود را با حریم خصوصی و پیام‌رسانی در Ad Manager ادغام کنید. امروزه، این API فقط برای ناشران شرکت کننده در نسخه بتای بسته Offerwall در دسترس است.

برای ادغام راه حل کسب درآمد خود با Offerwall، این مراحل تنظیم انتخاب سفارشی را دنبال کنید. به طور خلاصه:

  • گزینه «انتخاب سفارشی» را برای Offerwall از برگه حریم خصوصی و پیام‌رسانی در Ad Manager فعال کنید.

  • جاوا اسکریپت سفارشی را در سایتی که Offerwall در آن منتشر شده است اضافه کنید. جزئیات پیاده سازی را می توان در بخش های زیر یافت.

  • این جاوا اسکریپت باید یک ارائه‌دهنده کسب درآمد سفارشی را همانطور که در زیر تعریف شده است نشان دهد و ارائه‌دهنده را با Privacy & Messaging در پنجره با کلید ثبت نام ثبت کند: 'publisherCustom' .

واژه نامه

مدت، اصطلاح تعریف
ارائه دهنده کسب درآمد یک شی جاوا اسکریپت بومی که راه حل کسب درآمد سفارشی شما را ارائه می دهد. به عنوان مثال، می توانید یک سرویس اشتراک، خدمات پرداخت خرد و موارد دیگر ارائه دهید. Offerwall از روش های ارائه دهنده شما برای کسب درآمد از محتوای شما با راه حل سفارشی شما استفاده می کند.
استحقاق پاداشی که توسط راه حل کسب درآمد شما برای انجام برخی اقدامات کسب درآمد به کاربران اعطا می شود. در محدوده این API، یک حق به کاربران اجازه می دهد بدون دیدن Offerwall به محتوای وب سایت شما دسترسی داشته باشند. شما تعداد بارگیری صفحه رایگان یا مدت زمان اعطا شده به کاربرانی را که انتخاب کسب درآمد سفارشی شما را انتخاب می کنند، تعیین می کنید.
پورتال کسب درآمد نقطه ورود به جریان کسب درآمد. پورتال ها جریان های جداگانه ای را که توسط راه حل کسب درآمد شما ارائه می شود، تعریف می کنند. به عنوان مثال، یک پورتال ممکن است برای "کسب درآمد" باشد، جایی که کاربر می تواند در سرویس شما مشترک شود. پورتال دیگری ممکن است برای "ورود به سیستم" باشد، جایی که کاربر می تواند برای دسترسی به اشتراک موجود وارد سیستم شود.
کلید ثبت نام شناسه ارائه‌دهنده کسب درآمد، که برای ثبت اجرای ارائه‌دهنده شما در Google Privacy & Messaging در زمان بارگذاری صفحه استفاده می‌شود.

نمونه پیاده سازی API

در اینجا نمونه‌ای از پیاده‌سازی است که ارائه‌دهنده کسب درآمد را تعریف می‌کند، آن را نمونه‌سازی می‌کند و آن را در Google Privacy & Messaging ثبت می‌کند.

// 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());

قطعه کد بالا یک پیاده سازی اسکلت است که شامل همه چیزهایی است که برای ادغام یک ارائه دهنده درآمدزایی با حریم خصوصی و پیام رسانی لازم است. توجه داشته باشید که برای هر تابع ارائه دهنده، کد نمونه اضافه شده است که شما مسئول جایگزینی با پیاده سازی خود هستید.

خلاصه روش

ارائه‌دهنده کسب درآمد شی‌ای است که با نمایش مجموعه‌ای از عملکردها، عملکرد کسب درآمد را در صفحات وب ارائه می‌کند. این توابع در ادامه بیشتر توضیح داده شده است.

روش خلاصه
مقداردهی اولیه ارائه دهنده کسب درآمد را به همراه هر گونه منابعی که برای انجام اقدامات کسب درآمد لازم است، راه اندازی کنید.
getUserEntitlementState وضعیت حق کاربر را در لحظه فراخوانی دریافت کنید.
کسب درآمد راه حل کسب درآمد سفارشی خود را در صفحه وب ارائه دهید. راه‌حل کسب درآمد شما می‌تواند به هر شکلی باشد، با برخی از نمونه‌های آن می‌توان به تبلیغ پاداش، گفتگوی سرویس اشتراک و موارد دیگر اشاره کرد.
از بین رفتن ارائه دهنده را به همراه هر منبع یا شغلی که پس از شروع اولیه در حال اجرا بودند، از بین ببرید. پس از تخریب، 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 >

وضعیت حق کاربر را در لحظه فراخوانی دریافت کنید. اگر کاربر حق داشته باشد Offerwall پنهان می شود زیرا کاربر باید دسترسی رایگان به وب سایت داشته باشد.

مثال:

  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 و ارائه دهنده را تضمین می کند.

Offerwall پارامتر پورتال کسب درآمد را تنظیم می کند تا مشخص کند به کدام پورتال می خواهد دسترسی داشته باشد. دو نوع پورتال موجود عبارتند از PORTAL_PRIMARY_ACCESS که اختیاری نیست و PORTAL_SIGN_IN که اختیاری است. در پاسخ به تابع مقداردهی اولیه ، می توانید مشخص کنید که آیا از پورتال اختیاری PORTAL_SIGN_IN پشتیبانی می کنید.

پس از حل کردن وعده تابع کسب درآمد، باید:

  • راه حل کسب درآمد ارائه شده خود را پنهان کنید.

  • برگردانید که آیا کاربر حق محتوای صفحه را دارد یا نه. این مشخص می کند که Offerwall همچنان نشان داده می شود یا پنهان است.

  • در صورت وجود، هرگونه داده اضافی در مورد تعامل کاربر مانند مبلغ پرداختی، نوع و ارزش حق، و تکرار کسب درآمد را برگردانید.

مثال:

  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();
  }

تعاریف را تایپ کنید

تعریف هر نوع داده در API بیشتر در زیر توضیح داده شده است.

تعاریف شی

این بخش تمام تعاریف شی در API را فهرست می کند.

InitializeParams

نوع پارامتر برای تابع مقداردهی اولیه .

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

نوع پاسخ برای تابع مقداردهی اولیه .

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;
}

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

نوع پارامتر برای تابع تخریب .

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

تعاریف Enum

این بخش تمام تعاریف enum در API را فهرست می کند.

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>

شی جاوا اسکریپت در سطح پنجره که برای ثبت ارائه دهندگان کسب درآمد استفاده می شود. ثبت شامل ارسال شی ارائه دهنده نمونه شما با کلید ثبت ثابت به رجیستری است که در زیر فضای نام پنجره قرار دارد: 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 2023/07/24 انتشار اولیه API ارائه دهنده کسب درآمد.