เวอร์ชัน: 1.0.0
บทนำ
Monetization Provider Client API ช่วยให้คุณผสานรวมโซลูชันการสร้างรายได้ของคุณเองกับความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ใน Ad Manager ได้
หากต้องการผสานรวมโซลูชันการสร้างรายได้ของคุณเองกับ Offerwall ให้ทำตามขั้นตอนต่อไปนี้
เปิดใช้ตัวเลือก "ทางเลือกที่กำหนดเอง" สำหรับ Offerwall จากในแท็บความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ใน Ad Manager
เพิ่ม JavaScript ที่กําหนดเองในเว็บไซต์ที่เผยแพร่ Offerwall ดูรายละเอียดการใช้งานได้ที่ส่วนด้านล่าง
JavaScript นี้ควรสร้างอินสแตนซ์ของผู้ให้บริการการสร้างรายได้ที่กำหนดเองตามที่ระบุไว้ด้านล่าง และลงทะเบียนผู้ให้บริการกับความเป็นส่วนตัวและการรับส่งข้อความในหน้าต่างด้วยคีย์การลงทะเบียน:
'publisherCustom'
อภิธานศัพท์
คำศัพท์ | คำจำกัดความ |
---|---|
ผู้ให้บริการสร้างรายได้ | ออบเจ็กต์ JavaScript เดิมที่ให้บริการโซลูชันการสร้างรายได้ที่กำหนดเอง เช่น คุณอาจให้บริการสมัครใช้บริการ บริการการชำระเงินแบบไมโครเพย์เมนต์ และอื่นๆ Offerwall จะเรียกใช้วิธีการของผู้ให้บริการเพื่อสร้างรายได้จากเนื้อหาด้วยโซลูชันที่กำหนดเอง |
การให้สิทธิ์ | รางวัลที่โซลูชันการสร้างรายได้มอบให้แก่ผู้ใช้เมื่อดำเนินการบางอย่างเพื่อสร้างรายได้ ในขอบเขตของ API นี้ การให้สิทธิ์จะอนุญาตให้ผู้ใช้เข้าถึงเนื้อหาของเว็บไซต์ได้โดยไม่ต้องเห็น Offerwall คุณเป็นผู้กำหนดจำนวนการโหลดหน้าเว็บแบบไม่มีค่าใช้จ่ายหรือระยะเวลาที่มอบให้แก่ผู้ใช้ที่เลือกตัวเลือกการสร้างรายได้ที่กำหนดเอง |
พอร์ทัลการสร้างรายได้ | จุดแรกเข้าของขั้นตอนการสร้างรายได้ พอร์ทัลจะกำหนดขั้นตอนแยกต่างหากที่โซลูชันการสร้างรายได้ของคุณนำเสนอ ตัวอย่างเช่น พอร์ทัลหนึ่งอาจใช้สำหรับ "การสร้างรายได้" ซึ่งผู้ใช้สามารถสมัครใช้บริการของคุณได้ พอร์ทัลอื่นอาจเป็น "ลงชื่อเข้าใช้" ซึ่งผู้ใช้สามารถลงชื่อเข้าใช้เพื่อเข้าถึงการสมัครใช้บริการที่มีอยู่ |
คีย์การลงทะเบียน | ตัวระบุของผู้ให้บริการสร้างรายได้ ซึ่งใช้ในการลงทะเบียนการใช้งานผู้ให้บริการกับความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ของ 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 | รับสถานะการให้สิทธิ์ของผู้ใช้ ณ เวลาที่เรียกใช้ |
monetize | แสดงผลโซลูชันการสร้างรายได้ที่กำหนดเองในหน้าเว็บ โซลูชันการสร้างรายได้ของคุณอาจอยู่ในรูปแบบใดก็ได้ เช่น โฆษณาที่มีการให้รางวัล กล่องโต้ตอบบริการที่ต้องสมัครใช้บริการ และอื่นๆ |
destroy | ทำลายผู้ให้บริการ รวมถึงทรัพยากรหรืองานที่ทำงานอยู่เมื่อเริ่มต้น เมื่อถูกทำลาย Offerwall จะไม่เรียกใช้เมธอดของผู้ให้บริการอีกต่อไป |
คําจํากัดความของเมธอด
ด้านล่างนี้คือคำจำกัดความของวิธีการของผู้ให้บริการสร้างรายได้แต่ละราย
เริ่มต้น
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 เรียกใช้เมธอดนี้ Offerwall จะซ่อนอยู่จนกว่า Promise จะได้รับการแก้ไข ดังนั้น ผู้ให้บริการจึงมีหน้าที่รับผิดชอบในการควบคุมเนื้อหาหน้าเว็บจนกว่าข้อสัญญาจะได้รับการแก้ไข เมื่อการตัดสินได้รับการแก้ไขแล้ว ผู้ให้บริการต้องตรวจสอบว่าไม่ปรากฏในหน้าเว็บอีกต่อไป
เราขอแนะนำให้คุณใช้รหัสภาษาและรูปแบบที่แนะนำซึ่งระบุไว้ใน InitializeParams ภายในโซลูชันการสร้างรายได้ วิธีนี้ช่วยให้ Offerwall และผู้ให้บริการมีการแสดงผลที่ราบรื่น
Offerwall จะตั้งค่าพารามิเตอร์พอร์ทัลการสร้างรายได้เพื่อระบุพอร์ทัลที่ต้องการเข้าถึง พอร์ทัล 2 ประเภทที่ใช้ได้มีดังนี้
PORTAL_PRIMARY_ACCESS
ซึ่งไม่บังคับ และ
PORTAL_SIGN_IN
ซึ่งไม่บังคับ คุณสามารถระบุได้ว่าคุณรองรับพอร์ทัล PORTAL_SIGN_IN
ที่ไม่บังคับหรือไม่ในการตอบกลับฟังก์ชัน initialize
เมื่อแก้ไขการปฏิบัติตามสัญญาเกี่ยวกับฟังก์ชันการสร้างรายได้แล้ว คุณต้องดำเนินการต่อไปนี้
ซ่อนโซลูชันการสร้างรายได้ที่แสดงผล
แสดงผลว่าผู้ใช้มีสิทธิ์เข้าถึงเนื้อหาในหน้าหรือไม่ ซึ่งจะเป็นตัวกำหนดว่า 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(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;
}
คำจำกัดความของ Enum
ส่วนนี้จะแสดงคำจำกัดความของ Enum ทั้งหมดใน 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 ดังนี้
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 | 24/07/2023 | การเปิดตัว Monetization Provider API ครั้งแรก |