Monetization Provider API

Version: 1.0.0

Einführung

Mit der Client API des Monetarisierungsanbieters können Sie Ihre eigene Monetarisierungslösung in Datenschutz und Mitteilungen in Ad Manager einbinden.

So integrieren Sie Ihre eigene Monetarisierungslösung in die Offerwall:

  • Aktivieren Sie die Option „Benutzerdefinierte Auswahl“ für die Offerwall auf dem Tab „Datenschutz und Mitteilungen“ in Ad Manager.

  • Fügen Sie benutzerdefiniertes JavaScript auf der Website hinzu, auf der die Offerwall veröffentlicht wird. Details zur Implementierung finden Sie in den folgenden Abschnitten.

  • Dieses JavaScript sollte einen benutzerdefinierten Monetarisierungsanbieter wie unten definiert instanziieren und den Anbieter im Fenster mit dem Registrierungsschlüssel 'publisherCustom' bei „Datenschutz und Mitteilungen“ registrieren.

Glossar

Begriff Definition
Monetarisierungsanbieter Ein natives JavaScript-Objekt, das deine benutzerdefinierte Monetarisierungslösung bereitstellt. Sie können beispielsweise einen Abodienst oder einen Mikrozahlungsdienst anbieten. Die Offerwall ruft die Methoden Ihres Anbieters auf, um Ihre Inhalte mit Ihrer benutzerdefinierten Lösung zu monetarisieren.
Berechtigung Eine Prämie, die Nutzern über Ihre Monetarisierungslösung für die Durchführung einer Monetarisierungsaktion gewährt wird. Im Rahmen dieser API gewährt eine Berechtigung Nutzern Zugriff auf die Inhalte Ihrer Website, ohne dass die Offerwall angezeigt wird. Sie legen die Anzahl der kostenlosen Seitenladevorgänge oder die Dauer fest, die Nutzern gewährt wird, die Ihre benutzerdefinierte Monetarisierungsoption auswählen.
Monetarisierungsportal Ein Einstiegspunkt in einen Monetarisierungsablauf. Portale definieren die einzelnen Abläufe, die von Ihrer Monetarisierungslösung angeboten werden. Ein Portal kann beispielsweise für die Monetarisierung gedacht sein, bei der Nutzer Ihren Dienst abonnieren können. Ein anderes Portal kann für die Anmeldung dienen, über die sich der Nutzer anmelden kann, um auf ein bestehendes Abo zuzugreifen.
Registrierungsschlüssel Die Kennung eines Monetarisierungsanbieters, mit der Ihre Anbieterimplementierung beim Laden der Seite bei „Datenschutz und Mitteilungen“ von Google registriert wird.

Beispiel für eine API-Implementierung

Hier ist ein Beispiel für eine funktionierende Implementierung, bei der ein Monetarisierungsanbieter definiert, instanziiert und bei Google unter „Datenschutz und Mitteilungen“ registriert wird.

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

Das Code-Snippet oben ist eine Skelettimplementierung, die alles enthält, was für die Einbindung eines Monetarisierungsanbieters in „Datenschutz und Mitteilungen“ erforderlich ist. Für jede Anbieterfunktion wurde Beispielcode hinzugefügt, den du durch deine eigene Implementierung ersetzen musst.

Methodenzusammenfassung

Ein Monetarisierungsanbieter ist ein Objekt, das Monetarisierungsfunktionen auf Webseiten bereitstellt, indem es eine Reihe von Kernfunktionen zur Verfügung stellt. Diese Funktionen werden unten näher beschrieben.

Methode Zusammenfassung
initialize Initialisiere den Monetarisierungsanbieter und alle erforderlichen Ressourcen, um Monetarisierungsaktionen auszuführen.
getUserEntitlementState Ruft den Berechtigungsstatus des Nutzers zum Zeitpunkt der Aufrufs ab.
monetize Rendere deine benutzerdefinierte Monetarisierungslösung auf der Webseite. Ihre Monetarisierungslösung kann jede beliebige Form haben, z. B. eine Anzeige mit Prämie oder ein Dialogfeld für Abodienste.
destroy Löschen Sie den Anbieter und alle Ressourcen oder Jobs, die bei der Initialisierung ausgeführt wurden. Nach der Zerstörung ruft die Offerwall keine Anbietermethoden mehr auf.

Methodendefinitionen

Die Definition der einzelnen Monetarisierungsmethoden von Anbietern wird unten näher beschrieben.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Initialisiere den Monetarisierungsanbieter. Nach der Initialisierung sollte der Anbieter in der Lage sein, auf alle anderen Anbieterfunktionen zu reagieren. Diese Funktion wird garantiert vor jeder anderen Anbieterfunktion aufgerufen und wird bei einem bestimmten Seitenladevorgang voraussichtlich höchstens einmal aufgerufen.

