API Monetization Provider

Versione: 1.0.0

Introduzione

L'API client del fornitore di servizi di monetizzazione ti consente di integrare la tua soluzione di monetizzazione con Privacy e messaggi in Ad Manager.

Per integrare la tua soluzione di monetizzazione con l'Offerwall, segui questi passaggi:

  • Attiva l'opzione "Scelta personalizzata" per l'Offerwall dalla scheda Privacy e messaggi di Ad Manager.

  • Aggiungi codice JavaScript personalizzato sul sito su cui è pubblicata la Offerwall. I dettagli sull'implementazione sono disponibili nelle sezioni seguenti.

  • Questo codice JavaScript deve creare un'istanza di un fornitore di servizi di monetizzazione personalizzato come definito di seguito e registrarlo in Privacy e messaggistica nella finestra con la chiave di registrazione: 'publisherCustom'.

Glossario

Termine Definizione
Fornitore di servizi di monetizzazione Un oggetto JavaScript nativo che fornisce la tua soluzione di monetizzazione personalizzata. Ad esempio, potresti fornire un servizio in abbonamento, un servizio di micropagamenti e altro ancora. La Offerwall richiama i metodi del fornitore per monetizzare i tuoi contenuti con la tua soluzione personalizzata.
Diritto Un premio concesso agli utenti dalla tua soluzione di monetizzazione per aver completato un'azione di monetizzazione. Nell'ambito di questa API, un diritto consente agli utenti di accedere ai contenuti del tuo sito web senza visualizzare la Offerwall. Puoi determinare il numero di caricamenti di pagine senza costi o la durata del tempo concessa agli utenti che selezionano la tua scelta di monetizzazione personalizzata.
Portale di monetizzazione Un punto di accesso a un flusso di monetizzazione. I portali definiscono i flussi separati offerti dalla tua soluzione di monetizzazione. Ad esempio, un portale potrebbe essere dedicato alla "monetizzazione", in cui l'utente può abbonarsi al tuo servizio. Un altro portale potrebbe essere "Accedi", dove l'utente può accedere per accedere a un abbonamento esistente.
Chiave di registrazione L'identificatore di un fornitore di servizi di monetizzazione, utilizzato per registrare l'implementazione del fornitore in Privacy e messaggi di Google al momento del caricamento della pagina.

Implementazione dell'API di esempio

Ecco un esempio di implementazione funzionante che definisce un fornitore di servizi di monetizzazione, lo esegue in un'istanza e lo registra in Privacy e messaggi di 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>

Lo snippet di codice riportato sopra è un'implementazione di base che include tutto ciò che è necessario per integrare un fornitore di servizi di monetizzazione con Privacy e messaggi. Tieni presente che per ogni funzione del provider è stato aggiunto un codice di esempio che è tua responsabilità sostituire con la tua implementazione.

Riepilogo del metodo

Un fornitore di servizi di monetizzazione è un oggetto che fornisce funzionalità di monetizzazione sulle pagine web esponendo un insieme di funzioni di base. Queste funzioni sono descritte più dettagliatamente di seguito.

Metodo Riepilogo
inizializzare Inizializza il fornitore di servizi di monetizzazione, insieme a eventuali risorse necessarie per eseguire azioni di monetizzazione.
getUserEntitlementState Recupera lo stato dei diritti dell'utente al momento dell'invocazione.
monetize Esegui il rendering della soluzione di monetizzazione personalizzata nella pagina web. La soluzione di monetizzazione può assumere qualsiasi forma, ad esempio un annuncio con premio, una finestra di dialogo del servizio in abbonamento e altro ancora.
destroy Distruggi il provider, insieme a eventuali risorse o job in esecuzione all'inizializzazione. Al momento della distruzione, Offerwall non invoca più metodi del fornitore.

Definizioni dei metodi

La definizione di ciascun metodo del fornitore di servizi di monetizzazione è descritta di seguito.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Inizializza il fornitore di servizi di monetizzazione. Una volta inizializzato, il provider dovrebbe essere pronto a rispondere a qualsiasi altra funzione del provider. È garantito che questa funzione verrà invocata prima di qualsiasi altra funzione del provider e si prevede che venga invocata al massimo una volta in un determinato caricamento della pagina.

