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 under the Simplified Framework for EU consent
  • query the ad blocking 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 whether to proceed with Funding Choices messaging. This functionality is supported for all message types.
googlefc.suppressConsentMessage boolean Suppresses the consent message from showing if set before the Funding Choices script loads. This functionality is only supported for messages shown under the Simplified Framework for EU consent.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue Reference to the callback queue for asynchronous execution of consent and ad blocking related queries.
googlefc.CallbackQueue Object The type of the Funding Choices callback queue object.
googlefc.ConsentStatusEnum !Object<string, number> An enum to represent the user's consent state under the Simplified Framework for EU consent.
googlefc.AdBlockerStatusEnum !Object<string, number> An enum to represent the user's ad blocker state.
googlefc.WhitelistStatusEnum !Object<string, number> An enum to represent the user's whitelist state.

Method Summaries

Name Type Definition
googlefc.getConsentStatus() number Returns a value in the ConsentStatusEnum depending on the consent choice of the user. This method is only supported if using the Simplified Framework for EU consent.
googlefc.getConsentedProviderIds() !Array<string> Returns the list of ad tech provider IDs that the user has explicitly consented to for personalized ads. This method is only supported if using the Simplified Framework for EU consent.
googlefc.showRevocationMessage() void Clears the consent record and reloads the googlefc script to show the consent message applicable to the user.
googlefc.getAdBlockerStatus() number Returns a value in the AdBlockerStatusEnum depending on the ad blocking status of the user.
googlefc.getWhitelistStatus() number Returns a value in the WhitelistStatusEnum depending on the whitelist status of the user.

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 message, or with any other message type.

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 configured under the Simplified Framework for EU consent 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<!Object<string, function()>> | !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.

Since different types of data become available at different times, a function should be added as a map, with one of the below strings as the key and the function to be executed as the value.

Supported keys:

  • 'AD_BLOCK_DATA_READY'
  • 'CONSENT_DATA_READY'

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 any function with a map key of CONSENT_DATA_READY. From this point on, execution of any subsequently added consent functions are synchronous.

When ad blocking data becomes available later in the flow, any function with a map key of AD_BLOCK_DATA_READY will be executed and any subsequently added ad blocking functions are synchronous.


googlefc.CallbackQueue Object

Method summary:

Name Type Parameter Return type Role
push(data) number data: A key-value pair with the key as one of the data availability types and the value as a JavaScript function to be executed. The acceptable data availability keys are `CONSENT_DATA_READY` and `AD_BLOCK_DATA_READY`. The number of commands added so far. This returns the current length of the array. Executes the function passed in, in the order in which the data becomes available, then by the order in which 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({
    'CONSENT_DATA_READY':
    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 under the Simplified Framework for EU consent. 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,
  // Some sort of error state - failed to retrieve consent.
  NO_CONSENT: 4,
  // 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,
};

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

Represents the different ad blocking states of the user. The different states are:

googlefc.AdBlockerStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // The user was running an extension level ad blocker.
  EXTENSION_AD_BLOCKER: 1,
  // The user was running a network level ad blocker.
  NETWORK_LEVEL_AD_BLOCKER: 2,
  // The user was not blocking ads.
  NO_AD_BLOCKER: 3,
};

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

Represents the different ad blocking whitelist states of the user. The different states are:

googlefc.WhitelistStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // User is currently using an ad blocker, was never using an ad blocker, or
  // whitelisted, but not because they saw the Funding Choices messaging.
  NOT_WHITELISTED: 1,
  // User is no longer using an ad blocker after seeing the ad blocking message.
  WHITELISTED: 2,
};

Methods: explanations and examples

googlefc.getConsentStatus(): {number}

Returns a value in the ConsentStatusEnum depending on the consent choice made by the user under the Simplified Framework for EU consent. The key that should be specified for this function is CONSENT_DATA_READY.

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({
    'CONSENT_DATA_READY':
    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.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 under the Simplified Framework for EU consent. 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 in the Providers file from here. The key that should be specified for this function is CONSENT_DATA_READY.

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({
    'CONSENT_DATA_READY':
    function() {
      doSomething(googlefc.getConsentedProviderIds());
    }
  });
</script>

googlefc.showRevocationMessage(): {void}

Clears the current consent record and shows the consent message that is applicable for this user. The key that should be specified for this function is CONSENT_DATA_READY.

Example

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

googlefc.getAdBlockerStatus(): {number}

Returns a value in the AdBlockerStatusEnum depending on the ad blocking status of the user. The key that should be specified for this function is AD_BLOCK_DATA_READY.

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({
    'AD_BLOCK_DATA_READY':
    function() {
      switch (googlefc.getAdBlockerStatus()) {
          case googlefc.AdBlockerStatusEnum.EXTENSION_LEVEL_AD_BLOCKER:
          case googlefc.AdBlockerStatusEnum.NETWORK_LEVEL_AD_BLOCKER:
            // Insert handling for cases where the user is blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER:
            // Insert handling for cases where the user is not blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.UNKNOWN:
            // Insert handling for unknown cases.
            break;
      }
    }
  });
</script>

googlefc.getWhitelistStatus(): {number}

Returns a value in the WhitelistStatusEnum depending on the whitelist status of the user. The key that should be specified for this function is AD_BLOCK_DATA_READY.

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({
    'AD_BLOCK_DATA_READY':
    function() {
      switch (googlefc.getWhitelistStatus()) {
        case googlefc.WhitelistStatusEnum.NOT_WHITELISTED:
          // Insert handling for cases where the user has not whitelisted.
          // The user may have never been an ad blocker.
          break;
        case googlefc.WhitelistStatusEnum.WHITELISTED:
          // Insert handling for cases where the user saw the ad blocking
          // message and whitelisted the site.
          break;
        case googlefc.WhitelistStatusEnum.UNKNOWN:
          // Insert handling for unknown cases.
          break;
      }
    }
  });
</script>