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:

• suppress the Funding Choices message for any given user
• query the ad blocking status of a user
• allow a user to revoke consent (if applicable)

You can also use Funding Choices to gather user consent using some industry standard protocols:

• GDPR consent using the IAB TCF v2 spec
• CCPA opt-out using the IAB CCPA spec

In these cases, the consent status is communicated by way of those APIs.

The Funding Choices tag is smart and dynamic, and loads the appropriate consent framework as needed. This means that you won't need to re-tag every time a new regulation or spec is released. See the samples below for how to safely use these APIs with the Funding Choices tag.

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

Note: This reference uses google-closure type annotations. Here is a brief explanation by examples:

• boolean: JavaScript boolean type.
• number|string: Union type. The value is either number or string.
• ?string: Indicates that a value is type string or null. string, number and boolean types are not nullable by default.
• Array<string>: An array of strings.
• googlefc.CallbackQueue: Object of class googlefc.CallbackQueue.
• !googlefc.CallbackQueue: Indicates that a value is type googlefc.CallbackQueue and not null. All object types are nullable by default.
• !Array<!googlefc.CallbackQueue>: An array of googlefc.CallbackQueue objects. Each object is not null. Array itself is not null.
• !googlefc.ConsentStatusEnum: Number contained in the ConsentStatusEnum.
• !googlefc.AdBlockerStatusEnum: Number contained in the AdBlockerStatusEnum.
• !googlefc.AllowAdsStatusEnum: Number contained in the AllowAdsStatusEnum.
• !googlefc.ccpa.InitialCcpaStatusEnum: Number contained in the InitialCcpaStatusEnum.

Find more detailed information in Google Closure docs.

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.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.AdBlockerStatusEnum	!Object<string, number>	An enum to represent the user's ad blocker state.
googlefc.AllowAdsStatusEnum	!Object<string, number>	An enum to represent the user's allow-ads state.
googlefc.ccpa.InitialCcpaStatusEnum	!Object<string, number>	An enum to represent the user initial CCPA status.
googlefc.ccpa.overrideDnsLink	undefined|boolean	A boolean which can be set to true to use a custom Do Not Sell link.

Method Summaries

Note: The only supported way to invoke any function is by adding it to the callbackQueue.

Name	Return type	Definition
googlefc.showRevocationMessage()	undefined	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.getAllowAdsStatus()	number	Returns a value in the AllowAdsStatusEnum depending on the allow-ads status of the user.
googlefc.ccpa.getInitialCcpaStatus()	number	Returns a value in the InitialCcpaStatusEnum depending on the initial CCPA status of the user.
googlefc.ccpa.openConfirmationDialog(function(boolean))	undefined	Opens the CCPA confirmation dialog if the default Do Not Sell link is overridden.

Testing and debugging on your site

We provide debugging and testing functionality that lets you see what specific messages (or combinations of messages) look like on your actual site.

Prerequisites:

• The message(s) you want to preview must be published under the site you're testing against

• The Funding Choices tag must be on the site you're testing against

You can see a live preview on your site by using the following debugging URL parameters:

Debug parameter	Allowed values
fc	alwaysshow (to trigger debug/preview mode)
fctype	ab (Ad blocking messages), ccpa (CCPA opt-out messages), gdpr (GDPR consent messages)

Some examples of how to use this to preview on your site (foo.com):

• Test CCPA messaging -- http://foo.com?fc=alwaysshow&fctype=ccpa
• Test GDPR messaging -- http://foo.com?fc=alwaysshow&fctype=gdpr

Note: If you expect to see a message but don't see it, or it's not behaving as expected, try clearing your cookies (or using Incognito mode) to reset any saved state and try again.

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.

Caution: googlefc.controlledMessagingFunction must be set before the Funding Choices tag loads to guarantee correct functionality. If the message is already visible when this field is set, the message is not suppressed. A method setting this field should not be added to the callback queue; instead, the field should be set directly, and set before the Funding Choices tag on the page.

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.ccpa = window.googlefc.ccpa || {}
    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.ccpa = window.googlefc.ccpa || {}
    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.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
• INITIAL_CCPA_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 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.

When CCPA data becomes available in the flow, any function with a map key of INITIAL_CCPA_DATA_READY will be executed. Note that any subsequent request for CCPA data should be obtained by directly calling the US Privacy API (__uspapi).

Note: For backwards compatibility with an older version of this API, if an element added to the queue is a function and not a map, the function will be executed when consent data becomes available. If ad blocking information is requested in the function, the status return value will be UNKNOWN.

---

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.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      if (googlefc.getAdBlockerStatus() == googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER) {
        // Handle a non-ad blocking user.
      }
    }
  });
</script>

