דף זה תורגם על ידי Cloud Translation API.

Monetization Provider API

גרסה: 1.0.0

מבוא

ממשק ה-API של לקוח ספק המונטיזציה מאפשר לכם לשלב את פתרון המונטיזציה שלכם עם פרטיות והודעות ב-Ad Manager.

כדי לשלב פתרון מונטיזציה משלכם עם Offerwall:

מפעילים את האפשרות 'בחירה מותאמת אישית' עבור Offerwall בכרטיסייה 'פרטיות והודעות' ב-Ad Manager.
מוסיפים קוד JavaScript בהתאמה אישית לאתר שבו פורסם ה-Offerwall. פרטי ההטמעה מפורטים בקטעים הבאים.
קוד ה-JavaScript הזה אמור ליצור מופע של ספק מונטיזציה בהתאמה אישית כפי שמוגדר בהמשך, ולרשום את הספק בחלון 'פרטיות והודעות' באמצעות מפתח הרישום: 'publisherCustom'.

מילון מונחים

מונח	הגדרה
ספק שירותי מונטיזציה	אובייקט JavaScript מקורי שמספק את פתרון המונטיזציה בהתאמה אישית. לדוגמה, אתם יכולים לספק שירות מינוי, שירות של תשלומי מיקרו ועוד. הודעות ה-Offerwall מפעילות את השיטות של הספק כדי לייצר הכנסות מהתוכן שלכם באמצעות הפתרון המותאם אישית.
זכאות	תגמול שמוענק למשתמשים על ידי פתרון המונטיזציה שלכם בתמורה לביצוע פעולת מונטיזציה כלשהי. בהיקף של ה-API הזה, הרשאה מעניקה למשתמשים גישה לתוכן באתר שלכם בלי שהם יראו את Offerwall. אתם קובעים את מספר הטעינות של דפים בחינם או את משך הזמן שהמשתמשים יכולים ליהנות ממנו אם הם בוחרים באפשרות המותאמת אישית שרציתם ליישם למונטיזציה.
פורטל המונטיזציה	נקודת כניסה לתהליך מונטיזציה. פורטלים מגדירים את תהליכי העבודה הנפרדים שמוצעים על ידי פתרון המונטיזציה. לדוגמה, פורטל אחד יכול לשמש ל'מונטיזציה', שבו המשתמש יכול להירשם לשירות שלכם. פורטל אחר יכול לשמש ל'כניסה', שבו המשתמש יכול להיכנס כדי לגשת למינוי קיים.
מפתח רישום	המזהה של ספק המונטיזציה, שמשמש לרישום ההטמעה של הספק ב'פרטיות והודעות' של Google בזמן טעינת הדף.

דוגמה להטמעת API

לפניכם דוגמה להטמעה שפועלת, שמגדירה ספק מונטיזציה, יוצרת מופע שלו ומרשמת אותו ב-Privacy & messaging של 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>

מאתחלים את ספק שירותי המונטיזציה. אחרי האיפוס, הספק אמור להיות מוכן להגיב לכל פונקציות אחרות של הספק. הפונקציה הזו מופעלת לפני כל פונקציית ספק אחרת, וניתן לצפות שהיא תופעל לכל היותר פעם אחת בחיוב של דף נתון.

דוגמה:

  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 מפעיל את השיטה הזו, הוא מוסתר עד שההבטחה מתקבלת. לכן, האחריות של הספק היא לחסום את תוכן הדף עד שהבעיה תיפתר. אחרי שהבעיה נפתרה, הספק צריך לוודא שהוא לא מופיע יותר בדף האינטרנט.

מומלץ מאוד להשתמש בסגנונות ובקוד השפה המוצעים ב-InitializeParams בתוך פתרון המונטיזציה שלכם. כך תוכלו להבטיח חוויה חזותית חלקה בין Offerwall לבין הספק.

ה-Offerwall מגדיר את הפרמטר של פורטל המונטיזציה כדי לציין לאיזה פורטל הוא רוצה לגשת. שני סוגי הפורטלים הזמינים הם 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

מוחקים את הספק. הפונקציה הזו מופעלת תמיד בסוף מחזור החיים של הספק, וצריך לצפות שהיא תופעל לכל היותר פעם אחת בכל טעינה של דף נתון.

דוגמה:

  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)

בקטע הזה מפורטות כל הגדרות המאפיינים המפורטים ב-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	24.07.2023	הגרסה הראשונית של ממשק ה-API של ספק שירותי המונטיזציה.

Monetization Provider API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

מילון מונחים

דוגמה להטמעת API

סיכום של השיטה

הגדרות של שיטות

אתחול

getUserEntitlementState

ייצור הכנסות

כיבוי סופי

הגדרות טיפוס

הגדרות אובייקטים

הגדרות של טיפוסים בני מנייה (enum)

רישום הספק

היסטוריית גרסאות

Monetization Provider API