Ta strona została przetłumaczona przez Cloud Translation API.

Monetization Provider API

Wersja: 1.0.0

Wprowadzenie

Interfejs Monetization Provider API umożliwia integrację własnego rozwiązania do generowania przychodu z usługą Prywatność i wyświetlanie wiadomości w Ad Managerze.

Aby zintegrować własne rozwiązanie do zarabiania z wiadomością typu Offerwall:

Na karcie Prywatność i wyświetlanie wiadomości w usłudze Ad Manager włącz opcję „Opcja niestandardowa” dla wiadomości typu Offerwall.
Dodaj niestandardowy kod JavaScriptu w witrynie, w której wiadomość typu Offerwall została opublikowana. Szczegółowe informacje o wdrożeniu znajdziesz w sekcjach poniżej.
Ten kod JavaScript powinien instancjonować niestandardowego dostawcę funkcji zarabiania, jak określono poniżej, i zarejestrować go w oknie Privacy & messaging za pomocą klucza rejestracji: 'publisherCustom'.

Słowniczek

Termin	Definicja
Usługodawca generowania przychodu	Natywne obiekty JavaScript, które zapewniają niestandardowe rozwiązanie do generowania przychodu. Możesz na przykład udostępniać usługę subskrypcyjną, mikropłatności i inne. Wiadomość typu Offerwall wywołuje metody dostawcy w celu zarabiania na treściach za pomocą Twojego rozwiązania niestandardowego.
Uprawnienie	Nagroda przyznawana użytkownikom przez Twoje rozwiązanie do generowania przychodu za wykonanie określonego działania związanego z generowaniem przychodu. W ramach tego interfejsu API uprawnienia przyznają użytkownikom dostęp do treści w Twojej witrynie bez wyświetlania wiadomości typu Offerwall. Ty określasz liczbę bezpłatnych wczytań strony lub czas, przez który użytkownicy mogą korzystać z Twojej niestandardowej opcji zarabiania.
Portal Zarabianie	Punkt wejścia do procesu zarabiania. Portale definiują osobne przepływy danych oferowane przez Twoje rozwiązanie do generowania przychodu. Na przykład jeden portal może służyć do zarabiania i umożliwiać użytkownikowi subskrybowanie Twojej usługi. Inny portal może służyć do logowania, gdzie użytkownik może zalogować się, aby uzyskać dostęp do istniejącej subskrypcji.
Klucz rejestracji	Identyfikator dostawcy funkcji zarabiania, który służy do rejestrowania implementacji dostawcy w Google Prywatność i wyświetlanie wiadomości w momencie wczytywania strony.

Przykładowa implementacja interfejsu API

Oto przykład działającej implementacji, która definiuje dostawcę funkcji zarabiania, tworzy jego instancję i rejestruje go w Prywatności i wyświetlaniu wiadomości 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>

Powyższy fragment kodu to szkielet implementacji, który zawiera wszystko, co jest wymagane do zintegrowania dostawcy przychodów z funkcją Prywatność i wyświetlanie wiadomości. Pamiętaj, że w przypadku każdej funkcji dostawcy dodano przykładowy kod, który musisz zastąpić własną implementacją.

Podsumowanie metody

Dostawca funkcji zarabiania to obiekt, który zapewnia funkcje zarabiania na stronach internetowych, udostępniając podstawowy zestaw funkcji. Te funkcje są opisane poniżej.

Metoda	Podsumowanie
initialize	Inicjowanie dostawcy przychodów wraz ze wszystkimi zasobami wymaganymi do wykonywania działań związanych z generowaniem przychodów.
getUserEntitlementState	Pobieranie stanu uprawnień użytkownika w momencie wywołania.
zarabianie	Wyrenderuj niestandardowe rozwiązanie do generowania przychodu na stronie internetowej. Rozwiązanie do zarabiania może przybierać dowolną formę, np. reklamę z nagrodą lub okno dialogowe subskrypcji.
destroy	Zniszcz dostawcę wraz ze wszystkimi zasobami i zadaniami, które były uruchomione podczas inicjalizacji. Po zniszczeniu wiadomości typu Offerwall nie wywołuje już żadnych metod dostawcy.

Definicje metod

Definicje każdej metody dostawcy usług płatnych znajdziesz poniżej.

inicjować

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Inicjalizacja dostawcy usług umożliwiających zarabianie. Po zainicjowaniu dostawca powinien być gotowy do reagowania na inne funkcje dostawcy. Ta funkcja jest wywoływana przed każdą inną funkcją dostawcy i może być wywoływana maksymalnie raz podczas wczytywania danej strony.

Przykład:

  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>

