Cette page a été traduite par l'API Cloud Translation.

API Monetization Provider

Version: 1.0.0

Introduction

L'API client du fournisseur de monétisation vous permet d'intégrer votre propre solution de monétisation à Confidentialité et messages dans Ad Manager.

Pour intégrer votre propre solution de monétisation à l'Offerwall, procédez comme suit:

Activez l'option "Choix personnalisé" pour l'Offerwall dans l'onglet "Confidentialité et messages" d'Ad Manager.
Ajoutez du code JavaScript personnalisé sur le site sur lequel l'Offerwall est publié. Vous trouverez des informations détaillées sur l'implémentation dans les sections ci-dessous.
Ce code JavaScript doit instancier un fournisseur de monétisation personnalisé tel que défini ci-dessous et enregistrer le fournisseur auprès de Confidentialité et messages dans la fenêtre avec la clé d'enregistrement: 'publisherCustom'.

Glossaire

Terme	Définition
Fournisseur de solutions de monétisation	Objet JavaScript natif qui fournit votre solution de monétisation personnalisée. Par exemple, vous pouvez proposer un service d'abonnement, un service de micropaiements, etc. L'Offerwall appelle les méthodes de votre fournisseur pour monétiser votre contenu avec votre solution personnalisée.
Droit d'accès	Récompense accordée aux utilisateurs par votre solution de monétisation pour avoir effectué une action de monétisation. Dans le cadre de cette API, un droit d'accès permet aux utilisateurs d'accéder au contenu de votre site Web sans voir l'Offerwall. Vous déterminez le nombre de chargements de pages sans frais ou la durée accordée aux utilisateurs qui sélectionnent votre choix de monétisation personnalisée.
Portail de monétisation	Point d'entrée dans un flux de monétisation. Les portails définissent les flux distincts proposés par votre solution de monétisation. Par exemple, un portail peut être dédié à la "monétisation", où l'utilisateur peut s'abonner à votre service. Un autre portail peut être destiné à la connexion, où l'utilisateur peut se connecter pour accéder à un abonnement existant.
Clé d'enregistrement	Identifiant d'un fournisseur de monétisation, utilisé pour enregistrer l'implémentation de votre fournisseur auprès de la fonctionnalité Confidentialité et messages de Google au moment du chargement de la page.

Exemple d'implémentation d'API

Voici un exemple d'implémentation fonctionnelle qui définit un fournisseur de monétisation, l'instancie et l'enregistre auprès de Confidentialité et messages de 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>

L'extrait de code ci-dessus est une implémentation squelette qui inclut tout ce qui est nécessaire pour intégrer un fournisseur de monétisation à la section "Confidentialité et messages". Notez que pour chaque fonction du fournisseur, un exemple de code a été ajouté que vous devez remplacer par votre propre implémentation.

Récapitulatif sur la méthode

Un fournisseur de monétisation est un objet qui fournit des fonctionnalités de monétisation sur les pages Web en exposant un ensemble de fonctions de base. Ces fonctions sont décrites plus en détail ci-dessous.

Méthode	Résumé
initialiser	Initialisez le fournisseur de monétisation, ainsi que toutes les ressources requises pour effectuer des actions de monétisation.
getUserEntitlementState	Obtenez l'état des droits d'accès de l'utilisateur au moment de l'appel.
monetize	Affichez votre solution de monétisation personnalisée sur la page Web. Votre solution de monétisation peut prendre n'importe quelle forme, par exemple une annonce avec récompense, une boîte de dialogue de service d'abonnement, etc.
destroy	Détruisez le fournisseur, ainsi que toutes les ressources ou tâches en cours d'exécution lors de l'initialisation. Lors de la destruction, l'Offerwall n'appelle plus aucune méthode du fournisseur.

Définitions des méthodes

La définition de chaque méthode de fournisseur de monétisation est décrite plus en détail ci-dessous.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Initialisez le fournisseur de monétisation. Une fois initialisé, le fournisseur doit être prêt à répondre à toutes les autres fonctions du fournisseur. Cette fonction est appelée avant toute autre fonction du fournisseur. Elle ne doit être appelée qu'une seule fois lors d'un chargement de page donné.

Exemple :

  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>

Obtenez l'état des droits d'accès de l'utilisateur au moment de l'appel. L'Offerwall est masqué si l'utilisateur est éligible, car il doit bénéficier d'un accès sans frais au site Web.

