版本：1.0.0
简介
借助变现提供商客户端 API，您可以将自己的变现解决方案与 Ad Manager 中的隐私权和消息部分集成。
如需将您自己的变现解决方案与积分墙集成，请按以下步骤操作：
在 Ad Manager 的“隐私权和消息”标签页中，为积分墙启用“自定义选项”。
在积分墙发布到的网站上添加自定义 JavaScript。 如需了解实现详情，请参阅下文。
此 JavaScript 应按如下所定义的实例化自定义创收提供程序，并使用注册键
'publisherCustom'在窗口上将提供程序注册到 Privacy & Messaging。
术语库
| 术语 | 定义 |
|---|---|
| 创收服务提供商 | 用于提供自定义变现解决方案的原生 JavaScript 对象。例如，您可以提供订阅服务、微支付服务等。积分墙会调用提供商的方法，以便使用您的自定义解决方案通过您的内容创收。 |
| 使用权 | 您的变现解决方案为用户完成某些变现操作而授予的奖励。在此 API 的范围内，使用权可让用户访问您网站上的内容，而无需看到积分墙。您可以确定选择您的自定义变现方式的用户可免费加载的网页数量或可享受的免费时长。 |
| 创收门户 | 用于进入创收流程的入口点。门户用于定义变现解决方案提供的各个流程。例如，一个门户可能用于“创收”，用户可以在其中订阅您的服务。另一个门户可能用于“登录”，用户可以在其中登录以访问现有订阅。 |
| 注册密钥 | 变现提供商的标识符，用于在页面加载时向 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>
上面的代码段是一个框架实现，其中包含将变现提供程序与“隐私权和消息”功能集成所需的所有内容。请注意，对于每个提供程序函数，都添加了示例代码，您有责任将其替换为自己的实现。
方法摘要
变现提供程序是一种对象，可通过公开一组核心函数在网页上提供变现功能。下文对这些函数进行了进一步说明。
| 方法 | 摘要 |
|---|---|
| initialize | 初始化变现提供程序以及执行变现操作所需的所有资源。 |
| getUserEntitlementState | 获取调用时刻用户的使用权状态。 |
| 创收 | 在网页上呈现您的自定义变现解决方案。您的变现解决方案可以采用任何形式，例如激励广告、订阅服务对话框等。 |
| destroy | 销毁提供程序以及在初始化时正在运行的所有资源或作业。销毁后，积分墙将不再调用任何提供程序方法。 |
方法定义
下面进一步介绍了每个变现提供商方法的定义。
initialize
initialize(initializeParams:InitializeParams): Promise<InitializeResponse>
初始化变现提供方。初始化后，提供程序应已准备好响应任何其他提供程序函数。此函数保证会在任何其他提供程序函数之前调用，并且在给定网页加载时最多只会调用一次。
示例：
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>
获取调用时刻用户的使用权状态。如果用户有权访问，系统会隐藏积分墙，因为用户应可免费访问相应网站。
示例：
async getUserEntitlementState(): Promise<googlefc.monetization.UserEntitlementStateEnum> {
resolve(this.isUserLoggedIn() ? this.isUserEntitledOnThisPage()
: googlefc.monetization.UserEntitlementStateEnum.ENTITLED_NO);
}
获利
monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>
呈现您的变现解决方案并处理用户的变现操作。 变现形式可以是任何形式，包括激励广告、订阅服务等。积分墙调用此方法后，积分墙会隐藏，直到 promise 解析完毕。因此，在 promise 解决之前，提供商有责任控制网页内容。解决承诺后，提供商还必须确保自己不再显示在网页上。
强烈建议您在变现解决方案的 InitializeParams 中提供的建议语言代码和样式。这样可以确保积分墙和提供商之间提供流畅的视觉体验。
积分墙会设置变现门户参数，以指明其要访问的门户。可用的两个门户类型包括非必需的 PORTAL_PRIMARY_ACCESS 和可选的 PORTAL_SIGN_IN。您可以在对 initialize 函数的响应中指明是否支持可选门户 PORTAL_SIGN_IN。
解析创收函数 promise 后，您必须：
隐藏呈现的变现解决方案。
返回用户是否有权访问网页内容。这决定了积分墙是继续显示还是隐藏。
返回与用户互动相关的任何其他数据（如果适用），例如支付金额、使用权类型和价值，以及变现周期。
示例：
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(destroyParams:DestroyParams): void
销毁提供程序。此函数保证会在提供程序的生命周期中最后调用，并且您应该预计在给定网页加载时最多调用一次此函数。
示例：
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
创收函数的参数类型。
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
创收函数的响应类型。
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 对象。
注册包括将按静态注册键键值对的已实例化提供程序对象传递给位于窗口命名空间下的注册库：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 日 | Monetize Provider API 的初始版本。 |