Halaman ini diterjemahkan oleh Cloud Translation API.

Monetization Provider API

Versi: 1.0.0

Pengantar

API klien penyedia monetisasi memungkinkan Anda mengintegrasikan solusi monetisasi Anda sendiri dengan Privasi & pesan di Ad Manager.

Untuk mengintegrasikan solusi monetisasi Anda sendiri dengan Offerwall, ikuti langkah-langkah berikut:

Aktifkan opsi "Pilihan Kustom" untuk Offerwall dari dalam tab Privasi & pesan di Ad Manager.
Tambahkan JavaScript kustom di situs tempat Offerwall dipublikasikan. Detail penerapan dapat ditemukan di bagian di bawah.
JavaScript ini harus membuat instance penyedia monetisasi kustom seperti yang ditentukan di bawah dan mendaftarkan penyedia ke Privacy & messaging di jendela dengan kunci pendaftaran: 'publisherCustom'.

Glosarium

Istilah	Definisi
Penyedia Monetisasi	Objek JavaScript native yang menyediakan solusi monetisasi kustom Anda. Misalnya, Anda dapat menyediakan layanan langganan, layanan pembayaran mikro, dan lainnya. Offerwall memanggil metode penyedia Anda untuk memonetisasi konten dengan solusi kustom Anda.
Kepemilikan hak	Reward yang diberikan kepada pengguna oleh solusi monetisasi Anda karena menyelesaikan beberapa tindakan monetisasi. Dalam cakupan API ini, hak memberikan pengguna akses ke konten situs Anda tanpa melihat Offerwall. Anda menentukan jumlah pemuatan halaman gratis atau durasi waktu yang diberikan kepada pengguna yang memilih pilihan monetisasi kustom Anda.
Portal Monetisasi	Titik entri ke alur monetisasi. Portal menentukan alur terpisah yang ditawarkan oleh solusi monetisasi Anda. Misalnya, satu portal mungkin untuk "monetisasi", tempat pengguna dapat berlangganan layanan Anda. Portal lain mungkin untuk "login", tempat pengguna dapat login untuk mengakses langganan yang ada.
Kunci Pendaftaran	ID penyedia monetisasi, yang digunakan untuk mendaftarkan penerapan penyedia Anda dengan Privasi & pesan Google pada waktu pemuatan halaman.

Contoh Implementasi API

Berikut adalah contoh penerapan yang berfungsi yang menentukan penyedia monetisasi, membuat instance-nya, dan mendaftarkannya ke Privasi & pesan 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>

Cuplikan kode di atas adalah implementasi kerangka yang menyertakan semua hal yang diperlukan untuk mengintegrasikan penyedia monetisasi dengan Privasi & pesan. Perhatikan bahwa untuk setiap fungsi penyedia, kode contoh telah ditambahkan yang harus Anda ganti dengan implementasi Anda sendiri.

Ringkasan Metode

Penyedia monetisasi adalah objek yang menyediakan fungsi monetisasi di halaman web dengan mengekspos kumpulan fungsi inti. Fungsi ini dijelaskan lebih lanjut di bawah.

Metode	Ringkasan
melakukan inisialisasi	Lakukan inisialisasi penyedia monetisasi, beserta resource apa pun yang diperlukan untuk melakukan tindakan monetisasi.
getUserEntitlementState	Dapatkan status hak pengguna pada saat pemanggilan.
monetisasi	Render solusi monetisasi kustom Anda di halaman web. Solusi monetisasi Anda dapat berupa apa saja, dengan beberapa contohnya adalah iklan reward, dialog layanan langganan, dan lainnya.
destroy	Menghancurkan penyedia, beserta resource atau tugas apa pun yang berjalan saat inisialisasi. Setelah dihancurkan, Offerwall tidak lagi memanggil metode penyedia apa pun.

Definisi Metode

Definisi setiap metode penyedia monetisasi dijelaskan lebih lanjut di bawah.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Lakukan inisialisasi penyedia monetisasi. Setelah diinisialisasi, penyedia harus siap merespons fungsi penyedia lainnya. Fungsi ini dijamin akan dipanggil sebelum fungsi penyedia lainnya, dan dapat diharapkan akan dipanggil maksimal satu kali pada pemuatan halaman tertentu.

Contoh:

  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>

