Offerwall Custom Choice API

Introduction

The Offerwall Custom Choice API lets you integrate your own custom monetization solution with Offerwall in Google Ad Manager.

To integrate your own monetization solution with Offerwall, follow these Custom Choice setup steps. In summary:

  1. Enable the "Custom Choice" option for your Offerwall from within the Privacy & messaging tab in Ad Manager.

  2. Add custom JavaScript between the <head> and </head> tags of the site where you have published your Offerwall.

  3. Instantiate a CustomOfferwallChoice object as defined in the sections that follow, and register it with your Offerwall on the window.

API Usage

A CustomOfferwallChoice is a JavaScript object that you plug in to your Offerwall to integrate your custom monetization implementation.

// Define your custom choice.
class CustomOfferwallChoice {
  // Initialize your custom choice, which may include loading or preparing any
  // resources required to function.
  async initialize(params: InitializeParams): Promise<InitializeResponseEnum> {...}

  // Show your custom choice on the web page, which may be a subscription
  // service, micropayments service, rewarded ad, etc.
  async show(): Promise<boolean> {...}
}

// Register your custom choice with your Offerwall.
window.googlefc = window.googlefc || {};
window.googlefc.offerwall = window.googlefc.offerwall || {};
window.googlefc.offerwall.customchoice = window.googlefc.offerwall.customchoice || {};
window.googlefc.offerwall.customchoice.registry = new CustomOfferwallChoice();

Method Definitions

This section describes each method that a CustomOfferwallChoice is required to implement.

initialize

initialize(params: InitializeParams): Promise<InitializeResponseEnum>

Initialize your custom monetization solution. This function is invoked before any other function, and can be expected to be invoked at most once on a given page load.

Example

  async initialize(params: InitializeParams): Promise<InitializeResponseEnum> {
    // If your custom choice is inoperable on this page, return CUSTOM_CHOICE_DISABLED,
    // causing your Offerwall to exclude the custom choice option when rendering.
    const isCustomChoiceEnabled: boolean = await this.initializeCustomOfferwallChoice(params);
    if (!isCustomChoiceEnabled) {
      resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.CUSTOM_CHOICE_DISABLED);
    }

    // If the user should automatically be granted page access on page load, return
    // ACCESS_GRANTED, causing your Offerwall to be ineligible to render on this page.
    const isAccessGranted: boolean = await this.shouldUserBeGrantedPageAccess();
    if (isAccessGranted) {
      resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.ACCESS_GRANTED);
    }

    // If the user shouldn't automatically be granted page access on page load, return
    // ACCESS_NOT_GRANTED, causing your Offerwall to be eligible to render on this page.
    resolve(googlefc.offerwall.customchoice.InitializeResponseEnum.ACCESS_NOT_GRANTED);
  }

show

show(): Promise<boolean>

Render your custom monetization solution and handle the user's monetization actions. This method is invoked by your Offerwall when the user clicks on the custom choice option. Monetization can take any form, including a subscription service, micropayments service, rewarded ad, and more. When invoked, your Offerwall is hidden until this promise is resolved and it is the responsibility of your CustomOfferwallChoice to gate page content in the meantime. Once this promise is resolved, your CustomOfferwallChoice must be sure to no longer be visible on the web page.

Upon resolution of the show() function's promise, you must:

  • Hide your rendered monetization solution.

  • Return a boolean value indicating whether the user gained access to page content:

    • true: User gained access to page content. In this case, your Offerwall won't be rendered again upon promise resolution.
    • false: User did not gain access to page content. In this case, your Offerwall will be rendered again upon promise resolution.

Example

  async show(): Promise<boolean> {
    // Show your custom choice dialog and hide it once the user completes an action.
    const didUserGainAccessToPage: boolean = await this.showCustomChoiceDialogUntilUserAction();

    resolve(didUserGainAccessToPage);
  }

Custom Choice Registration

Registration includes passing your instantiated CustomOfferwallChoice object to the following window registry: window.googlefc.offerwall.customchoice.registry

Example

    // Register your custom choice with your Offerwall.
    window.googlefc = window.googlefc || {};
    window.googlefc.offerwall = window.googlefc.offerwall || {};
    window.googlefc.offerwall.customchoice = window.googlefc.offerwall.customchoice || {};
    window.googlefc.offerwall.customchoice.registry = new CustomOfferwallChoice();

API Type Definitions

This section describes each data type in the API.

Object Definitions

This section describes each object definition in the API.

InitializeParams

The parameter object type for the initialize function.

Property Type Description
offerwallLanguageCode string | undefined The language code of your Offerwall that is being served, as defined by BCP 47.

Enum Definitions

This section describes each enum definition in the API.

googlefc.offerwall.customchoice.InitializeResponseEnum

The response enum type for the initialize function.

Enumeration member Description
CUSTOM_CHOICE_DISABLED Disable the custom choice option in your Offerwall. If custom choice is disabled, your Offerwall can only
render with other eligible choices; if no other choices are eligible, your Offerwall won't ever render on the page.
ACCESS_GRANTED Grant the user page access on page load. Your Offerwall won't ever render on the page if this response is returned.
ACCESS_NOT_GRANTED Don't grant the user page access on page load. Your Offerwall is eligible to render on the page if this response is returned.