이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Monetization Provider API

버전: 1.0.0

소개

수익 창출 서비스 공급업체 클라이언트 API를 사용하면 자체 수익 창출 솔루션을 Ad Manager의 개인 정보 보호 및 메시지와 통합할 수 있습니다.

자체 수익 창출 솔루션을 Offerwall과 통합하려면 다음 단계를 따르세요.

Ad Manager의 개인 정보 보호 및 메시지 탭에서 Offerwall에 '맞춤 선택' 옵션을 사용 설정합니다.
Offerwall이 게시된 사이트에 맞춤 JavaScript를 추가합니다. 구현 세부정보는 아래 섹션을 참고하세요.
이 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	호출 시 사용자의 사용 권한 상태를 가져옵니다.
수익 창출	웹페이지에서 맞춤 수익 창출 솔루션을 렌더링합니다. 수익 창출 솔루션은 어떤 형태로든 제공될 수 있으며, 보상형 광고, 구독 서비스 대화상자 등이 그 예입니다.
destroy	초기화 시 실행 중인 리소스 또는 작업과 함께 제공자를 소멸합니다. 소멸 시 Offerwall은 더 이상 제공자 메서드를 호출하지 않습니다.

메서드 정의

각 수익 창출 서비스 제공업체 메서드의 정의는 아래에 자세히 설명되어 있습니다.

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>

호출 시 사용자의 사용 권한 상태를 가져옵니다. 사용자가 웹사이트에 무료로 액세스할 수 있어야 하므로 사용자가 자격 요건을 충족하는 경우 Offerwall이 숨겨집니다.

예:

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

수익 올리기

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

수익 창출 솔루션을 렌더링하고 사용자의 수익 창출 작업을 처리합니다. 수익 창출은 보상형 광고, 정기 결제 서비스 등 다양한 형태로 이루어질 수 있습니다. Offerwall에서 이 메서드를 호출하면 약속이 해결될 때까지 Offerwall이 숨겨집니다. 따라서 약속이 해결될 때까지 페이지 콘텐츠를 차단하는 것은 제공업체의 책임입니다. 약속이 해결되면 제공업체는 웹페이지에 더 이상 표시되지 않아야 합니다.

수익 창출 솔루션 내에서 InitializeParams에 제공된 추천 언어 코드와 스타일을 사용하는 것이 좋습니다. 이렇게 하면 Offerwall과 제공업체 간에 원활한 시각적 환경을 보장할 수 있습니다.

Offerwall은 수익 창출 포털 매개변수를 설정하여 액세스하려는 포털을 나타냅니다. 사용할 수 있는 두 가지 포털 유형에는 선택사항이 아닌 PORTAL_PRIMARY_ACCESS와 선택사항인 PORTAL_SIGN_IN가 있습니다. initialize 함수에 대한 응답에서 선택적 포털 PORTAL_SIGN_IN를 지원하는지 여부를 나타낼 수 있습니다.

수익 창출 함수 약속을 해결할 때 다음을 실행해야 합니다.

렌더링된 수익 창출 솔루션을 숨깁니다.
사용자가 페이지 콘텐츠에 액세스할 권한이 있는지 여부를 반환합니다. 이 값에 따라 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`

수익 창출 함수의 매개변수 유형입니다.

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

enum 정의

이 섹션에는 API의 모든 enum 정의가 나열되어 있습니다.

`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일	수익 창출 서비스 제공업체 API의 최초 출시 버전입니다.