Эта страница переведена с помощью Cloud Translation API.

API поставщика монетизации

Версия: 1.0.0

Введение

API клиента поставщика монетизации позволяет вам интегрировать собственное решение для монетизации с функцией «Конфиденциальность и сообщения» в Менеджере рекламы .

Чтобы интегрировать собственное решение по монетизации с Offerwall, выполните следующие действия:

Включите опцию «Пользовательский выбор» для Offerwall на вкладке «Конфиденциальность и сообщения» в Менеджере объявлений.
Добавьте пользовательский JavaScript на сайт, на котором опубликован Offerwall. Подробности реализации можно найти в разделах ниже.
Этот JavaScript должен создать экземпляр пользовательского поставщика монетизации, как определено ниже, и зарегистрировать поставщика в разделе «Конфиденциальность и сообщения» в окне с регистрационным ключом : 'publisherCustom' .

Глоссарий

Срок	Определение
Поставщик монетизации	Собственный объект JavaScript, который предоставляет ваше индивидуальное решение для монетизации. Например, вы можете предоставить услугу подписки, услугу микроплатежей и т. д. Offerwall вызывает методы вашего провайдера для монетизации вашего контента с помощью вашего индивидуального решения.
Право	Вознаграждение, которое предоставляется пользователям вашим решением по монетизации за выполнение некоторых действий по монетизации. В рамках этого API право предоставляет пользователям доступ к контенту вашего веб-сайта без просмотра Offerwall. Вы определяете количество бесплатных загрузок страниц или продолжительность времени, предоставляемого пользователям, которые выбирают ваш индивидуальный вариант монетизации.
Портал монетизации	Точка входа в поток монетизации. Порталы определяют отдельные потоки, предлагаемые вашим решением монетизации. Например, один портал может быть для «монетизации», где пользователь может подписаться на ваш сервис. Другой портал может быть для «входа», где пользователь может войти, чтобы получить доступ к существующей подписке.
Регистрационный ключ	Идентификатор поставщика монетизации, который используется для регистрации реализации вашего поставщика в Google Privacy & Messaging во время загрузки страницы.

Пример реализации API

Ниже приведен пример рабочей реализации, которая определяет поставщика монетизации, создает его экземпляр и регистрирует его в Google Privacy & Messaging.

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

Фрагмент кода выше — это скелетная реализация, которая включает все, что требуется для интеграции поставщика монетизации с Privacy & messagesing. Обратите внимание, что для каждой функции поставщика был добавлен пример кода, который вы несете ответственность за замену на собственную реализацию.

Краткое описание метода

Поставщик монетизации — это объект, который обеспечивает функциональность монетизации на веб-страницах, предоставляя базовый набор функций. Эти функции более подробно описаны ниже.

Метод	Краткое содержание
инициализировать	Инициализируйте поставщика монетизации, а также все ресурсы, необходимые для выполнения действий по монетизации.
получитьUserEntitlementState	Получить состояние прав пользователя на момент вызова.
монетизировать	Представьте свое индивидуальное решение по монетизации на веб-странице. Ваше решение по монетизации может иметь любую форму, например, вознаграждение за рекламу, диалоговое окно подписки и многое другое.
разрушать	Уничтожить поставщика вместе со всеми ресурсами или заданиями, которые были запущены при инициализации. После уничтожения 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);
  }

получитьUserEntitlementState

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;
  // 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`

Тип параметра для функции уничтожения .

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

Определения перечислений

В этом разделе перечислены все определения перечислений в 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>

Объект JavaScript уровня окна, используемый для регистрации поставщиков монетизации. Регистрация включает передачу вашего экземпляра объекта поставщика, зашифрованного статическим ключом регистрации, в реестр, который находится в пространстве имен окна: 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	Первоначальный выпуск API провайдера монетизации.

API поставщика монетизации Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Введение

Глоссарий

Пример реализации API

Краткое описание метода

Определения методов

инициализировать

получитьUserEntitlementState

монетизировать

разрушать

Определения типов

Определения объектов

Определения перечислений

Регистрация поставщика

История версий

API поставщика монетизации