Monetization Provider API

Sürüm: 1.0.0

Giriş

Para kazanma sağlayıcı istemci API'si, kendi para kazanma çözümünüzü Ad Manager'daki Gizlilik ve Mesajlaşma ile entegre etmenize olanak tanır.

Kendi para kazanma çözümünüzü Offerwall ile entegre etmek için aşağıdaki adımları uygulayın:

  • Ad Manager'daki Gizlilik ve Mesajlaşma sekmesinden Offerwall için"Özel Seçim" seçeneğini etkinleştirin.

  • Offerwall'un yayınlandığı siteye özel JavaScript ekleyin. Uygulama ayrıntılarını aşağıdaki bölümlerde bulabilirsiniz.

  • Bu JavaScript, aşağıda tanımlandığı şekilde özel bir para kazanma sağlayıcısını örneklemelidir ve sağlayıcıyı pencerede kayıt anahtarıyla ('publisherCustom') Gizlilik ve Mesajlaşma'ya kaydetmelidir.

Sözlük

Terim Tanım
Para Kazanma Sağlayıcısı Özel para kazanma çözümünüzü sağlayan yerel bir JavaScript nesnesi. Örneğin, abonelik hizmeti, mikro ödeme hizmeti ve daha fazlasını sağlayabilirsiniz. Offerwall, özel çözümünüzle içeriğinizden para kazanmak için sağlayıcınızın yöntemlerini çağırır.
Hak Para kazanma çözümünüz tarafından, para kazanma işlemi tamamlayan kullanıcılara verilen bir ödül. Bu API kapsamında, kullanıcılara Offerwall'u görmeden web sitenizin içeriğine erişim hakkı veren bir ayrıcalık verilir. Özel para kazanma seçeneğinizi belirleyen kullanıcılara ücretsiz sayfa yüklemelerinin sayısını veya süreyi siz belirlersiniz.
Para Kazanma Portalı Para kazanma akışına giriş noktası. Portallar, para kazanma çözümünüzün sunduğu ayrı akışları tanımlar. Örneğin, bir portal "para kazanma" için olabilir. Bu portalda kullanıcılar hizmetinize abone olabilir. Başka bir portal, kullanıcının mevcut bir aboneliğe erişmek için oturum açabileceği "oturum açma" portalı olabilir.
Kayıt Anahtarı Para kazanma sağlayıcının, sağlayıcı uygulamanızı sayfa yükleme sırasında Google Gizlilik ve Mesajlaşma'ya kaydetmek için kullanılan tanımlayıcısıdır.

Örnek API Uygulaması

Aşağıda, para kazanma sağlayıcıyı tanımlayan, örnekleyen ve Google Gizlilik ve Mesajlaşma'ya kaydeden çalışan bir uygulama örneği verilmiştir.

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

Yukarıdaki kod snippet'i, bir para kazanma sağlayıcıyı Gizlilik ve Mesajlaşma ile entegre etmek için gereken her şeyi içeren bir iskelet uygulamadır. Her sağlayıcı işlevi için, kendi uygulamanızla değiştirmekten sorumlu olduğunuz örnek kod eklendiğini unutmayın.

Yöntem Özeti

Para kazanma sağlayıcı, temel işlev grubunu sunarak web sayfalarında para kazanma işlevi sağlayan bir nesnedir. Bu işlevler aşağıda daha ayrıntılı olarak açıklanmıştır.

Yöntem Özet
initialize Para kazanma sağlayıcıyı ve para kazanma işlemlerini gerçekleştirmek için gereken tüm kaynakları başlatın.
getUserEntitlementState Kullanıcının, çağrı sırasındaki hak durumu bilgisini alın.
monetize Özel para kazanma çözümünüzü web sayfasında oluşturun. Para kazanma çözümünüz, ödüllü reklam, abonelik hizmeti iletişim kutusu gibi çeşitli biçimlerde olabilir.
destroy Başlatma sırasında çalışan tüm kaynaklar veya işlerle birlikte sağlayıcıyı yok edin. Offerwall, yok edildikten sonra artık sağlayıcı yöntemlerini çağırmaz.

Yöntem Tanımları

Her para kazanma sağlayıcı yönteminin tanımı aşağıda daha ayrıntılı olarak açıklanmıştır.

ilk kullanıma hazırlama

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Para kazanma sağlayıcısını başlatın. İlkleştirildikten sonra sağlayıcı, diğer sağlayıcı işlevlerine yanıt vermeye hazır olmalıdır. Bu işlevin diğer sağlayıcı işlevlerinden önce çağrılacağı garanti edilir ve belirli bir sayfa yüklenmesinde en fazla bir kez çağrılması beklenir.