---

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.AllowAdsStatusEnum {!Object<string, number>}

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

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

googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}

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

googlefc.ccpa.InitialCcpaStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // CCPA does not apply to this user.
  CCPA_DOES_NOT_APPLY: 1,
  // CPPA applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // CPPA applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

googlefc.ccpa.overrideDnsLink{undefined|boolean}

Set this field to true in order to hide the default Funding Choices link and use a custom Do Not Sell link.

Example:

<FC tag goes here>
<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  // Signals that the default DNS link will be overridden.
  googlefc.ccpa.overrideDnsLink = true;
</script>

Methods: explanations and examples

googlefc.getConsentStatus(): {number}

Caution: The getConsentStatus() method only applies when using the Simplified Framework for EU consent - which has been deprecated as of October 2021. This method will always return UNKNOWN (value 0) if called.

---

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

Caution: The getConsentedProviderIds() method only applies when using the Simplified Framework for EU consent - which has been deprecated as of October 2021. This will always return an empty list if called.

---

googlefc.showRevocationMessage(): {undefined}

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:

<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
  Click here to revoke
</button>

---

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.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      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.getAllowAdsStatus(): {number}

Returns a value in the AllowAdsStatusEnum depending on the allow-ads 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.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      switch (googlefc.getAllowAdsStatus()) {
        case googlefc.AllowAdsStatusEnum.ADS_NOT_ALLOWED:
          // Insert handling for cases where the user has not allowed ads.
          // The user may have never been an ad blocker.
          break;
        case googlefc.AllowAdsStatusEnum.ADS_ALLOWED:
          // Insert handling for cases where the user saw the ad blocking
          // message and allowed ads on the site.
          break;
        case googlefc.AllowAdsStatusEnum.UNKNOWN:
          // Insert handling for unknown cases.
          break;
      }
    }
  });
</script>

---

googlefc.ccpa.getInitialCcpaStatus(): {number}

Returns a value in the InitialCcpaStatusEnum depending on the CCPA status of the user. The key that should be specified for this function is INITIAL_CCPA_DATA_READY. Note that any subsequent request for CCPA data should be obtained by directly calling the US Privacy API (__uspapi).

Example:

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

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'INITIAL_CCPA_DATA_READY':
    () => {
      switch (googlefc.ccpa.getInitialCcpaStatus()) {
        case googlefc.ccpa.InitialCcpaStatusEnum.CCPA_DOES_NOT_APPLY:
          // Insert handling for cases where the user is not CCPA eligible.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where the user is CCPA eligible and has
          // not opted out.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
          // Insert handling for cases where the user is CCPA eligible and has
          // opted out.
          break;
      }
    }
  });
</script>

---

googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}

Opens the CCPA confirmation dialog if the default Do Not Sell link is overridden. Once the user interacts with the confirmation dialog, the provided callback function will be called with true if the user decides to opt-out, and false otherwise.

Example:

<FC tag goes here>
<script>
// This callback will be called with the user CCPA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the CCPA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>

Using Funding Choices with the IAB TCF v2 for GDPR

If you are using Funding Choices to gather GDPR consent under the IAB TCF v2 framework, you should use the IAB TCF v2 API.

Example:

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

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __tcfapi('getTCData', 0, (data, success) => console.log(data))
  });
</script>

Using Funding Choices with the IAB CCPA framework for CCPA

If you are using Funding Choices to gather CCPA opt-out under the IAB CCPA framework, you should use the IAB CCPA API.

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

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __uspapi('getUSPData', 1, (data, success) => console.log(data))
  });
</script>

Using Funding Choices with the IAB CCPA framework for CCPA with a custom Do Not Sell link

If you are using Funding Choices to gather CCPA opt-out under the IAB CCPA framework, it is possible to provide a custom Do Not Sell link by setting the googlefc.ccpa.overrideDnsLink flag to true.

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

  // Signals that the default DNS link will be overridden.
  googlefc.ccpa.overrideDnsLink = true;

  // Register the callback for the initial CCPA data.
  googlefc.callbackQueue.push({
      'INITIAL_CCPA_DATA_READY': () => {
        if (googlefc.ccpa.getInitialCcpaStatus() ===
            googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT) {
          // TODO: Display custom CCPA Do Not Sell link here.
        }
      }
    });
</script>

This will ensure that the default Do Not Sell link will not be rendered. Note that you are responsible for rendering your own Do Not Sell link in order to be compliant with CCPA. Then, you need to handle the user interaction with your custom Do Not Sell link by invoking the CCPA confirmation dialog.

<script>
// This callback will be called with the user CCPA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  if (userOptedOut) {
    // TODO: Hide custom CCPA Do Not Sell link here.
  }
}
// Invoke the CCPA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>