API Monetization Provider

Versão: 1.0.0

Introdução

A API cliente do provedor de monetização permite integrar sua própria solução de monetização com a página Privacidade e mensagens no Ad Manager.

Para integrar sua própria solução de monetização com o Offerwall, siga estas etapas:

  • Ative a opção "Opção personalizada" para o Offerwall na guia "Privacidade e mensagens" do Ad Manager.

  • Adicione um JavaScript personalizado no site em que o Offerwall é publicado. Confira os detalhes da implementação nas seções abaixo.

  • Esse JavaScript precisa instanciar um provedor de monetização personalizado, conforme definido abaixo, e registrar o provedor com a API Privacy & Messaging na janela com a chave de registro: 'publisherCustom'.

Glossário

Termo Definição
Provedor de monetização Um objeto JavaScript nativo que oferece sua solução de monetização personalizada. Por exemplo, você pode fornecer um serviço de assinatura, de micropagamentos e muito mais. O Offerwall invoca os métodos do provedor para gerar receita com seu conteúdo usando a solução personalizada.
Direito Uma recompensa concedida aos usuários pela sua solução de monetização por concluir uma ação de monetização. No escopo desta API, um direito concede aos usuários acesso ao conteúdo do seu site sem mostrar o Offerwall. Você determina o número de carregamentos de página sem custo financeiro ou a duração do tempo concedido aos usuários que selecionam sua escolha de monetização personalizada.
Portal de monetização Um ponto de entrada em um fluxo de monetização. Os portais definem os fluxos separados oferecidos pela sua solução de monetização. Por exemplo, um portal pode ser para "monetização", em que o usuário pode se inscrever no serviço. Outro portal pode ser para "fazer login", em que o usuário pode fazer login para acessar uma assinatura existente.
Chave de registro Um identificador do provedor de monetização, que é usado para registrar sua implementação do provedor com a ferramenta Privacidade e mensagens do Google no momento do carregamento da página.

Exemplo de implementação de API

Confira um exemplo de implementação que define um provedor de monetização, o instancia e o registra com a ferramenta Privacidade e mensagens do 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>

O snippet de código acima é uma implementação básica que inclui tudo o que é necessário para integrar um provedor de monetização com a seção "Privacidade e mensagens". Para cada função do provedor, foi adicionado um código de exemplo que você precisa substituir pela sua própria implementação.

Resumo do método

Um provedor de monetização é um objeto que oferece a funcionalidade de monetização em páginas da Web expondo um conjunto principal de funções. Essas funções são descritas abaixo.

Método Resumo
inicializar Inicialize o provedor de monetização e todos os recursos necessários para realizar ações de monetização.
getUserEntitlementState Receba o estado de direito do usuário no momento da invocação.
Monetização Renderize sua solução de monetização personalizada na página da Web. Sua solução de monetização pode ter qualquer formato, como um anúncio premiado, uma caixa de diálogo de serviço de assinatura e muito mais.
destroy Destrói o provedor e todos os recursos ou jobs que estavam em execução durante a inicialização. Após a destruição, o Offerwall não invoca mais nenhum método do provedor.

Definições de método

A definição de cada método do provedor de monetização é descrita abaixo.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Inicialize o provedor de monetização. Depois de inicializado, o provedor estará pronto para responder a qualquer outra função do provedor. Essa função é garantida para ser invocada antes de qualquer outra função do provedor e pode ser invocada no máximo uma vez em uma determinada carga de página.

Exemplo:

  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>

Receba o estado de direito do usuário no momento da invocação. O Offerwall fica oculto se o usuário tiver direito, já que ele vai receber acesso sem custo financeiro ao site.

Exemplo:

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

gerar receita

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Renderize sua solução de monetização e processe as ações de monetização do usuário. A monetização pode ter qualquer formato, como um anúncio premiado, serviço de assinatura e muito mais. Depois que esse método é invocado pelo Offerwall, ele fica oculto até que a promessa seja resolvida. Portanto, é responsabilidade do provedor restringir o conteúdo da página até que a promessa seja resolvida. Depois que a promessa for resolvida, o provedor também não poderá mais ser mostrado na página da Web.

É altamente recomendável usar o código de idioma e os estilos fornecidos em InitializeParams na sua solução de monetização. Isso garante uma experiência visual perfeita entre o Offerwall e o provedor.

O Offerwall define o parâmetro do portal de monetização para indicar qual portal ele quer acessar. Os dois tipos de portal disponíveis são PORTAL_PRIMARY_ACCESS, que não é opcional, e PORTAL_SIGN_IN, que é opcional. É possível indicar se você oferece suporte ao portal opcional PORTAL_SIGN_IN na resposta à função initialize.

Ao resolver a promessa da função de monetização, você precisa:

  • Ocultar a solução de monetização renderizada.

  • Retorna se o usuário tem ou não direito ao conteúdo da página. Isso determina se o Offerwall continua sendo mostrado ou fica oculto.

  • Retorna outros dados sobre a interação do usuário, se aplicável, como o valor pago, o tipo e o valor do direito e a recorrência da monetização.

Exemplo:

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

destruir

destroy(destroyParams:DestroyParams): void

Destrua o provedor. Essa função será invocada por último no ciclo de vida do provedor, e você deve esperar que ela seja invocada no máximo uma vez em um determinado carregamento de página.

Exemplo:

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

Definições de tipo

A definição de cada tipo de dados na API é descrita abaixo.

Definições dos objetos

Esta seção lista todas as definições de objetos na API.

InitializeParams

O tipo de parâmetro da função 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

O tipo para definir estilos.

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

InitializeResponse

O tipo de resposta da função 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

O tipo de parâmetro para a função monetize.

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

O tipo de resposta da função monetize.

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

O tipo para definir um valor em uma moeda específica. Consulte a definição original 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

O tipo de parâmetro da função destroy.

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

Definições de tipo enumerado

Esta seção lista todas as definições de tipo enumerado na API.

googlefc.monetization.UserEntitlementStateEnum

A enumeração do direito de acesso indica que um usuário pode ter um provedor de monetização.

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

Enumeração dos diferentes portais de monetização ou pontos de entrada de monetização que um provedor pode oferecer suporte. Consulte o glossário para saber mais sobre os portais de monetização.

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

Enumeração dos diferentes tipos de direito que um provedor de monetização pode conceder a um usuário.

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

Enumeração de motivos pelos quais um provedor de monetização pode ser destruído.

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

Enumeração das diferentes cadências de recorrência de monetização que podem ser iniciadas após alguma ação do usuário.

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

Registro do provedor

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

O objeto JavaScript no nível da janela usado para registrar provedores de monetização. O registro inclui a transmissão do objeto de provedor instanciado com uma chave de registro estática para um registro que fica no namespace da janela: 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());

Histórico de versões

Versão Data do lançamento Resumo
1.0.0 24/07/2023 Versão inicial da API Monetization Provider.