API nhà cung cấp kiếm tiền

Phiên bản: 1.0.0

Giới thiệu

API ứng dụng của nhà cung cấp dịch vụ kiếm tiền cho phép bạn tích hợp giải pháp kiếm tiền của riêng mình với phần Quyền riêng tư và thông báo trong Ad Manager.

Để tích hợp giải pháp kiếm tiền của riêng bạn với Offerwall, hãy làm theo các bước sau:

  • Bật tuỳ chọn "Lựa chọn tuỳ chỉnh" cho Offerwall trong thẻ Quyền riêng tư và thông báo trong Ad Manager.

  • Thêm JavaScript tuỳ chỉnh trên trang web mà Offerwall được xuất bản. Bạn có thể xem thông tin chi tiết về cách triển khai trong các phần bên dưới.

  • JavaScript này sẽ tạo bản sao của một nhà cung cấp kiếm tiền tuỳ chỉnh như được xác định bên dưới và đăng ký nhà cung cấp đó với Quyền riêng tư và thông báo trên cửa sổ bằng khoá đăng ký: 'publisherCustom'.

Bảng thuật ngữ

Thuật ngữ Định nghĩa
Nhà cung cấp dịch vụ kiếm tiền Một đối tượng JavaScript gốc cung cấp giải pháp kiếm tiền tuỳ chỉnh. Ví dụ: bạn có thể cung cấp dịch vụ thuê bao, dịch vụ thanh toán vi mô và nhiều dịch vụ khác. Offerwall gọi các phương thức của nhà cung cấp để kiếm tiền từ nội dung của bạn bằng giải pháp tuỳ chỉnh.
Quyền đối với sản phẩm Phần thưởng do giải pháp kiếm tiền của bạn cấp cho người dùng khi họ hoàn tất một số hành động kiếm tiền. Trong phạm vi của API này, một quyền sẽ cấp cho người dùng quyền truy cập vào nội dung của trang web mà không cần xem Offerwall. Bạn xác định số lượt tải trang miễn phí hoặc thời lượng được cấp cho những người dùng chọn lựa chọn kiếm tiền tuỳ chỉnh của bạn.
Cổng thông tin kiếm tiền Điểm truy cập vào luồng kiếm tiền. Cổng xác định các luồng riêng biệt do giải pháp kiếm tiền của bạn cung cấp. Ví dụ: một cổng thông tin có thể dành cho "kiếm tiền", nơi người dùng có thể đăng ký dịch vụ của bạn. Một cổng thông tin khác có thể là để "đăng nhập", nơi người dùng có thể đăng nhập để truy cập vào một gói thuê bao hiện có.
Khoá đăng ký Giá trị nhận dạng của nhà cung cấp kiếm tiền, được dùng để đăng ký việc triển khai nhà cung cấp của bạn với công cụ Quyền riêng tư và thông báo của Google tại thời điểm tải trang.

Triển khai API mẫu

Dưới đây là ví dụ về cách triển khai hiệu quả giúp xác định trình cung cấp dịch vụ kiếm tiền, tạo bản sao và đăng ký trình cung cấp dịch vụ kiếm tiền đó với công cụ Quyền riêng tư và thông báo của 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>

Đoạn mã ở trên là một bản triển khai khung bao gồm mọi thứ cần thiết để tích hợp nhà cung cấp kiếm tiền với tính năng Quyền riêng tư và thông báo. Xin lưu ý rằng đối với mỗi hàm nhà cung cấp, mã ví dụ đã được thêm vào mà bạn chịu trách nhiệm thay thế bằng cách triển khai của riêng mình.

Tóm tắt phương thức

Nhà cung cấp dịch vụ kiếm tiền là một đối tượng cung cấp chức năng kiếm tiền trên trang web bằng cách hiển thị một nhóm hàm cốt lõi. Các hàm này được mô tả thêm ở bên dưới.

Phương thức Tóm tắt
khởi chạy Khởi động trình cung cấp dịch vụ kiếm tiền cùng với mọi tài nguyên cần thiết để thực hiện các hành động kiếm tiền.
getUserEntitlementState Lấy trạng thái quyền của người dùng tại thời điểm gọi.
kiếm tiền Hiển thị giải pháp kiếm tiền tuỳ chỉnh trên trang web. Giải pháp kiếm tiền của bạn có thể ở bất kỳ hình thức nào, chẳng hạn như quảng cáo có tặng thưởng, hộp thoại dịch vụ thuê bao, v.v.
destroy Huỷ bỏ nhà cung cấp cùng với mọi tài nguyên hoặc công việc đang chạy khi khởi chạy. Sau khi bị huỷ, Offerwall sẽ không còn gọi bất kỳ phương thức nhà cung cấp nào nữa.

Định nghĩa phương thức

Định nghĩa của từng phương thức nhà cung cấp dịch vụ kiếm tiền được mô tả chi tiết hơn ở bên dưới.

