Monetarisierungsanbieter-API

Version: 1.0.0

Einleitung

Mit der Client API des Monetarisierungsanbieters können Sie Ihre eigene Monetarisierungslösung mit Datenschutz und Mitteilungen in Ad Manager einbinden. Aktuell ist diese API nur für Publisher verfügbar, die an der geschlossenen Offerwall-Beta teilnehmen.

Wenn du deine eigene Monetarisierungslösung in die Offerwall integrieren möchtest, folge diesen Schritten zur Einrichtung der benutzerdefinierten Auswahl. Zusammenfassung:

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

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

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

Glossar

Laufzeit Definition
Monetarisierungsanbieter Ein natives JavaScript-Objekt, das Ihre benutzerdefinierte Monetarisierungslösung bereitstellt. Sie können beispielsweise einen Abodienst, einen Mikrozahlungsdienst und mehr bereitstellen. Die Offerwall ruft die Methoden Ihres Anbieters auf, um Ihre Inhalte mit Ihrer benutzerdefinierten Lösung zu monetarisieren.
Berechtigung Eine Prämie, die Nutzern durch Ihre Monetarisierungslösung für das Ausführen einer Monetarisierungsaktion gewährt wird. Im Rahmen dieser API gewährt eine Berechtigung Nutzern Zugriff auf die Inhalte deiner Website, ohne die Offerwall zu sehen. Sie legen die Anzahl der kostenlosen Seitenladevorgänge oder die Dauer fest, die Nutzer erhalten, wenn sie sich für Ihre benutzerdefinierte Monetarisierungsentscheidung entscheiden.
Monetarisierungsportal Ein Einstiegspunkt in den Monetarisierungsprozess Portale definieren die separaten Abläufe, die Ihre Monetarisierungslösung bietet. Ein Beispiel ist ein Portal für die „Monetarisierung“, bei dem der Nutzer Ihren Dienst abonnieren kann. Ein anderes Portal kann für „Anmelden“ stehen. Hier kann sich der Nutzer anmelden, um auf ein vorhandenes Abo zuzugreifen.
Registrierungsschlüssel Die ID eines Monetarisierungsanbieters, die verwendet wird, um deine Anbieterimplementierung beim Seitenaufbau bei Google „Datenschutz und Mitteilungen“ zu registrieren.

Beispiel-API-Implementierung

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

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

Das obige Code-Snippet ist eine grundlegende Implementierung, die alles enthält, was für die Einbindung eines Monetarisierungsanbieters mit Datenschutz und Mitteilungen erforderlich ist. Für jede Anbieterfunktion wurde Beispielcode hinzugefügt, den Sie durch Ihre eigene Implementierung ersetzen müssen.

Methodenzusammenfassung

Ein Monetarisierungsanbieter ist ein Objekt, das Monetarisierungsfunktionen auf Webseiten bereitstellt und dabei eine Reihe von Hauptfunktionen bereitstellt. Diese Funktionen werden unten näher beschrieben.

Methode Zusammenfassung
initialize Initialisiere den Monetarisierungsanbieter und alle Ressourcen, die für die Durchführung von Monetarisierungsaktionen erforderlich sind.
getUserEntitlementState Ruft den Berechtigungsstatus des Nutzers beim Aufruf ab.
monetarisieren Benutzerdefinierte Monetarisierungslösung auf der Webseite rendern. Ihre Monetarisierungslösung kann jede Form haben, z. B. eine Anzeige mit Prämie, ein Dialogfeld für Abodienste und mehr.
destroy Löschen Sie den Anbieter sowie alle Ressourcen oder Jobs, die bei der Initialisierung ausgeführt wurden. Nach dem Löschen ruft die Offerwall keine Anbietermethoden mehr auf.

Methodendefinitionen

Die einzelnen Methoden zur Monetarisierung werden unten näher beschrieben.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Initialisieren Sie den Monetarisierungsanbieter. Nach der Initialisierung sollte der Anbieter auf alle anderen Anbieterfunktionen reagieren können. Diese Funktion wird garantiert vor jeder anderen Anbieterfunktion und bei einem bestimmten Seitenaufbau höchstens einmal aufgerufen.

Example:

  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 beim Aufruf ab. Die Offerwall ist ausgeblendet, wenn der Nutzer berechtigt ist, da er kostenlosen Zugriff auf die Website erhalten sollte.

Example:

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

Monetarisieren

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Rendern Sie Ihre Monetarisierungslösung und verarbeiten Sie die Monetarisierungsaktionen der Nutzer. Dabei kann es sich z. B. um Anzeigen mit Prämie oder Abodienste handeln. Sobald diese Methode von der Offerwall aufgerufen wird, wird die Offerwall ausgeblendet, bis das Promise aufgelöst wird. Daher ist der Anbieter dafür verantwortlich, die Seiteninhalte so lange zu sperren, bis das Versprechen einzuhalten ist. Sobald das Promise aufgelöst ist, muss auch der Anbieter darauf achten, dass er nicht mehr auf der Webseite sichtbar ist.

Wir empfehlen dringend, den vorgeschlagenen Sprachcode und die Stile zu verwenden, die in InitializeParams in deiner Monetarisierungslösung zur Verfügung gestellt werden. Dadurch wird ein nahtloses visuelles Erlebnis zwischen der Offerwall und dem Anbieter sichergestellt.

Die Offerwall legt den Parameter für das Monetarisierungsportal fest, um anzugeben, auf welches Portal zugegriffen werden soll. Zu den zwei verfügbaren Portaltypen gehören PORTAL_PRIMARY_ACCESS (nicht optional) und PORTAL_SIGN_IN (optional). In Ihrer Antwort auf die Funktion initialize können Sie angeben, ob Sie das optionale Portal PORTAL_SIGN_IN unterstützen.

Nach dem Auflösen des Versprechen der Monetarisierungsfunktion sind folgende Schritte erforderlich:

  • Gerenderte Monetarisierungslösung ausblenden

  • Gibt an, ob der Nutzer eine Berechtigung für den Seiteninhalt hat oder nicht. Dadurch wird festgelegt, ob die Offerwall weiterhin angezeigt oder ausgeblendet wird.

  • Gib gegebenenfalls zusätzliche Daten zur Nutzerinteraktion zurück, z. B. den bezahlten Betrag, den Berechtigungstyp und -wert sowie die Wiederholung der Monetarisierung.

Example:

  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

destroy(destroyParams:DestroyParams): void

Löschen Sie den Anbieter. Diese Funktion wird garantiert zuletzt im Lebenszyklus des Anbieters aufgerufen und Sie sollten davon ausgehen, dass sie bei einem bestimmten Seitenaufbau höchstens einmal aufgerufen wird.

Example:

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

Typdefinitionen

Die Definition jedes Datentyps im API wird unten näher 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;
}

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 zum Definieren eines Geldbetrags in einer bestimmten Währung. Siehe ursprüngliche money.proto-Definition.

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

Enum-Definitionen

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 bei einem Monetarisierungsanbieter anwesend sein kann.

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 Monetarisierungseinstiegspunkte, die ein Anbieter möglicherweise unterstützen kann. 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

Auflistung der verschiedenen Rhythmen für Wiederholungen der Monetarisierung, die bei bestimmten Nutzeraktionen 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, das zum Registrieren von Monetarisierungsanbietern verwendet wird. Die Registrierung umfasst die Übergabe des instanziierten Anbieterobjekts mit einem statischen Registrierungsschlüssel an eine Registry, die sich unter dem Namespace „window“ 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öffentlichungsdatum Zusammenfassung
1.0.0 24.07.2023 Erste Version der Monetarisierungsanbieter-API.