Funding Choices for user consent API

This guide contains:

Notes:
  • This API is applicable only to Funding Choices for user consent.
  • This help article is available in English only.

Introduction

The Funding Choices API provides a library to interact with the consent-gathering Funding Choices tool. The API can:

  • query the consent status of a user,
  • allow a user to revoke consent, and
  • suppress the consent message for any given user.

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

Learn more about Funding Choices consent management in the Help Center.

Closure types

Note: This Funding Choices tag 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.
  • 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<string>: An array of strings.
  • !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.

Find more detailed information in Google Closure docs.

Field summaries

Name Type Definition
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.ConsentStatusEnum !Object<string, number> An enum to represent the different consent states that the user can be in.

Method summaries

Note: The only supported way to invoke any function is by adding it to the callbackQueue.
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.suppressConsentMessage {boolean}

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

googlefc.suppressConsentMessage must be set before the Funding Choices tag loads to guarantee correct functionality. If the consent 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.

Example

<script>
// Make sure that the googlefc property exists on the window.
window.googlefc = window.googlefc || {};

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

<FC tag goes here>
</script>

  

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:

<script>
<FC tag goes here>

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

Correct usage can be found in the example for getConsentStatus.

Methods: explanations and examples

googlefc.getConsentStatus() : {number}

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

<script>
<FC tag goes here>

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

<script>
<FC tag goes here>

// 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>.
Was this helpful?
How can we improve it?