Örnek:

  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>

Kullanıcının, çağrı sırasındaki hak durumu bilgisini alın. Kullanıcı web sitesine ücretsiz erişim alacağı için Offerwall, kullanıcının hakkı varsa gizlenir.

Örnek:

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

para kazanmak

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Para kazanma çözümünüzü oluşturun ve kullanıcının para kazanma işlemlerini yönetin. Para kazanma, ödüllü reklam, abonelik hizmeti ve daha birçok biçimde olabilir. Bu yöntem Offerwall tarafından çağrıldıktan sonra, Offerwall, söz çözülene kadar gizlenir. Bu nedenle, söz çözülene kadar sayfa içeriğini kısıtlamak sağlayıcının sorumluluğundadır. Taahhüt çözüldükten sonra sağlayıcının, web sayfasında artık görünmediğinden de emin olması gerekir.

Para kazanma çözümünüzde InitializeParams içinde önerilen dil kodunu ve stilleri kullanmanız önemle tavsiye edilir. Bu sayede Offerwall ile sağlayıcı arasında sorunsuz bir görsel deneyim sağlanır.

Offerwall, para kazanma portalı parametresini hangi portala erişmek istediğini belirtecek şekilde ayarlar. Kullanabileceğiniz iki portal türü vardır: isteğe bağlı olmayan PORTAL_PRIMARY_ACCESS ve isteğe bağlı PORTAL_SIGN_IN. initialize işlevine verdiğiniz yanıtta isteğe bağlı PORTAL_SIGN_IN portalını destekleyip desteklemediğinizi belirtebilirsiniz.

Para kazanma işlevi için verdiğiniz sözü yerine getirdikten sonra şunları yapmanız gerekir:

  • Oluşturulan para kazanma çözümünüzü gizleyin.

  • Kullanıcının sayfa içeriğine erişip erişemeyeceğini döndürür. Bu, Offerwall'un gösterilmeye devam edip etmeyeceği veya gizlenip gizlenmeyeceğini belirler.

  • Kullanıcı etkileşimiyle ilgili ek verileri (varsa) döndürün (ör. ödenen tutar, hak kazanma türü ve değeri, para kazanmanın tekrarı).

Örnek:

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

kaldırmak

destroy(destroyParams:DestroyParams): void

Sağlayıcıyı imha edin. Bu işlevin, sağlayıcının yaşam döngüsünde en son çağrılacağı garanti edilir ve belirli bir sayfa yüklemesinde en fazla bir kez çağrılacağını bekleyebilirsiniz.

Örnek:

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

Tür Tanımları

API'deki her veri türünün tanımı aşağıda daha ayrıntılı olarak açıklanmıştır.

Nesne Tanımları

Bu bölümde, API'deki tüm nesne tanımları listelenmektedir.

InitializeParams

initialize işlevinin parametre türü.

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

Stilleri tanımlama türü.

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

InitializeResponse

initialize işlevinin yanıt türü.

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

Para kazanma işlevinin parametre türü.

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

Para kazanma işlevinin yanıt türü.

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

Belirli bir para biriminde para tutarını tanımlamak için kullanılan tür. Orijinal money.proto tanımını inceleyin.

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 işlevinin parametre türü.

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

Enum Tanımları

Bu bölümde, API'deki tüm enum tanımları listelenmektedir.

googlefc.monetization.UserEntitlementStateEnum

Hak talebinin numaralandırılması, kullanıcının para kazanma sağlayıcısı olabileceğini belirtir.

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

Bir sağlayıcının destekleyebileceği farklı para kazanma portallarının veya para kazanma giriş noktalarının listesi. Para kazanma portalları hakkında daha fazla bilgi için terimler sözlüğüne göz atı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

Bir para kazanma sağlayıcının kullanıcıya verebileceği farklı hak türlerinin listesi.

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

Para kazanma sağlayıcının silinmesinin nedenlerini listeler.

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

Kullanıcının yaptığı bir işlem sonrasında başlatılabilecek farklı para kazanma tekrarı ritimlerinin listesi.

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

Sağlayıcı Kaydı

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

Para kazanma sağlayıcılarını kaydetmek için kullanılan pencere düzeyinde JavaScript nesnesi. Kayıt, statik kayıt anahtarıyla anahtarlanmış oluşturulmuş sağlayıcı nesnenizin window ad alanının altındaki bir sicil dairesine iletilmesini içerir: 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());

Sürüm Geçmişi

Sürüm Yayın Tarihi Özet
1.0.0 24.07.2023 Para kazanma sağlayıcı API'sinin ilk sürümü.