Offerwall Custom Choice API

簡介

透過 Offerwall Custom Choice API，您可以在 Google Ad Manager 中，將自訂營利解決方案與 Offerwall 整合。

如要將自己的營利解決方案與 Offerwall 整合，請按照自訂選項設定步驟操作。摘要說明：

  1. 在 Ad Manager 的「隱私權與訊息」分頁中，為 Offerwall 啟用「自訂選項」。

  2. 在發布 Offerwall 的網站中，於 <head> 和 </head> 標記之間新增自訂 JavaScript。

  3. 按照後續章節的定義，建立 CustomOfferwallChoice 物件的例項，並在視窗中向 Offerwall 註冊。

程式碼範例

如要快速入門，請參閱這個 Offerwall Custom Choice API 導入作業的範例。

API 使用方法

CustomOfferwallChoice 是 JavaScript 物件，您可將其插入 Offerwall，整合自訂的營利方式。

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

方法定義

本節說明 CustomOfferwallChoice 必須實作的每個方法。

initialize

initialize(params: InitializeParams): Promise<InitializeResponseEnum>

初始化自訂營利解決方案。這個函式會在任何其他函式之前叫用，且預計在特定網頁載入時最多叫用一次。

範例

  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(): Promise<boolean>

顯示自訂營利解決方案，並處理使用者的營利動作。使用者點按自訂選項時，Offerwall 會叫用這個方法。營利形式不限，包括訂閱服務、微付款服務、獎勵廣告等。呼叫時，Offerwall 會隱藏，直到這個 Promise 解決為止，而在此期間，您有責任CustomOfferwallChoice限制頁面內容。解決這項承諾後，您的 CustomOfferwallChoice 必須確保網頁上不再顯示。

show() 函式的 Promise 解決後，您必須：

  • 隱藏已顯示的營利解決方案。

  • 傳回布林值，指出使用者是否已取得網頁內容的存取權：

    • true：使用者已取得網頁內容的存取權。在這種情況下，承諾解決後，Offerwall 不會再次顯示。
    • false：使用者無法存取網頁內容。在這種情況下，Offerwall 會在 Promise 解決後再次算繪。

範例

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

自訂選項註冊

註冊包括將已例項化的 CustomOfferwallChoice 物件傳遞至下列視窗登錄： window.googlefc.offerwall.customchoice.registry

範例

    // 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 類型定義

本節將說明 API 中的每個資料類型。

物件定義

本節說明 API 中的每個物件定義。

InitializeParams

initialize 函式的參數物件型別。

屬性 類型 說明
offerwallLanguageCode string | undefined 根據 BCP 47 定義，放送的 Offerwall 語言代碼。

列舉定義

本節說明 API 中的每個列舉定義。

googlefc.offerwall.customchoice.InitializeResponseEnum

initialize 函式的回應列舉型別。

列舉成員 說明
CUSTOM_CHOICE_DISABLED 在 Offerwall 中停用自訂選項。如果停用自訂選項，Offerwall 就只能使用其他符合資格的選項顯示；如果沒有其他符合資格的選項，Offerwall 就不會在網頁上顯示。
ACCESS_GRANTED 在網頁載入時授予使用者頁面存取權。如果傳回這項回應，Offerwall 就不會在網頁上顯示。
ACCESS_NOT_GRANTED 請勿在網頁載入時授予使用者網頁存取權。如果系統傳回這項回應，表示 Offerwall 符合在網頁上顯示的資格。