Funding Choices JavaScript API

Introduction

The Funding Choices API provides a library to interact with the Funding Choices tool. The API has general functionality, but also functionality specific to consent gathering. It can:

  • control when to suppress the consent message (synchronously or asynchronously)
  • query the consent status of a user
  • allow a user to revoke consent (if applicable)
  • suppress the Funding Choices message for any given user

googlefc is the global namespace that the Funding Choices tag uses for its API.

Field Summaries

Name Type Definition
googlefc.controlledMessagingFunction function(!Object) A function that determines when to proceed (or not) with Funding Choices messaging.
googlefc.suppressConsentMessage boolean Suppresses the consent message from showing if set before the Funding Choices script loads.
googlefc.callbackQueue !Array<function()> | !googlefc.CallbackQueue Reference to the callback queue for asynchronous execution of consent related queries.
googlefc.CallbackQueue Object The type of the Funding Choices callback queue object.
googlefc.ConsentStatusEnum !Object<string, number> An enum to represent the different consent states that the user can be in.

Method Summaries

Name Type Definition
googlefc.getConsentStatus() number Returns a value in the ConsentStatusEnum depending on the consent choice of the user.
googlefc.getConsentedProviderIds() !Array<string> Returns the list of ad tech provider IDs that the user has explicitly consented to for personalized ads.
googlefc.showRevocationMessage() void Clears the consent record and reloads the googlefc script to show the consent message.

Fields: explanations and examples

googlefc.controlledMessagingFunction {function(!Object)}

A function that determines whether to proceed (or not) with Funding Choices messaging. It can be used to gate the message rendering on a dynamic condition (e.g., time of day, subscriber status), and can be used in conjunction with an Ad Blocking Custom Choice wall, or on its own.

googlefc.controlledMessagingFunction must be set before the Funding Choices tag loads to guarantee correct functionality; but the call to message.proceed can happen asynchronously, after the Funding Choices script has already loaded. This function is used to gate the rendering of a Funding Choices message on a condition (e.g., subscriber status). The following is an asynchronous example in ES5 format assuming that a call to user.isSubscriber() is an asynchronous call that returns a Promise.

Synchronous example

The following is a synchronous example of googlefc.controlledMessagingFunction that gates the message based on the time of day.

<head>
  <script>
    // Make sure that the properties exist on the window.
    window.googlefc = window.googlefc || {};
    window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

    // To guarantee functionality, this must go before the FC tag on the page.
    googlefc.controlledMessagingFunction = (message) => {
     const today = new Date();
     // If it is in between 0 and 12 o’clock, show the message. Otherwise, do not.
     if (today.getHours() < 12) {
       message.proceed(true);
     } else {
       message.proceed(false);
     }
    };
  </script>
  <FC tag goes here>
</head>

Asynchronous example

The following is an asynchronous example of googlefc.controlledMessagingFunction that assumes that a call to user.isSubscriber() is an asynchronous call that returns a Promise.

<head>
  <script>
    // Make sure that the properties exist on the window.
    window.googlefc = window.googlefc || {};
    window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

    // To guarantee functionality, this must go before the FC tag on the page.
    googlefc.controlledMessagingFunction = (message) => {
     user.isSubscriber().then(
       function (isSubscriber) {
         // Do not show the message if a user is a subscriber.
         if (isSubscriber) {
           message.proceed(false);
         } else {
           message.proceed(true);
         }
       }
     );
  </script>
  <FC tag goes here>
</head>

googlefc.suppressConsentMessage {boolean}

Suppresses the consent message if set before the Funding Choices script loads.

Example

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Set the boolean to true before the tag triggers to guarantee functionality.
  // Note: googlefc.getConsentStatus() will return CONSENT_NOT_REQUIRED in this case.
  googlefc.suppressConsentMessage = true;
</script>

<FC tag goes here>

googlefc.callbackQueue {!Array<function()> | !googlefc.CallbackQueue}

Reference to the global callback queue for asynchronous execution of Funding Choices-related calls. The only supported way to invoke any function is by adding it to the callbackQueue.

When the Funding Choices JavaScript is loaded and user consent is known (either from a prior execution or once the user interacts with the consent message), it looks through the array and executes all the functions. From this point on, execution of any subsequently added functions is synchronous.


googlefc.CallbackQueue Object

Method summary:

Name Type Parameter Return type Role
push(f) number f: A JavaScript function to be executed. The number of commands added so far. This returns the current length of the array. Executes the function passed in, in the order that these functions are added to the queue.

Example

<FC tag goes here>
<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push(
    function() {
      if (googlefc.getConsentStatus() == googlefc.ConsentStatusEnum.CONSENTED_TO_PERSONALIZED_ADS ||
          googlefc.getConsentStatus() == googlefc.ConsentStatusEnum.CONSENT_NOT_REQUIRED) {
        // Insert/trigger 3rd party ad tag.
      }
    });
</script>

googlefc.ConsentStatusEnum {!Object<string, number>}

Represents the different consent states of the user. The different states are:

googlefc.ConsentStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  CONSENTED_TO_PERSONALIZED_ADS: 1,
  CONSENTED_TO_NON_PERSONALIZED_ADS: 2,
  // Contributor user.
  CONTRIBUTOR: 3,
  // Some sort of error state - failed to retrieve consent.
  NO_CONSENT: 4,
  // When Funding Choices determined that prompting for consent was not
  // required, e.g.:
  //     * Publisher suppressed the consent message.
  //     * User was from a non-consent-required region.
  CONSENT_NOT_REQUIRED: 5,
};

Methods: explanations and examples

googlefc.getConsentStatus(): {number}

Returns a value in the ConsentStatusEnum depending on the consent choice of the user.

Example

<FC tag goes here>
<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push(function() {
    switch (googlefc.getConsentStatus()) {
        case googlefc.ConsentStatusEnum.CONSENTED_TO_PERSONALIZED_ADS:
        case googlefc.ConsentStatusEnum.CONSENT_NOT_REQUIRED:
          // Insert 3rd party ad tag.
          break;
        case googlefc.ConsentStatusEnum.CONSENTED_TO_NON_PERSONALIZED_ADS:
          // Load 3rd party ad tag that supports non-personalized ads.
          break;
        case googlefc.ConsentStatusEnum.CONTRIBUTOR:
        case googlefc.ConsentStatusEnum.UNKNOWN:
        case googlefc.ConsentStatusEnum.NO_CONSENT:
          // Don’t load ads.
          break;
    }
  });
</script>

googlefc.getConsentedProviderIds(): {!Array<string>}

Returns the IDs of the ad technology providers that the user has explicitly consented to for personalized ads. These IDs include those of manually-added providers, which have the prefix fc_company, and IDs of providers selected through the Ad Manager and AdSense front ends, which map to the entries here.

Example

<FC tag goes here>
<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push(
    function() {
      doSomething(googlefc.getConsentedProviderIds());
    });
</script>

googlefc.showRevocationMessage(): {void}

Clears the current consent record and shows the consent message.

Example

<a href="javascript:googlefc.callbackQueue.push(googlefc.showRevocationMessage)">
  Click here to revoke
</a>.