Dapatkan status hak pengguna pada saat pemanggilan. Offerwall disembunyikan jika pengguna berhak karena pengguna harus menerima akses gratis ke situs.

Contoh:

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

monetisasi

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Render solusi monetisasi Anda dan tangani tindakan monetisasi pengguna. Monetisasi dapat berupa apa saja, baik iklan reward, layanan langganan, dan lainnya. Setelah metode ini dipanggil oleh Offerwall, Offerwall akan disembunyikan hingga promise diselesaikan. Oleh karena itu, penyedia bertanggung jawab untuk mengontrol konten halaman hingga promise diselesaikan. Setelah promise diselesaikan, penyedia juga harus memastikan bahwa promise tidak lagi terlihat di halaman web.

Sebaiknya gunakan kode dan gaya bahasa yang disarankan yang disediakan di InitializeParams dalam solusi monetisasi Anda. Hal ini memastikan pengalaman visual yang lancar antara Offerwall dan penyedia.

Offerwall menetapkan parameter portal monetisasi untuk menunjukkan portal mana yang ingin diakses. Dua jenis portal yang tersedia mencakup PORTAL_PRIMARY_ACCESS yang tidak opsional, dan PORTAL_SIGN_IN yang opsional. Anda dapat menunjukkan apakah Anda mendukung portal opsional PORTAL_SIGN_IN dalam respons Anda ke fungsi initialize.

Setelah me-resolve promise fungsi monetisasi, Anda harus:

Sembunyikan solusi monetisasi yang dirender.
Menampilkan apakah pengguna berhak mendapatkan konten halaman atau tidak. Hal ini menentukan apakah Offerwall akan terus ditampilkan atau disembunyikan.
Tampilkan data tambahan apa pun tentang interaksi pengguna jika berlaku, seperti jumlah yang dibayar, jenis & nilai hak, dan pengulangan monetisasi.

Contoh:

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

hancurkan

destroy(destroyParams:DestroyParams): void

Menghancurkan penyedia. Fungsi ini dijamin akan dipanggil terakhir dalam siklus proses penyedia, dan Anda harus mengharapkannya dipanggil maksimal sekali pada muat halaman tertentu.

Contoh:

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

Definisi Jenis

Definisi setiap jenis data di API dijelaskan lebih lanjut di bawah.

Definisi Objek

Bagian ini mencantumkan semua definisi objek di API.

`InitializeParams`

Jenis parameter untuk fungsi 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`

Jenis untuk menentukan gaya.

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

`InitializeResponse`

Jenis respons untuk fungsi 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`

Jenis parameter untuk fungsi monetisasi.

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`

Jenis respons untuk fungsi 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`

Jenis untuk menentukan jumlah uang dalam mata uang tertentu. Lihat definisi money.proto asli.

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`

Jenis parameter untuk fungsi destroy.

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

Definisi Enum

Bagian ini mencantumkan semua definisi enum di API.

`googlefc.monetization.UserEntitlementStateEnum`

Enumerasi hak menyatakan bahwa pengguna dapat menggunakan penyedia monetisasi.

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`

Enumerasi berbagai portal monetisasi, atau titik entri monetisasi, yang mungkin dapat didukung oleh penyedia. Lihat glosarium untuk mengetahui informasi selengkapnya tentang portal monetisasi.

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`

Enumerasi berbagai jenis hak yang dapat diberikan oleh penyedia monetisasi kepada pengguna.

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`

Enumerasi alasan penyedia monetisasi dapat dihancurkan.

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`

Enumerasi berbagai ritme pengulangan monetisasi yang dapat dimulai setelah beberapa tindakan pengguna.

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

Pendaftaran Penyedia

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

Objek JavaScript tingkat jendela yang digunakan untuk mendaftarkan penyedia monetisasi. Pendaftaran mencakup penerusan objek penyedia yang dibuat instance-nya dan diberi kunci oleh kunci pendaftaran statis ke registry yang berada di namespace jendela: 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());

Histori Versi

Versi	Tanggal Rilis	Ringkasan
1.0.0	24/07/2023	Rilis awal Monetization Provider API.

Monetization Provider API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Pengantar

Glosarium

Contoh Implementasi API

Ringkasan Metode

Definisi Metode

initialize

getUserEntitlementState

monetisasi

hancurkan

Definisi Jenis

Definisi Objek

Definisi Enum

Pendaftaran Penyedia

Histori Versi

Monetization Provider API