khởi chạy

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Khởi chạy nhà cung cấp dịch vụ kiếm tiền. Sau khi khởi chạy, trình cung cấp sẽ sẵn sàng phản hồi mọi hàm trình cung cấp khác. Hàm này được đảm bảo sẽ được gọi trước mọi hàm nhà cung cấp khác và có thể được gọi tối đa một lần trong một lượt tải trang nhất định.

Ví dụ:

  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>

Lấy trạng thái quyền của người dùng tại thời điểm gọi. Offerwall sẽ bị ẩn nếu người dùng đủ điều kiện vì người dùng sẽ được cấp quyền truy cập miễn phí vào trang web.

Ví dụ:

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

kiếm tiền

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Hiển thị giải pháp kiếm tiền và xử lý các hành động kiếm tiền của người dùng. Bạn có thể kiếm tiền theo bất kỳ hình thức nào, cho dù đó là quảng cáo có tặng thưởng, dịch vụ thuê bao, v.v. Sau khi Offerwall gọi phương thức này, Offerwall sẽ bị ẩn cho đến khi lời hứa được giải quyết. Do đó, nhà cung cấp có trách nhiệm kiểm soát nội dung trang cho đến khi lời hứa được giải quyết. Sau khi lời hứa được giải quyết, nhà cung cấp cũng phải đảm bảo không còn xuất hiện trên trang web nữa.

Bạn nên sử dụng mã ngôn ngữ và kiểu được đề xuất được cung cấp trong InitializeParams trong giải pháp kiếm tiền của mình. Điều này đảm bảo trải nghiệm hình ảnh liền mạch giữa Offerwall và nhà cung cấp.

Offerwall đặt thông số cổng kiếm tiền để cho biết cổng nào mà Offerwall muốn truy cập. Có hai loại cổng thông tin, bao gồm PORTAL_PRIMARY_ACCESS (bắt buộc) và PORTAL_SIGN_IN (không bắt buộc). Bạn có thể cho biết liệu bạn có hỗ trợ cổng thông tin PORTAL_SIGN_IN không bắt buộc trong phản hồi cho hàm khởi chạy hay không.

Sau khi giải quyết lời hứa về hàm kiếm tiền, bạn phải:

  • Ẩn giải pháp kiếm tiền đã hiển thị.

  • Trả về thông tin người dùng có quyền truy cập vào nội dung trang hay không. Điều này xác định liệu Offerwall có tiếp tục hiển thị hay bị ẩn.

  • Trả về mọi dữ liệu bổ sung về lượt tương tác của người dùng (nếu có), chẳng hạn như số tiền đã trả, loại và giá trị quyền, cũng như tần suất kiếm tiền.

Ví dụ:

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

hủy bỏ

destroy(destroyParams:DestroyParams): void

Huỷ bỏ nhà cung cấp. Hàm này được đảm bảo được gọi sau cùng trong vòng đời của trình cung cấp và bạn nên dự kiến hàm này được gọi nhiều nhất một lần trên một lượt tải trang nhất định.

Ví dụ:

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

Định nghĩa loại

Định nghĩa của từng loại dữ liệu trong API được mô tả chi tiết hơn ở bên dưới.

Định nghĩa đối tượng

Phần này liệt kê tất cả các định nghĩa đối tượng trong API.

InitializeParams

Kiểu tham số cho hàm khởi chạy.

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

Loại để xác định kiểu.

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

InitializeResponse

Loại phản hồi cho hàm initialize (khởi chạy).

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

Kiểu tham số cho hàm kiếm tiền.

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

Loại phản hồi cho hàm kiếm tiền.

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

Loại để xác định số tiền bằng một đơn vị tiền tệ cụ thể. Xem định nghĩa gốc của 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

Kiểu tham số cho hàm destroy.

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

Định nghĩa enum

Phần này liệt kê tất cả các định nghĩa enum trong API.

googlefc.monetization.UserEntitlementStateEnum

Việc liệt kê quyền cho biết người dùng có thể tham gia một nhà cung cấp kiếm tiền.

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

Liệt kê các cổng kiếm tiền hoặc điểm truy cập kiếm tiền mà nhà cung cấp có thể hỗ trợ. Hãy xem bảng thuật ngữ để biết thêm thông tin về cổng kiếm tiền.

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

Liệt kê các loại quyền mà nhà cung cấp dịch vụ kiếm tiền có thể cấp cho người dùng.

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

Liệt kê các lý do có thể khiến nhà cung cấp dịch vụ kiếm tiền bị huỷ.

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

Liệt kê các tần suất lặp lại khác nhau để kiếm tiền có thể bắt đầu khi người dùng thực hiện một số hành động.

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

Đăng ký nhà cung cấp

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

Đối tượng JavaScript cấp cửa sổ dùng để đăng ký nhà cung cấp kiếm tiền. Quá trình đăng ký bao gồm việc truyền đối tượng nhà cung cấp được tạo bản sao được khoá bằng khoá đăng ký tĩnh đến một sổ đăng ký nằm trong không gian tên cửa sổ: 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());

Lịch sử Phiên bản

Phiên bản Ngày phát hành Tóm tắt
1.0.0 24/7/2023 Bản phát hành đầu tiên của API nhà cung cấp kiếm tiền.