このページは Cloud Translation API によって翻訳されました。

Monetization Provider API

バージョン: 1.0.0

はじめに

Monetization Provider クライアント API を使用すると、独自の収益化ソリューションをアドマネージャーの [プライバシーとメッセージ] と統合できます。

独自の収益化ソリューションを Offerwall と統合する手順は次のとおりです。

アドマネージャーの [プライバシーとメッセージ] タブで、オファーウォールの [カスタムチョイス] オプションを有効にします。
Offerwall が公開されているサイトにカスタム JavaScript を追加します。実装の詳細については、以下のセクションをご覧ください。
この JavaScript は、以下で定義されているようにカスタム収益化プロバイダをインスタンス化し、登録キー 'publisherCustom' を使用してウィンドウのプライバシーとメッセージにプロバイダを登録する必要があります。

用語集

用語	定義
収益化プロバイダ	カスタムの収益化ソリューションを提供するネイティブ JavaScript オブジェクト。たとえば、定期購入サービスやマイクロペイメントサービスを提供できます。Offerwall は、プロバイダのメソッドを呼び出して、カスタムソリューションでコンテンツを収益化します。
利用資格	収益化アクションを完了したユーザーに、収益化ソリューションから付与される報酬。この API の対象となる利用資格では、ユーザーはオファーウォールを表示せずにウェブサイトのコンテンツにアクセスできます。カスタムの収益化オプションを選択したユーザーに許可する無料のページ読み込み回数または時間の長さを決定します。
収益化ポータル	収益化フローのエントリポイント。ポータルは、収益化ソリューションで提供される個別のフローを定義します。たとえば、1 つのポータルは「収益化」用で、ユーザーがサービスを定期購入できるものになります。別のポータルは「ログイン」用で、ユーザーがログインして既存のサブスクリプションにアクセスできます。
登録キー	収益化プロバイダの ID。ページの読み込み時に、プロバイダの実装を Google の [プライバシーとメッセージ] に登録するために使用されます。

API 実装のサンプル

以下に、収益化プロバイダを定義し、インスタンス化して、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>

上記のコードスニペットは、収益化プロバイダを [プライバシーとメッセージ] と統合するために必要なものがすべて含まれているスケルトン実装です。プロバイダ関数ごとにサンプルコードが追加されていますが、これは独自の実装に置き換える必要があります。

メソッドの概要

収益化プロバイダは、コアとなる一連の機能を公開することで、ウェブページで収益化機能を提供するオブジェクトです。これらの機能については、後で詳しく説明します。

メソッド	概要
初期化	収益化プロバイダと、収益化アクションの実行に必要なリソースを初期化します。
getUserEntitlementState	呼び出し時にユーザーの利用資格の状態を取得します。
収益化	カスタムの収益化ソリューションをウェブページにレンダリングします。収益化ソリューションは任意の形式にできます。例としては、リワード広告、定期購入サービスダイアログなどがあります。
destroy	初期化時に実行されていたリソースやジョブとともに、プロバイダを破棄します。破棄されると、Offerwall はプロバイダメソッドを呼び出しません。

メソッドの定義

各収益化プロバイダメソッドの定義について、以下で詳しく説明します。

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

収益化プロバイダを初期化します。初期化が完了すると、プロバイダは他のプロバイダ関数に応答できるようになります。この関数は、他のプロバイダ関数よりも前に呼び出されることが保証されており、特定のページ読み込みで最大 1 回呼び出されることになっています。

例:

  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>

呼び出しの時点でユーザーの利用資格の状態を取得します。ユーザーが利用資格を持っている場合、ユーザーはウェブサイトに無料でアクセスできるため、Offerwall は非表示になります。

例:

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

収益化

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

収益化ソリューションをレンダリングし、ユーザーの収益化アクションを処理します。収益化は、リワード広告、サブスクリプションサービスなど、さまざまな形態をとることができます。Offerwall によってこのメソッドが呼び出されると、Promise が解決されるまで Offerwall は非表示になります。そのため、プロバイダは、約束が解決されるまでページコンテンツを制限する責任があります。プロミスが解決されたら、プロバイダはウェブページに表示されないようにする必要があります。

収益化ソリューション内で InitializeParams で提供されている推奨の言語コードとスタイルを使用することを強くおすすめします。これにより、Offerwall とプロバイダの間でシームレスなビジュアルエクスペリエンスが実現します。

Offerwall は、アクセスするポータルを示すように収益化ポータルパラメータを設定します。使用できるポータルタイプは、必須の PORTAL_PRIMARY_ACCESS とオプションの PORTAL_SIGN_IN の 2 つです。オプションのポータル PORTAL_SIGN_IN をサポートするかどうかは、initialize 関数へのレスポンスで指定できます。

monetize 関数の Promise を解決する際には、次のことを行う必要があります。

レンダリングされた収益化ソリューションを非表示にします。
ユーザーがページコンテンツの利用資格があるかどうかを返します。これにより、Offerwall を表示し続けるか非表示にするかを決定します。
該当する場合は、支払われた金額、利用資格の種類と値、収益化の頻度など、ユーザーインタラクションに関する追加データを返します。

例:

  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

プロバイダを破棄します。この関数は、プロバイダのライフサイクルで最後に呼び出されることが保証されています。また、特定のページの読み込みで最大 1 回呼び出されることになっています。

例:

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

タイプの定義

API の各データ型の定義について、以下で詳しく説明します。

オブジェクトの定義

このセクションでは、API 内のすべてのオブジェクト定義を一覧表示します。

`InitializeParams`

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`

スタイルを定義するタイプ。

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

`InitializeResponse`

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`

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`

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`

特定の通貨で金額を定義するための型。元の 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`

destroy 関数のパラメータタイプ。

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

列挙型の定義

このセクションでは、API のすべての列挙型定義を一覧表示します。

`googlefc.monetization.UserEntitlementStateEnum`

利用資格の列挙は、ユーザーが収益化プロバイダを利用できることを示します。

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`

プロバイダがサポートできるさまざまな収益化ポータル（収益化エントリポイント）の列挙。収益化ポータルの詳細については、用語集をご覧ください。

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`

収益化プロバイダがユーザーに付与できるさまざまな利用資格のタイプを列挙します。

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`

収益化プロバイダが破棄される理由の列挙。

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`

ユーザーの操作によって開始できるさまざまな収益化の繰り返し頻度を列挙します。

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

医療機関の登録

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

収益化プロバイダの登録に使用されるウィンドウレベルの JavaScript オブジェクト。登録には、静的登録キーでキーが設定されたインスタンス化されたプロバイダオブジェクトを、ウィンドウ Namespace（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());

変更履歴

バージョン	リリース日	概要
1.0.0	2023 年 7 月 24 日	Monetization Provider API の初版リリース。