Beispiel:

  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>

Ruft den Berechtigungsstatus des Nutzers zum Zeitpunkt der Aufrufs ab. Die Offerwall wird ausgeblendet, wenn der Nutzer berechtigt ist, da er kostenlosen Zugriff auf die Website erhalten sollte.

Beispiel:

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

Monetarisieren

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Rendere deine Monetarisierungslösung und handel mit den Monetarisierungsaktionen des Nutzers. Die Monetarisierung kann verschiedene Formen haben, z. B. Anzeigen mit Prämie oder Abodienste. Sobald diese Methode von der Offerwall aufgerufen wird, wird die Offerwall ausgeblendet, bis das Versprechen erfüllt ist. Daher liegt es in der Verantwortung des Anbieters, den Seiteninhalt zu sperren, bis das Problem behoben ist. Sobald das Versprechen erfüllt wurde, muss der Anbieter auch dafür sorgen, dass er nicht mehr auf der Webseite zu sehen ist.

Wir empfehlen dir dringend, den vorgeschlagenen Sprachcode und die vorgeschlagenen Stile in InitializeParams in deiner Monetarisierungslösung zu verwenden. So wird ein nahtloses visuelles Erlebnis zwischen Offerwall und dem Anbieter gewährleistet.

Die Offerwall legt den Parameter „Monetarisierungsportal“ fest, um anzugeben, auf welches Portal zugegriffen werden soll. Die beiden verfügbaren Portaltypen sind PORTAL_PRIMARY_ACCESS, der nicht optional ist, und PORTAL_SIGN_IN, der optional ist. Du kannst angeben, ob du das optionale Portal PORTAL_SIGN_IN in deiner Antwort auf die Funktion initialize unterstützt.

Wenn Sie das Versprechen zur Monetarisierungsfunktion auflösen, müssen Sie Folgendes tun:

  • Renderte Monetarisierungslösung ausblenden

  • Gibt an, ob der Nutzer zum Seiteninhalt berechtigt ist. Damit wird festgelegt, ob die Offerwall weiterhin angezeigt oder ausgeblendet wird.

  • Gib gegebenenfalls zusätzliche Daten zur Nutzerinteraktion zurück, z. B. den gezahlten Betrag, den Berechtigungstyp und ‑wert sowie die Häufigkeit der Monetarisierung.

Beispiel:

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

löschen

destroy(destroyParams:DestroyParams): void

Den Anbieter zerstören. Diese Funktion wird garantiert als letzte im Lebenszyklus des Anbieters aufgerufen und sollte bei einem bestimmten Seitenladevorgang höchstens einmal aufgerufen werden.

Beispiel:

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

Typdefinitionen

Die Definition der einzelnen Datentypen in der API wird unten weiter beschrieben.

Objektdefinitionen

In diesem Abschnitt werden alle Objektdefinitionen in der API aufgeführt.

InitializeParams

Der Parametertyp für die Funktion 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

Der Typ zum Definieren von Stilen.

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

InitializeResponse

Der Antworttyp für die Funktion 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

Der Parametertyp für die Funktion 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

Der Antworttyp für die Funktion 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

Der Typ für die Definition eines Geldbetrags in einer bestimmten Währung. Siehe ursprüngliche Definition in 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

Der Parametertyp für die Funktion destroy.

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

Enumerationsdefinitionen

In diesem Abschnitt werden alle Enum-Definitionen in der API aufgeführt.

googlefc.monetization.UserEntitlementStateEnum

Die Aufzählung der Berechtigung gibt an, dass ein Nutzer für einen Monetarisierungsanbieter infrage kommt.

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

Aufzählung der verschiedenen Monetarisierungsportale oder Monetarisierungszugangspunkte, die ein Anbieter möglicherweise unterstützt. Weitere Informationen zu Monetarisierungsportalen finden Sie im Glossar.

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

Aufzählung der verschiedenen Berechtigungstypen, die ein Monetarisierungsanbieter einem Nutzer gewähren kann.

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

Aufzählung der Gründe, aus denen ein Monetarisierungsanbieter gelöscht werden kann.

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

Aufzählung der verschiedenen Wiederholungsintervalle für die Monetarisierung, die nach einer Nutzeraktion gestartet werden können.

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

Anbieterregistrierung

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

Das JavaScript-Objekt auf Fensterebene, mit dem Monetarisierungsanbieter registriert werden. Die Registrierung umfasst das Übergeben des durch einen statischen Registrierungsschlüssel gekennzeichneten Anbieterobjekts an eine Registry, die sich im Windows-Namespace befindet: 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());

Versionsverlauf

Version Veröffentlicht am Zusammenfassung
1.0.0 24.07.2023 Erste Version der Monetization Provider API.