Esempio:

  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>

Recupera lo stato dei diritti dell'utente al momento dell'invocazione. La Offerwall viene nascosta se l'utente ha diritto, in quanto dovrebbe ricevere accesso senza costi al sito web.

Esempio:

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

monetizza

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Esegui il rendering della soluzione di monetizzazione e gestisci le azioni di monetizzazione dell'utente. La monetizzazione può assumere qualsiasi forma, che si tratti di un annuncio con premio, di un servizio in abbonamento e altro ancora. Una volta invocato questo metodo dalla Offerwall, quest'ultima viene nascosta finché la promessa non viene risolta. Pertanto, è responsabilità del fornitore limitare l'accesso ai contenuti della pagina fino alla risoluzione della promessa. Una volta risolta la promessa, il fornitore deve anche assicurarsi di non essere più visibile sulla pagina web.

Ti consigliamo vivamente di utilizzare il codice lingua e gli stili suggeriti forniti in InitializeParams all'interno della tua soluzione di monetizzazione. In questo modo, l'esperienza visiva tra la Offerwall e il fornitore è fluida.

La Offerwall imposta il parametro del portale di monetizzazione per indicare a quale portale vuole accedere. I due tipi di portali disponibili sono PORTAL_PRIMARY_ACCESS, che non è facoltativo, e PORTAL_SIGN_IN, che è facoltativo. Puoi indicare se supporti il portale facoltativo PORTAL_SIGN_IN nella risposta alla funzione initialize.

Dopo aver risolto la promessa della funzione di monetizzazione, devi:

  • Nascondere la soluzione di monetizzazione visualizzata.

  • Restituisce se l'utente ha diritto o meno ai contenuti della pagina. Questo determina se la Offerwall continua a essere visualizzata o viene nascosta.

  • Restituire eventuali dati aggiuntivi sull'interazione dell'utente, se applicabili, come l'importo pagato, il tipo e il valore del diritto e la frequenza della monetizzazione.

Esempio:

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

eliminare

destroy(destroyParams:DestroyParams): void

Elimina il provider. È garantito che questa funzione venga invocata per ultima nel ciclo di vita del fornitore e dovresti aspettarti che venga invocata al massimo una volta per un determinato caricamento della pagina.

Esempio:

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

Definizioni dei tipi

La definizione di ogni tipo di dati nell'API è descritta più dettagliatamente di seguito.

Definizioni dell'oggetto

Questa sezione elenca tutte le definizioni di oggetti nell'API.

InitializeParams

Il tipo di parametro per la funzione 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

Il tipo per definire gli stili.

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

InitializeResponse

Il tipo di risposta per la funzione 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

Il tipo di parametro per la funzione 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

Il tipo di risposta per la funzione 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

Il tipo per definire un importo in una valuta specifica. Consulta la definizione originale di 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

Il tipo di parametro per la funzione destroy.

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

Definizioni di enum

Questa sezione elenca tutte le definizioni di enum nell'API.

googlefc.monetization.UserEntitlementStateEnum

L'enumerazione del diritto indica che un utente può essere registrato a un fornitore di servizi di monetizzazione.

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

Enumerazione dei diversi portali di monetizzazione o punti di accesso alla monetizzazione che un fornitore può supportare. Per saperne di più sui portali di monetizzazione, consulta il glossario.

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

Enumerazione dei diversi tipi di diritti che un fornitore di servizi di monetizzazione può concedere a un utente.

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

Elenco dei motivi per cui un fornitore di servizi di monetizzazione può essere eliminato.

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

Enumerazione delle diverse cadenze di ripetizione della monetizzazione che possono essere avviate in base ad alcune azioni dell'utente.

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

Registrazione del fornitore

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

L'oggetto JavaScript a livello di finestra utilizzato per registrare i fornitori di servizi di monetizzazione. La registrazione include il passaggio dell'oggetto provider istanziato con chiave tramite una chiave di registrazione statica a un registry che si trova nel namespace della finestra: 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());

Cronologia delle versioni

Versione Data di uscita Riepilogo
1.0.0 24/07/2023 Versione iniziale dell'API Monetization Provider.