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

API Monetization Provider

Version: 1.0.0

Introduction

L'API cliente du fournisseur de monétisation vous permet d'intégrer votre propre solution de monétisation avec Confidentialité et messages dans Ad Manager. À l'heure actuelle, cette API n'est disponible que pour les éditeurs participant à la version bêta fermée d'Offerwall.

Pour intégrer votre propre solution de monétisation à l'Offerwall, suivez ces étapes de configuration du choix personnalisé. En résumé :

Activez l'option "Choix personnalisé" pour l'Offerwall dans l'onglet "Confidentialité et messages" d'Ad Manager.
Ajoutez du code JavaScript personnalisé au site sur lequel l'Offerwall est publié. Vous trouverez des informations 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 l'enregistrer avec l'option "Confidentialité et messages" dans la fenêtre contenant la clé d'inscription: 'publisherCustom'.

Glossaire

Terme	Définition
Fournisseur de monétisation	Objet JavaScript natif qui fournit votre solution de monétisation personnalisée. Par exemple, vous pouvez fournir un service d'abonnement, un service de micropaiement, etc. Le message 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 autorise les utilisateurs à accéder au contenu de votre site Web sans voir le message Offerwall. Vous déterminez le nombre de chargements de pages sans frais ou la durée accordé aux utilisateurs qui sélectionnent votre choix de monétisation personnalisé.
Portail de monétisation	Point d'entrée dans un processus de monétisation. Les portails définissent les flux distincts proposés par votre solution de monétisation. Par exemple, un portail dédié à la monétisation peut permettre à l'utilisateur de s'abonner à votre service. Un autre portail peut servir à se connecter pour permettre à l'utilisateur de se connecter pour accéder à un abonnement existant.
Clé d'enregistrement	Identifiant d'un fournisseur de monétisation, qui permet d'enregistrer l'implémentation de votre fournisseur auprès de l'outil Confidentialité et messages de Google au moment du chargement de la page.

Exemple d'implémentation d'API

Voici un exemple d'implémentation qui définit un fournisseur de monétisation, l'instancie et l'enregistre avec l'outil Confidentialité et messages de Google.

// 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());

L'extrait de code ci-dessus est une implémentation squelette qui comprend tout ce qui est nécessaire pour intégrer un fournisseur de monétisation à la fonctionnalité 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 une fonctionnalité 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é
initialize	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.
monétiser	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 pour un service d'abonnement, etc.).
destroy	Détruisez le fournisseur, ainsi que toutes les ressources ou tâches qui étaient en cours d'exécution lors de l'initialisation. Lors de sa destruction, l'Offerwall n'appelle plus de méthode du fournisseur.

Définitions des méthodes

Vous trouverez ci-dessous la définition de chaque méthode utilisée par un fournisseur de monétisation.

initialize

initialize(initializeParams:InitializeParams): Promise<InitializeResponse>

Initialisez le fournisseur de monétisation. Une fois initialisé, le fournisseur doit être prêt à répondre à toutes ses autres fonctions. L'appel de cette fonction est garanti avant toute autre fonction du fournisseur. On peut s'attendre à ce qu'elle soit appelée au maximum une 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. Le message Offerwall est masqué si l'utilisateur est autorisé, 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 des utilisateurs. La monétisation peut prendre n'importe quelle forme, qu'il s'agisse d'annonces avec récompense, d'un service d'abonnement, etc. Une fois que cette méthode est appelée par l'Offerwall, celui-ci est masqué jusqu'à ce que la promesse soit résolue. Par conséquent, il appartient 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 veiller à ne plus être visible sur la page Web.

Nous vous recommandons vivement d'utiliser le code de langage et les styles suggérés dans la section InitializeParams de 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 incluent PORTAL_PRIMARY_ACCESS (facultatif) et PORTAL_SIGN_IN (facultatif). Vous pouvez indiquer si le portail facultatif PORTAL_SIGN_IN est pris en charge dans votre réponse à la fonction d'initialize.

Une fois la promesse de la fonction de monétisation résolue, vous devez:

Masquez la solution de monétisation affichée.
Indique si l'utilisateur est autorisé ou non à accéder au contenu de la page. Cela détermine si l'Offerwall continue de s'afficher ou s'il est masqué.
Renvoyez toutes les données supplémentaires sur l'interaction utilisateur, le cas échéant, telles que le montant payé, le type et la valeur du droit d'accès, et la récurrence de la 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);
  }

destroy

destroy(destroyParams:DestroyParams): void

Détruisez le fournisseur. Cette fonction sera invoquée en dernier dans le cycle de vie du fournisseur. Vous devez vous attendre à ce qu'elle soit appelée une fois au maximum lors d'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 dans l'API est décrite plus en détail ci-dessous.

Définitions d'objets

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

`InitializeParams`

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

Type permettant de définir 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.

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

`MonetizeParams`

Type de paramètre pour la fonction monetization.

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 pour la fonction monetization.

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 dans une devise spécifique. Voir la définition originale du fichier 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 des énumérations

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

`googlefc.monetization.UserEntitlementStateEnum`

Énumération des droits d'accès auxquels un utilisateur peut appartenir pour 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 est susceptible de prendre en charge. Consultez le glossaire pour en savoir plus sur les portails de monétisation.

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 de droits d'accès 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 détruit.

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 cadences de récurrence de la monétisation qui peuvent être lancées suite à 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 comprend la transmission de l'objet de fournisseur instancié associé à une clé d'enregistrement statique à un registre qui se trouve dans l'espace de noms de la 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	24/07/2023	Version initiale de l'API du fournisseur de monétisation.