Pobieranie stanu uprawnień użytkownika w momencie wywołania. Wiadomość typu Offerwall jest ukryta, jeśli użytkownik ma prawo do bezpłatnego dostępu do witryny.

Przykład:

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

zarabiać

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Wyświetlanie rozwiązania do generowania przychodu i obsługa działań użytkownika związanych z generowaniem przychodu. Zarabianie może przybierać różne formy, np. reklamy z nagrodą czy subskrypcję. Gdy wiadomość typu Offerwall wywoła tę metodę, zostaje ona ukryta, dopóki obietnica nie zostanie spełniona. Dlatego to na dostawcy spoczywa odpowiedzialność za ograniczenie dostępu do treści na stronie, dopóki nie spełni on obietnicy. Po rozwiązaniu problemu dostawca musi się też upewnić, że nie jest już widoczny na stronie internetowej.

Zdecydowanie zalecamy używanie sugerowanego kodu języka i stylów podanych w parametrze InitializeParams w Twoim rozwiązaniu do zarabiania. Zapewnia to płynne wyświetlanie wiadomości typu Offerwall i interfejsów dostawcy.

Wiadomość typu Offerwall ustawia parametr portalu generowania przychodu, aby wskazać, do którego portalu ma uzyskać dostęp. Dostępne są 2 typy portali:PORTAL_PRIMARY_ACCESS, który nie jest opcjonalny, orazPORTAL_SIGN_IN, który jest opcjonalny. W odpowiedzi na funkcję initialize możesz wskazać, czy obsługujesz opcjonalny portal PORTAL_SIGN_IN.

Po spełnieniu obietnicy dotyczącej funkcji zarabiania musisz:

Ukryj wyrenderowane rozwiązanie do generowania przychodu.
Zwraca informację, czy użytkownik ma uprawnienia do treści strony. Określa, czy wiadomość typu Offerwall ma się nadal wyświetlać, czy ma być ukryta.
Zwraca wszelkie dodatkowe dane o interakcji użytkownika, jeśli to konieczne, np. kwotę, typ i wartość uprawnień oraz częstotliwość generowania przychodów.

Przykład:

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

zniszczyć

destroy(destroyParams:DestroyParams): void

Zniszcz dostawcę. Ta funkcja jest wywoływana jako ostatnia w cyklu życia dostawcy i może być wywoływana maksymalnie raz podczas wczytywania danej strony.

Przykład:

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

Definicje typów

Definicje poszczególnych typów danych w interfejsie API zostały opisane poniżej.

Definicje obiektów

W tej sekcji znajdziesz listę wszystkich definicji obiektów w interfejsie API.

`InitializeParams`

Typ parametru dla funkcji 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`

Typ do definiowania stylów.

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

`InitializeResponse`

Typ odpowiedzi dla funkcji 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`

Typ parametru dla funkcji 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`

Typ odpowiedzi dla funkcji 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`

Typ do definiowania kwoty w określonej walucie. Zobacz oryginalną definicję pliku 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`

Typ parametru dla funkcji destroy.

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

Definicje typu wyliczeniowego

W tej sekcji znajdziesz listę wszystkich definicji typów wyliczeń w interfejsie API.

`googlefc.monetization.UserEntitlementStateEnum`

Wyliczenie uprawnień, które użytkownik może mieć w przypadku danego dostawcy usług płatnych.

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`

Wyliczenie różnych portali zarabiania lub punktów wejścia do zarabiania, które dostawca może obsługiwać. Więcej informacji o portalach do zarabiania znajdziesz w glosariuszu.

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`

Wyliczenie różnych typów uprawnień, które dostawca przychodów może przyznać użytkownikowi.

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`

Wyliczenie powodów, dla których dostawca funkcji zarabiania może zostać usunięty.

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`

Wyliczenie różnych częstotliwości powtarzania cyklu generowania przychodów, które można rozpocząć po wykonaniu przez użytkownika określonego działania.

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

Rejestracja dostawcy

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

Obiekt JavaScriptu na poziomie okna służący do rejestrowania dostawców funkcji zarabiania. Rejestracja obejmuje przekazanie instancjonowanego obiektu dostawcy z kluczem stałego rejestru do rejestru znajdującego się w przestrzeni nazw okna: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());

Historia zmian

Wersja	Data wydania	Podsumowanie
1.0.0	24.07.2023	Pierwsza wersja interfejsu Monetization Provider API.

Monetization Provider API Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wprowadzenie

Słowniczek

Przykładowa implementacja interfejsu API

Podsumowanie metody

Definicje metod

inicjować

getUserEntitlementState

zarabiać

zniszczyć

Definicje typów

Definicje obiektów

Definicje typu wyliczeniowego

Rejestracja dostawcy

Historia zmian

Monetization Provider API