Exemple :

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

Monétiser

monetize(monetizeParams:MonetizeParams): Promise<MonetizeResponse>

Affichez votre solution de monétisation et gérez les actions de monétisation de l'utilisateur. La monétisation peut prendre n'importe quelle forme, qu'il s'agisse d'une annonce avec récompense, d'un service d'abonnement, etc. Une fois cette méthode appelée par l'Offerwall, l'Offerwall est masqué jusqu'à ce que la promesse soit résolue. Par conséquent, il incombe au fournisseur de bloquer le contenu de la page jusqu'à ce que la promesse soit résolue. Une fois la promesse résolue, le fournisseur doit également s'assurer qu'il n'est plus visible sur la page Web.

Nous vous recommandons vivement d'utiliser le code de langue et les styles suggérés fournis dans InitializeParams dans votre solution de monétisation. Cela garantit une expérience visuelle fluide entre l'Offerwall et le fournisseur.

L'Offerwall définit le paramètre du portail de monétisation pour indiquer le portail auquel il souhaite accéder. Les deux types de portails disponibles sont PORTAL_PRIMARY_ACCESS, qui n'est pas facultatif, et PORTAL_SIGN_IN, qui l'est. Vous pouvez indiquer si vous acceptez le portail facultatif PORTAL_SIGN_IN dans votre réponse à la fonction initialize.

Lorsque vous résolvez la promesse de la fonction de monétisation, vous devez:

Masquer votre solution de monétisation affichée
Indique si l'utilisateur est autorisé à accéder au contenu de la page. Ce paramètre détermine si l'Offerwall continue de s'afficher ou s'il est masqué.
Renvoie toutes les données supplémentaires sur l'interaction utilisateur, le cas échéant, telles que le montant payé, le type et la valeur des droits d'accès, ainsi que la fréquence de monétisation.

Exemple :

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

détruire

destroy(destroyParams:DestroyParams): void

Détruisez le fournisseur. Cette fonction est appelée en dernier dans le cycle de vie du fournisseur. Vous devez vous attendre à ce qu'elle soit appelée au maximum une fois pour un chargement de page donné.

Exemple :

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

Définitions des types

La définition de chaque type de données de l'API est décrite plus en détail ci-dessous.

Définitions d'objets

Cette section liste toutes les définitions d'objets de l'API.

`InitializeParams`

Type de paramètre pour la fonction initialize (Initialiser).

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`

Type de définition des styles.

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

`InitializeResponse`

Type de réponse pour la fonction initialize (Initialiser).

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`

Type de paramètre pour la fonction 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`

Type de réponse de la fonction 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`

Type permettant de définir un montant d'argent dans une devise spécifique. Consultez la définition d'origine de 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`

Type de paramètre pour la fonction destroy.

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

Définitions d'énumérations

Cette section liste toutes les définitions d'énumération de l'API.

`googlefc.monetization.UserEntitlementStateEnum`

L'énumération du droit d'accès indique qu'un utilisateur peut être inscrit auprès d'un fournisseur de monétisation.

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`

Énumération des différents portails de monétisation, ou points d'entrée de monétisation, qu'un fournisseur peut prendre en charge. Pour en savoir plus sur les portails de monétisation, consultez le glossaire.

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`

Énumération des différents types d'autorisations qu'un fournisseur de monétisation peut accorder à un utilisateur.

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`

Énumération des raisons pour lesquelles un fournisseur de monétisation peut être supprimé.

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`

Énumération des différentes fréquences de récurrence de la monétisation qui peuvent être lancées en fonction d'une action de l'utilisateur.

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

Enregistrement du fournisseur

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

Objet JavaScript au niveau de la fenêtre utilisé pour enregistrer les fournisseurs de monétisation. L'enregistrement inclut la transmission de votre objet de fournisseur instancié associé à une clé d'enregistrement statique à un registre situé sous l'espace de noms de fenêtre :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());

Historique des versions

Version	Date de sortie	Résumé
1.0.0	07/24/2023	Version initiale de l'API Monetization Provider.

API Monetization Provider Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Introduction

Glossaire

Exemple d'implémentation d'API

Récapitulatif sur la méthode

Définitions des méthodes

initialize

getUserEntitlementState

Monétiser

détruire

Définitions des types

Définitions d'objets

Définitions d'énumérations

Enregistrement du fournisseur

Historique des versions

API Monetization Provider