## Introduction

This API provides tools to interact with messages offered by the Privacy \&
messaging tab. With it, you can:

- [suppress messaging for any given user](https://developers.google.com/funding-choices/fc-api-docs#googlefc-controlledMessagingFunction)
- [query the ad blocking status of a user](https://developers.google.com/funding-choices/fc-api-docs#googlefc-getAdBlockerStatus)
- [render an entrypoint to allow a user to revoke EU regulations consent](https://developers.google.com/funding-choices/fc-api-docs#googlefc-showRevocationMessage)
- [override the default Do Not Sell link for US state regulations](https://developers.google.com/funding-choices/fc-api-docs#using-google-consent-gpp-us-state-regs-custom-dns)
- [conditionally load your Google Ads and Analytics tags based on the user's EU regulations Google Consent Mode status](https://developers.google.com/funding-choices/fc-api-docs#using-google-consent-consent-mode)

and more.

You can also use these tools to gather user consent using industry standard
protocols:

- GDPR consent using the [IAB TCF v2 spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md)
- US state regulations opt-outs using the [IAB GPP spec](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform)

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

You can deploy this user messaging functionality on your site in a couple of
ways:

1. For most cases, you don't need to re-tag at all - your existing [Google
   Publisher
   Tag](https://developers.google.com/publisher-tag/guides/get-started) or [AdSense tag](https://support.google.com/adsense/answer/9274516) deploys user messages once the message is published in the relevant product.
2. If you're using the ad blocking recovery message, you need to add the ad blocking tag to your page explicitly. See [Ad
   Manager](https://support.google.com/admanager/answer/10711849) and [AdSense](https://support.google.com/adsense/answer/11575177) tagging instructions for more information.

`googlefc` is the global namespace that the user messaging functionality uses
for its API on the JavaScript `Window`.

> [!NOTE]
> **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.usstatesoptout.InitialUsStatesOptOutStatusEnum`: Number contained in the InitialUsStatesOptOutStatusEnum.
> - `!googlefc.ConsentModePurposeStatusEnum`: Number contained in the ConsentModePurposeStatusEnum.
> - `!googlefc.ccpa.InitialCcpaStatusEnum`: Number contained in the InitialCcpaStatusEnum.
>
> Find more detailed information in [Google Closure docs](https://developers.google.com/closure/compiler/docs/js-for-compiler#types).

## Field Summaries

| Name | Type | Definition |
|---|---|---|
| [`googlefc.controlledMessagingFunction`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-controlledMessagingFunction) | function(!Object) | A function that determines whether to proceed with any messaging. This functionality is supported for all message types. |
| [`googlefc.callbackQueue`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) | !Array\<!Object\<string, function()\>\> \| !Array\<function()\> \| !googlefc.CallbackQueue | Reference to the callback queue for asynchronous execution of user messaging queries. |
| [`googlefc.CallbackQueue`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-CallbackQueue-Object) | !Object | The type of the callback queue object. |
| [`googlefc.AdBlockerStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-AdBlockerStatusEnum) | !Object\<string, number\> | An enum to represent the user's ad blocker state. |
| [`googlefc.AllowAdsStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-AllowAdsStatusEnum) | !Object\<string, number\> | An enum to represent the user's allow-ads state. |
| [`googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-usstatesoptout-InitialUsStatesOptOutStatusEnum) | !Object\<string, number\> | An enum to represent the user's initial US States opt-out status. This takes into account the US State in which the user is located. |
| [`googlefc.GoogleFcConsentModeUserStatus`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-GoogleFcConsentModeUserStatus) | !Object | The return type for `googlefc.getGoogleConsentModeValues`. |
| [`googlefc.ConsentModePurposeStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ConsentModePurposeStatusEnum) | !Object\<string, number\> | An enum to represent the end user's decision for a consent mode purpose. |
| [`googlefc.usstatesoptout.overrideDnsLink`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-usstatesoptout-overrideDnsLink) | undefined\|boolean | A boolean which can be set to true to use your own custom Do Not Sell or Share link. |
| [`googlefc.ccpa.InitialCcpaStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ccpa-InitialCcpaStatusEnum) <br /> *** Legacy. Prefer `googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum`.*** | !Object\<string, number\> | An enum to represent the user's initial US State regulations status. |
| [`googlefc.ccpa.overrideDnsLink`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ccpa-overrideDnsLink) <br /> *** Legacy. Prefer `googlefc.usstatesoptout.overrideDnsLink`.*** | undefined\|boolean | A boolean which can be set to true to use your own custom Do Not Sell or Share link. |

## Method Summaries

> [!NOTE]
> **Note:** The only supported way to invoke any function is by adding it to the `callbackQueue`.

| Name | Return type | Definition |
|---|---|---|
| [`googlefc.showRevocationMessage()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-showRevocationMessage) | undefined | Clears the consent record and reloads the `googlefc` script to show the consent message applicable to the user. |
| [`googlefc.getAdBlockerStatus()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-getAdBlockerStatus) | number | Returns a value in the `AdBlockerStatusEnum` depending on the ad blocking status of the user. |
| [`googlefc.getAllowAdsStatus()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-getAllowAdsStatus) | number | Returns a value in the `AllowAdsStatusEnum` depending on the allow-ads status of the user. |
| [`googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-usstatesoptout-getInitialUsStatesOptOutStatus) | number | Returns a value in the `InitialUsStatesOptOutStatusEnum` depending on the initial US state regulations opt-out status of the user. This takes into account the regulation that applies to the user based on their current location. |
| [`googlefc.usstatesoptout.openConfirmationDialog(function(boolean))`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-usstatesoptout-openConfirmationDialog) | undefined | Opens the US state regulations opt-out confirmation dialog if the default Do Not Sell or Share link is overridden. |
| [`googlefc.getGoogleConsentModeValues()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-getGoogleConsentModeValues) | !Object | Returns a `googlefc.GoogleFcConsentModeUserStatus` object containing the current consent mode values for the user, one for each available consent mode purpose. |
| [`googlefc.ccpa.getInitialCcpaStatus()`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ccpa-getInitialCcpaStatus) <br /> *** Legacy. Prefer `googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()`. *** | number | Returns a value in the `InitialCcpaStatusEnum` depending on the initial US state regulations opt-out status of the user. |
| [`googlefc.ccpa.openConfirmationDialog(function(boolean))`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ccpa-openConfirmationDialog) <br /> *** Legacy. Prefer `googlefc.usstatesoptout.openConfirmationDialog()`. *** | undefined | Opens the US State regulations opt-out confirmation dialog if the default Do Not Sell or Share link is overridden. |

## Testing and debugging on your site

Privacy \& messaging provides debugging and testing functionality that lets you
see what specific messages, sub-types of messages, or combinations of messages
look like on your actual site.

Prerequisites:

- The message(s) you want to preview must be published to 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` (US state regulation opt-out messages), `gdpr` (GDPR consent messages), `monetization` (Offerwall messages), `usfl` (US state regulation opt-out messages, Florida-specific), `usnat` (US state regulation opt-out messages, all supported states except Florida; equivalent to `ccpa`) |

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

- Test US state regulation opt-out messaging -- `http://foo.com/?fc=alwaysshow&fctype=ccpa`
- Test GDPR messaging -- `http://foo.com/?fc=alwaysshow&fctype=gdpr`

> [!NOTE]
> **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 or not messages should display. It can be
used to gate message rendering on publisher-specified conditions such as
subscriber status or page URL.

When you define `googlefc.controlledMessagingFunction` on the Window prior to
other scripts loading, messages don't display until you call
`message.proceed(boolean)`. Calling `message.proceed(true)` allows messaging to
proceed as usual, whereas calling `message.proceed(false)` prevents any messages
from showing for the pageview.

> [!CAUTION]
> **Caution:** if `googlefc.controlledMessagingFunction` is defined on the page, no Privacy \& messaging messages display until `message.proceed()` is called. This may delay ads serving. Therefore, you should ensure `message.proceed()` is called shortly after the page loads in order to guarantee expected messaging and ads serving behavior.

> [!CAUTION]
> **Caution:** to guarantee functionality, you must define the function on the Window **before** Google Ads scripts load.

Example: assume that you have this script on the page which defines an async
function `determineIfUserIsSubscriber()` that checks if the logged-in user is a
subscriber.

    <head>
      <script>
        window.isSubscriber = undefined;
        function determineIfUserIsSubscriber() {
          if (isSubscriber !== undefined) {
            return isSubscriber;
          }
          return new Promise(resolve => {
            setTimeout(() => {
              // Change this to true if you want to test what subscribers would see.
              window.isSubscriber = false;
              resolve(window.isSubscriber);
            }, 1000);
          });
        }
      </script>
    </head>

This is an example of how you could use the
`googlefc.controlledMessagingFunction` to only show the message to
non-subscribers.

    <head>
      <script>
        // Define googlefc and the controlled messaging function on the Window.
        window.googlefc = window.googlefc || {};
        googlefc.controlledMessagingFunction = async (message) => {
          // Determine if the user is a subscriber asynchronously.
          const isSubscriber = await determineIfUserIsSubscriber();

          if (isSubscriber) {
            // If the user is a subscriber, don't show any messages.
            message.proceed(false);
          } else {
            // Otherwise, show messages as usual.
            message.proceed(true);
          }
        }
      </script>
    </head>

There is also an extension of this feature that allows publishers to specify
that only specific message types should be suppressed. Use this feature
extension to suppress specific message types without suppressing other message
types.

> [!IMPORTANT]
> **Important:** This feature extension is supported for Offerwall (`googlefc.MessageTypeEnum.OFFERWALL`) and the ad blocking recovery message (`googlefc.MessageTypeEnum.AD_BLOCKING`) today.

Message type-specific controlled messaging is achieved by passing an additional
parameter to `message.proceed()`, an `Array` of type `googlefc.MessageTypeEnum`.

Example: This is an example of using `googlefc.controlledMessagingFunction` to
only suppress Offerwall serving for subscribers, without suppressing other
message types:

    <head>
      <script>
        // Define googlefc and the controlled messaging function on the Window.
        window.googlefc = window.googlefc || {};
        googlefc.controlledMessagingFunction = async (message) => {
         // Determine if the Offerwall should display or not.
         const shouldDisplayOfferwall = await determineIfUserIsSubscriber();
         const applicableMessageTypes = [];

         if (!shouldDisplayOfferwall) {
           // Do not show the Offerwall, but allow other message types to display.
           applicableMessageTypes.push(window.googlefc.MessageTypeEnum.OFFERWALL);
           message.proceed(false, applicableMessageTypes);
         } else {
           // Otherwise, show messages as usual.
           message.proceed(true);
         }
        }
      </script>
    </head>

> [!TIP]
> **Tip:** calling `message.proceed(true)` only *allows* the Offerwall to display- it does not guarantee that an Offerwall *does* display. The Offerwall [supports
> many customizations](https://support.google.com/admanager/answer/13421071) that can affect when the message renders, which should be taken into consideration when using the controlledMessagingFunction. For example, consider changing the message's frequency settings from displaying after 2 pageviews to displaying after 0 pageviews to prevent the feature from affecting your Offerwall's serving.

*** ** * ** ***

`googlefc.callbackQueue {!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue}`

Reference to the global callback queue for asynchronous execution of
messaging-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 following strings as the key and the
function to be executed as the value.

Supported keys:

| Key name | Usage | Relative latency |
|---|---|---|
| `CONSENT_API_READY` | Functions pushed to the callback queue with the `CONSENT_API_READY` key are executed when the APIs for supported consent frameworks are defined and callable. From this point on, execution of any subsequently added `CONSENT_API_READY`-keyed functions is synchronous. See sections on [IAB frameworks](https://developers.google.com/funding-choices/fc-api-docs#using-google-consent-tcfv2) for framework-specific details. | Low |
| `CONSENT_DATA_READY` | Functions pushed to the callback queue with the `CONSENT_DATA_READY` key are executed when user consent gathered under a supported consent framework is known (either from a prior execution or once the user interacts with the consent message). From this point on, execution of any subsequently added `CONSENT_DATA_READY`-keyed functions is synchronous. | High |
| `AD_BLOCK_DATA_READY` | Functions pushed to the callback queue with the `AD_BLOCK_DATA_READY` key are executed when ad blocking data becomes available in the flow. From this point on, execution of any subsequently added `AD_BLOCK_DATA_READY`-keyed functions are synchronous. | High |
| `CONSENT_MODE_DATA_READY` | Functions pushed to the callback queue with the `CONSENT_MODE_DATA_READY` key are executed when Google \[consent mode\](https://support.google.com/google-ads/answer/10000067) data (for use with Google Ads and Analytics tags) becomes available in the flow. Once consent mode data is ready, you can access consent mode values at any time using `googlefc.getGoogleConsentModeValues`. | Medium |
| `INITIAL_US_STATES_OPT_OUT_DATA_READY` | Functions pushed to the callback queue with the `INITIAL_US_STATES_OPT_OUT_DATA_READY` key are executed when US state regulations data becomes available in the flow. Note that any subsequent request for US State regulations data should be obtained by directly calling the GPP API (`__gpp`). | Medium |
| `INITIAL_CCPA_DATA_READY` | *** Legacy key for US state regulations. Prefer `INITIAL_US_STATES_OPT_OUT_DATA_READY`. *** Functions pushed to the callback queue with the `INITIAL_CCPA_DATA_READY` key are executed when US state regulations data becomes available in the flow. Note that any subsequent request for US State regulations data should be obtained by directly calling the GPP API (`__gpp`). | Medium |

> [!IMPORTANT]
> **Important:** `CONSENT_API_READY` just indicates that supported consent framework APIs are defined; user consent strings may not be available yet. The `CONSENT_DATA_READY` key corresponds to user consent strings being available, but `CONSENT_DATA_READY`-keyed functions are always executed later in the flow than `CONSENT_API_READY`-keyed functions.

> [!NOTE]
> **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 is executed when consent data becomes available (i.e. treated as if function uses `CONSENT_DATA_READY` key). If ad blocking information is requested in the function, the status return value is 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_API_READY`, `CONSENT_DATA_READY`, `AD_BLOCK_DATA_READY`, `INITIAL_US_STATES_OPT_OUT_DATA_READY`, `CONSENT_MODE_DATA_READY` and (legacy) `INITIAL_CCPA_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:

    <script>
      // Make sure that the properties exist on the window.
      window.googlefc = window.googlefc || {};
      window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
      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 Privacy & messaging message.
      ADS_NOT_ALLOWED: 1,
      // User is no longer using an ad blocker after seeing the ad blocking message.
      ADS_ALLOWED: 2,
    };

*** ** * ** ***

`googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum{!Object<string, number>}`

Represents the different US state regulation opt-out statuses of the user. The
different statuses are:

    googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum = {
      // Something failed, status unknown.
      UNKNOWN: 0,
      // No US state regulation applies to this user.
      DOES_NOT_APPLY: 1,
      // A US state regulation applies to this user, and the user has not opted out yet.
      NOT_OPTED_OUT: 2,
      // A US state regulation applies to this user, and the user has opted out.
      OPTED_OUT: 3,
    };

*** ** * ** ***

`googlefc.GoogleFcConsentModeUserStatus{!Object}`

The type of the object returned by `googlefc.getGoogleConsentModeValues`.

    interface GoogleFcConsentModeUserStatus {

      // End user consent decision value for the ad_storage consent mode purpose.
      adStoragePurposeConsentStatus: number;

      // End user consent decision value for the ad_user_data consent mode purpose.
      adUserDataPurposeConsentStatus: number;

      // End user consent decision value for the ad_personalization consent mode purpose.
      adPersonalizationPurposeConsentStatus: number;

      // End user consent decision value for the analytics_storage consent mode purpose.
      analyticsStoragePurposeConsentStatus: number;
    }

The value of each field is a number that corresponds to a
[`googlefc.ConsentModePurposeStatusEnum`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ConsentModePurposeStatusEnum)
enum value.

*** ** * ** ***

`googlefc.ConsentModePurposeStatusEnum{!Object<string, number>}`

Represents the different possible end user consent values for a consent mode
purpose. The different values are:

    googlefc.ConsentModePurposeStatusEnum = {
      // Indicates either an error state, or that consent mode data is not ready
      // yet.
      UNKNOWN: 0,
      // Consent is granted for the given consent mode purpose.
      GRANTED: 1,
      // Consent is denied for the given consent mode purpose.
      DENIED: 2,
      // Consent is not applicable for the given consent mode purpose.
      NOT_APPLICABLE: 3,
      // The consent mode purpose has not been configured for use in the Privacy &
      // messaging UI.
      NOT_CONFIGURED: 4
    };

*** ** * ** ***

`googlefc.usstatesoptout.overrideDnsLink{undefined|boolean}`

Set this field to true in order to hide the default Do Not Sell or Share link
and use your own custom Do Not Sell or Share link. Note that this functionality
is only supported in Ad Manager.

Example:

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

*** ** * ** ***

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

> [!NOTE]
> **Note:** Prefer `googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum` in new code.

Represents the different US state regulation opt-out statuses of the user. The
different statuses are:

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

*** ** * ** ***

`googlefc.ccpa.overrideDnsLink{undefined|boolean}`

> [!NOTE]
> **Note:** Prefer `googlefc.usstatesoptout.overrideDnsLink` in new code.

Set this field to true in order to hide the default Do Not Sell or Share link
and use your own custom Do Not Sell or Share link. Note that if you set this
field to true, you are responsible for rendering a Do Not Sell or Share link on
your site. This field should be used in conjunction with
[`openConfirmationDialog`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-ccpa-openConfirmationDialog). Additionally,
using your own custom Do Not Sell or Share link for "US States
regulations" messaging functionality is only supported in Ad Manager.

Example:

    <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]
> **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]
> **Caution:** The `getConsentedProviderIds()` method only applies when using the Simplified Framework for EU consent - which has been deprecated as of October

1. This now always returns an empty list when called.

*** ** * ** ***

`googlefc.showRevocationMessage(): {undefined}`

Clears the current EU regulations consent record, if present, and shows the EU
regulations message again to allow the user to change their consent decision.

**Example 1**: Simple example of setting up a link that will show the
revocation message when clicked:

    <a href="javascript:window.googlefc.showRevocationMessage();">Privacy and cookie settings</a>

> [!TIP]
> **Tip:** If the googlefc API has not been loaded onto the page at the time the link is clicked, then the link will have no effect. In practice, the googlefc API typically loads onto the page more quickly than most users would be able to find and click this link; however, if you only want to show the link once googlefc is definitely on the page, you can condition showing the link on the [`CONSENT_API_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) API key, as shown in the following code snippet.

    <a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
    <script>
      window.googlefc = window.googlefc || {};
      window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
      window.googlefc.callbackQueue.push({
        'CONSENT_API_READY':
        () => {
          // Update the revocation link so that it shows on the page.
          const revocationLink = document.getElementById('revocation-link');
          revocationLink.style.display = 'block';
        }
      });
    </script>

**Example 2** : If you only want the link to be visible when EU regulations
apply to the current user, you can use the googlefc callback queue with the TCF
API to conditionally update the display of the button based on the `gdprApplies`
value once determined. For this, use the
[`CONSENT_API_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) API key.

    <a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
    <script>
      window.googlefc = window.googlefc || {};
      window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
      window.googlefc.callbackQueue.push({
        'CONSENT_API_READY':
        // Specifying "0" for the version parameter will result in the API call
        // using the latest version of the TCF spec.
        () => __tcfapi('addEventListener', 0, (tcdata, success) => {
          const revocationLink = document.getElementById('revocation-link');
          if (!success || !tcdata) {
            // Something went wrong, don't show the revocation link.
            revocationLink.style.display = 'none';
          }
          else if (tcdata.gdprApplies) {
            revocationLink.style.display = 'block';
          } else {
            // GDPR does not apply so don't show the revocation link.
            revocationLink.style.display = 'none';
          }
        })
      });
    </script>

*** ** * ** ***

`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:

    <script>
      // Make sure that the properties exist on the window.
      window.googlefc = window.googlefc || {};
      window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
      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:

    <script>
      // Make sure that the properties exist on the window.
      window.googlefc = window.googlefc || {};
      window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
      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.usstatesoptout.getInitialUsStatesOptOutStatus(): {number}`

Returns a value in the `InitialUsStatesOptOutStatusEnum` depending on the US
state regulation opt-out status of the user. The key that should be specified
for this function is `INITIAL_US_STATES_OPT_OUT_DATA_READY`. Note that any
subsequent request for US state regulations data should be obtained by directly
calling the GPP API (`__gpp`).

If you are overriding the Do Not Sell or Share link, you can use this method to
determine when to include the link on your site.

Example:

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

      // Queue the callback on the callbackQueue.
      googlefc.callbackQueue.push({
        'INITIAL_US_STATES_OPT_OUT_DATA_READY':
        () => {
          switch (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()) {
            case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.DOES_NOT_APPLY:
              // Insert handling for cases where no US state regulation applies to
              // the user.
              break;
            case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT:
              // Insert handling for cases where a US state regulation applies to
              // the user, and the user has not opted out.
              break;
            case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.OPTED_OUT:
              // Insert handling for cases where a US state regulation applies to the
              // user, and the user has opted out.
              break;
          }
        }
      });
    </script>

*** ** * ** ***

`googlefc.usstatesoptout.openConfirmationDialog(function(boolean)): {undefined}`

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

Example:

    <script>
    // This callback will be called with the user's US state regulation opt-out
    // decision.
    const usStateRegCompletionCallback = (userOptedOut) => {
      // Insert handling for user opt-out status here.
    }
    // Invoke the US state regulations confirmation dialog when the user clicks the
    // link.
    document.getElementById("your-custom-do-not-sell-link").addEventListener(
      "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
    </script>

*** ** * ** ***

`googlefc.getGoogleConsentModeValues(): {!Object}`

Returns a
[`googlefc.GoogleFcConsentModeUserStatus`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-GoogleFcConsentModeUserStatus)
object containing the current values of each consent mode purpose, based on the
user's consent decision.

See [Using Google consent management solutions with consent mode support for EU regulations](https://developers.google.com/funding-choices/fc-api-docs#using-google-consent-consent-mode)
for intended usage.

*** ** * ** ***

`googlefc.ccpa.getInitialCcpaStatus(): {number}`

> [!NOTE]
> **Note:** Prefer `googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()` in new code.

Returns a value in the `InitialCcpaStatusEnum` depending on the US state
regulation opt-out status of the user. The key that should be specified for this
function is `INITIAL_CCPA_DATA_READY`. Note that any subsequent request for
US state regulation data should be obtained by directly calling the GPP
API (`__gpp`).

Example:

    <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 no US state regulation applies to
              // the user.
              break;
            case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
              // Insert handling for cases where a US state regulation applies to
              // the user, and the user has not opted out.
              break;
            case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
              // Insert handling for cases where a US state regulation applies to the
              // user, and the user has opted out.
              break;
          }
        }
      });
    </script>

*** ** * ** ***

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

> [!NOTE]
> **Note:** Prefer `googlefc.usstatesoptout.openConfirmationDialog` in new code.

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

Example:

    <script>
    // This callback will be called with the user's US state regulation opt-out
    // decision.
    const usStateRegCompletionCallback = (userOptedOut) => {
      // Insert handling for user opt-out status here.
    }
    // Invoke the US state regulations 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 Google consent management solutions with the IAB TCF v2 for GDPR

If you are using Google consent management solutions to gather GDPR consent
under the IAB TCF v2 framework, you should use the [IAB TCF v2
API](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md).

You can use the [`CONSENT_API_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue)
callback queue key to ensure that corresponding callbacks are invoked only when
the IAB TCF v2 API is defined on the page. This should be used in conjunction
with the
[`'addEventListener'`](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#addeventlistener)
command of the IAB TCF v2 API.

Example:

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

      // Queue the callback using the CONSENT_API_READY key on the callbackQueue.
      window.googlefc.callbackQueue.push({
        'CONSENT_API_READY':
        () => __tcfapi('addEventListener', 2.2, (data, success) => {
          // Do something with consent data value; this callback may be invoked
          // multiple times as user completes consent flow.
        })
      });
    </script>

You can use the [`CONSENT_DATA_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) callback queue key to ensure that corresponding callbacks are invoked
only when user consent is collected and accessible using the IAB TCF v2 API.
This can be used in conjunction with the
[`'addEventListener'`](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#addeventlistener)
command - the data provided in the first invocation of your provided callback
will contain the user's consent selections (as long as TCF v2 applies to this
user). Note that with the release of TCF v2.2, the
[`'getTCData'`](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#gettcdata)
command is now deprecated.

Example:

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

      // Queue the callback using the CONSENT_DATA_READY key on the callbackQueue.
      window.googlefc.callbackQueue.push({
        'CONSENT_DATA_READY':
        () => __tcfapi('addEventListener', 2.2, (data, success) => {
          // Do something with consent data value; this callback may be invoked
          // multiple times if user consent selections change.
        })
      });
    </script>

## Using Google consent management solutions with consent mode support for EU regulations

Google consent management solutions can interpret your users' EU regulations
consent choices for
[Google consent mode](https://support.google.com/google-ads/answer/10000067)
(learn more in
[Help Center](https://support.google.com/admanager/answer/10076805)).

Consent mode may be implemented in either **basic mode** or **advanced mode** ,
as described in
[Google Ads and Analytics documentation](https://developers.google.com/tag-platform/security/concepts/consent-mode#basic-vs-advanced).
You should consult with your legal department on which consent mode to implement
to meet your legal requirements.

**Advanced consent mode** is supported by default; once you have enabled Consent
Mode in the Privacy \& messaging UI, no additional work is needed.

To implement **basic consent mode** using Google consent management solutions,
you can use the `CONSENT_MODE_DATA_READY` callback queue key to conditionally
load your Google Ads and Analytics tags once consent mode data is available.
Consent mode data will be available after Funding Choices determines that
consent mode does not apply to this request (for example, because EU regulations
do not apply to this request) or after a user has made an EU regulations consent
decision. You should consult with your legal department on the criteria to use
to determine whether your tags can be loaded once consent mode is available.

For example, to load your tags once consent mode data is available, regardless
of the end user's consent decision:

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

    // Helper function to load Google Ads/Analytics tags once consent mode data is
    // ready.
    const loadGtagScript = () => {
      // Load gtag.js script - code taken from
      // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
      var gtagScript = document.createElement('script');
      gtagScript.async = true;
      gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

      var firstScript = document.getElementsByTagName('script')[0];
      firstScript.parentNode.insertBefore(gtagScript,firstScript);
    }

    // Queue the callback using the CONSENT_MODE_DATA_READY key on the callbackQueue.
    window.googlefc.callbackQueue.push({
      'CONSENT_MODE_DATA_READY':
      () => {
          loadGtagScript();
      },
    });
    </script>

You can also use the `googlefc.getGoogleConsentModeValues()` API to obtain the
values of individual consent mode purposes when consent mode data is available.
This API returns a `GoogleFcConsentModeUserStatus` object that contains one
field for each supported consent mode purpose, and the value
of each field is an enum value that indicates the value of that consent mode
purpose.

For example, you can use `googlefc.getGoogleConsentModeValues()` to unblock your
Google Ads and Analytics tags only when either:

- the end user makes an EU regulations consent decision that results in granting consent for all consent mode purposes, *or*
- all consent mode purposes are inapplicable for the current request (which could happen if EU regulations do not apply or consent mode is not configured for one or more purposes in Privacy \& messaging).

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

    // Helper function to determine whether Google Ads and Analytics tags can be
    // unblocked. Returns true if all consent mode purposes are set to GRANTED,
    // NOT_APPLICABLE, or NOT_CONFIGURED.
    const shouldUnblockConsentTags = (googleFcConsentModeStatus) => {
      const allConsentModeValues = [
        googleFcConsentModeStatus.adStoragePurposeConsentStatus,
        googleFcConsentModeStatus.adUserDataPurposeConsentStatus,
        googleFcConsentModeStatus.adPersonalizationPurposeConsentStatus,
        googleFcConsentModeStatus.analyticsStoragePurposeConsentStatus
      ];
      for (const consentModeValue of allConsentModeValues) {
        switch (consentModeValue) {
          case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_UNKNOWN:
            // Indicates either an error case or that consent mode data is not
            // ready yet. Cannot unblock tags until consent data is ready and valid,
            // so return false.
            return false;
          case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_GRANTED:
            // Consent is granted for this consent mode purpose.
            break;
          case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_DENIED:
            // Consent is denied for this consent mode purpose. Do not unblock tags.
            return false;
          case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_APPLICABLE:
            // Consent mode does not apply for this purpose.
            break;
          case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_CONFIGURED:
            // Consent mode not configured for this purpose.
            // If you configured support for Ads purposes but not Analytics purposes in the
            // Privacy & messaging UI, the value of `analyticsStoragePurposeConsentStatus` will
            // always be set to NOT_CONFIGURED. If you do not enable any Consent Mode support
            // in the Privacy & messaging UI, the values of all purposes will always be set to
            // NOT_CONFIGURED.
            break;
          default:
            console.log("Unexpected consent mode value encountered");
        }
      }
      // If all prior checks pass, all consent mode values are either GRANTED,
      // NOT_APPLICABLE, or NOT_CONFIGURED.
      return true;
    };

    // Helper function to load Google Ads/Analytics tags.
    const loadGtagScript = () => {
      // Load gtag.js script - code taken from
      // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
      var gtagScript = document.createElement('script');
      gtagScript.async = true;
      gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

      var firstScript = document.getElementsByTagName('script')[0];
      firstScript.parentNode.insertBefore(gtagScript,firstScript);
    }

    googlefc.callbackQueue.push({
      CONSENT_MODE_DATA_READY: () => {
        if (shouldUnblockConsentTags(googlefc.getGoogleConsentModeValues())) {
          loadGtagScript();
        }
      },
    });
    </script>

## Using Google consent management solutions with the IAB GPP framework for US state regulations

If you are using Google consent management solutions to provide US state
regulations opt-out messages to end users under the IAB GPP framework, you
should use the [IAB GPP API](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform).

Due to the opt out nature of US state regulations, you may use either the
[`CONSENT_API_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) or
[`CONSENT_DATA_READY`](https://developers.google.com/funding-choices/fc-api-docs#googlefc-callbackQueue) callback
queue key to ensure that the IAB GPP API is callable and returning consent data
at the time that callbacks are invoked.

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

      // Queue the callback on the callbackQueue.
      window.googlefc.callbackQueue.push({
        'CONSENT_DATA_READY':
        () => __gpp('ping', (data, success) => {
            // Do something with consent data value.
        })
      });
    </script>

## Using Google consent management solutions with the IAB GPP framework for US state regulations with your own custom Do Not Sell or Share link

If you are using Google consent management solutions to provide US state
regulations opt-out messages to end users under the IAB GPP framework, it is
possible to provide your own custom Do Not Sell or Share link by setting the
`googlefc.usstatesoptout.overrideDnsLink` flag to `true`.

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

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

      // Register the callback for the initial US state regulations data.
      window.googlefc.callbackQueue.push({
          'INITIAL_US_STATES_OPT_OUT_DATA_READY': () => {
            if (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus() ===
                googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT) {
              // TODO: Display custom Do Not Sell or Share link here.
            }
          }
        });
    </script>

This ensures that the default Do Not Sell or Share link does not render. Then,
you need to handle the user interaction with your custom Do Not Sell or Share
link by invoking the US state regulations opt-out confirmation dialog.

Note that, when using your own custom Do Not Sell or Share link, you are
responsible for ensuring that your link is compliant with US state regulations.
Additionally, using your own custom Do Not Sell or Share link for "US States
regulations" messaging functionality is only supported in Ad Manager.

    <script>
    // This callback will be called when the user makes a US state regulations
    // decision.
    const usStateRegCompletionCallback = (userOptedOut) => {
      if (userOptedOut) {
        // TODO: Hide custom Do Not Sell or Share link here.
      }
    }
    // Invoke the US state regulations opt-out confirmation dialog when the user
    // clicks the link.
    document.getElementById("your-custom-do-not-sell-link").addEventListener(
      "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
    </script>