Custom Purposes

Custom Purposes allow you to define your own consent purposes beyond the standard IAB TCF purposes and Google Consent Mode types. They are displayed in the consent UI, stored separately from TCF consent, and can be queried via JavaScript API or used with UnicScript tag loading.

Setting Up Custom Purposes

1. Enable Custom Purposes

1. Log in to the UniConsent dashboard.
2. Navigate to Consent Collection -> Consent Manager and select your website.
3. Go to Step 4: Advanced Features.
4. Toggle Enable Custom Purposes to ON.
5. Click Save Changes.

2. Define Custom Purposes

1. After enabling, a new Custom Purposes tab will appear.
2. Click the Custom Purposes tab.
3. Click Add Custom Purpose to create a new purpose.
4. Fill in:
   • Language: Select the language you want to edit. English is the default language. You can add translations for the name and description in other languages supported by your project.
   • ID: A unique identifier string using lowercase letters, numbers, and underscores only (e.g. custom_analytics, ab_testing, newsletter_tracking). Spaces are automatically converted to underscores. This ID is used in storage, dataLayer, tag loading, and API queries.
   • Name: The display name shown to users in the consent UI (e.g. "Custom Analytics"). When editing a non-default language, the English name is shown as placeholder.
   • Description: A description shown when users click on the purpose for more details. When editing a non-default language, the English description is shown as placeholder.
5. Click Save Changes, then Publish to deploy.

You can add multiple custom purposes. Each must have a unique ID.

Templates

In Start from a template, you can start from a ready-made purpose or set of purposes, with translations where relevant:

• Email open tracking (see Email Open Tracking Consent)
• UK gambling direct marketing: 9 opt-ins, one for each product (betting, casino, bingo) and channel (email, text message, phone)
• Washington consumer health data: separate consents to collect and to share consumer health data
• Precise location and Biometric data: sensitive purposes that US visitors must opt in to explicitly
• Netherlands online gambling advertising opt-out
• Marketing by channel: email, text message, phone and post

A template with several purposes creates them all in one step; purposes whose ID already exists are skipped. Review and adapt the text to your own processing before publishing.

3. Multi-Language Support

Custom purposes support multi-language translations. To add translations:

1. Open an existing custom purpose or create a new one.
2. Use the Language dropdown at the top of the form to switch languages.
3. Enter the translated Name and Description for each language.
4. The Purpose ID remains the same across all languages.
5. If a translation is not provided for a language, the English (default) text will be used.

How Custom Purposes Work

• Custom purposes appear in the consent UI alongside standard purposes. Users can toggle each one individually.
• Consent status is stored in a separate storage key (__unic_custom_consent), independent from TCF consent strings and Google Consent Mode.
• When users click "Agree All", all custom purposes are granted. When users click "Reject All", all are denied.
• Custom purposes work across all law frameworks: GDPR, TCF Canada, CCPA, US State Privacy, Consent Categories (EZ), LGPD, PIPL, and POPIA.

JavaScript API

Query Custom Consent Status

Use getCustomConsent to retrieve the current consent status of all custom purposes:

__tcfapi('getCustomConsent', 2, function(data, success) {
  if (success) {
    console.log(data);
    // Example output: { "custom_analytics": true, "ab_testing": false }
  }
});

Or using the __unicapi alias:

__unicapi('getCustomConsent', 2, function(data, success) {
  if (success) {
    // Check a specific custom purpose
    if (data['custom_analytics']) {
      // Custom analytics consent is granted
    }
  }
});

Set Custom Consent Status

Use setCustomConsent to programmatically set the consent status of custom purposes:

__tcfapi('setCustomConsent', 2, { "custom_analytics": true, "ab_testing": false });

Or using the __unicapi alias:

__unicapi('setCustomConsent', 2, { "custom_analytics": true, "ab_testing": false });

The provided values are merged into the existing consent status and persisted to localStorage. You only need to include the purposes you want to update — other purposes will keep their current values.

When Consent DB is enabled, the change is recorded with any user IDs you set. Once the visitor has made a choice in the banner, the change also counts as a consent update: tags are reloaded and the uniconsent:update event is sent. See Email Open Tracking Consent for an example with a subscribe form.

Access via DataLayer

Custom purpose consent status is pushed to the dataLayer as UNIC_CP_{id}:

// Listen for consent data
(function waitCMP() {
  var readyCMP;
  if (!readyCMP && window['dataLayer']) {
    window['dataLayer'].forEach(function(event) {
      if (event['event'] === 'unic_data') {
        readyCMP = 1;
        console.log(event['UNIC_CP_custom_analytics']); // true or false
        console.log(event['UNIC_CP_ab_testing']);        // true or false
      }
    });
  }
  if (!readyCMP) {
    setTimeout(waitCMP, 100);
  }
})();

UnicScript Tag Loading

You can conditionally load scripts and iframes based on custom purpose consent using the unic-cp-id and unic-cp-ids attributes.

Load Script for a Single Custom Purpose

<script type="text/unicscript" unic-cp-id="custom_analytics">
  console.log('Custom analytics consent granted');
</script>

Load External Script for a Custom Purpose

<script type="text/unicscript" unic-cp-id="custom_analytics" src="https://example.com/analytics.js"></script>

Load Script for Multiple Custom Purposes

All specified purposes must be consented for the script to load:

<script type="text/unicscript" unic-cp-ids="custom_analytics,ab_testing">
  console.log('Both custom analytics and A/B testing consent granted');
</script>

Load Iframe for a Custom Purpose

<iframe
  data-unicscript
  unic-cp-id="custom_analytics"
  width="560"
  height="315"
  data-src="https://example.com/widget"
  frameborder="0"
></iframe>

Load Iframe for Multiple Custom Purposes

<iframe
  data-unicscript
  unic-cp-ids="custom_analytics,ab_testing"
  width="560"
  height="315"
  data-src="https://example.com/widget"
  frameborder="0"
></iframe>

Sensitive Custom Purposes (US)

Mark a custom purpose as Sensitive Data (US) in its settings when it processes sensitive personal information, such as health, precise location or biometric data. For US visitors:

• The purpose stays off until the visitor turns it on in the settings screen. Accepting the banner does not turn it on, and a US opt-out turns it off.
• The settings screen lists it under Limit the Use of My Sensitive Personal Information, and the banner link reads Your Privacy Choices.
• Choose a GPP Sensitive Category to send the choice in the IAB GPP US National section and in each US state section that has this category.

Outside the US, a sensitive purpose works like any other custom purpose.

Google Tag Manager Integration

In GTM, you can use the dataLayer variables UNIC_CP_{id} to create triggers based on custom purpose consent:

1. Create a Data Layer Variable in GTM with the name UNIC_CP_custom_analytics.
2. Create a Trigger that fires when UNIC_CP_custom_analytics equals true.
3. Attach the trigger to the tags you want to control.

Storage

Custom consent data is stored under the __unic_custom_consent key in localStorage (web) or native key-value storage (mobile apps). The format is:

{
  "custom_analytics": true,
  "ab_testing": false
}

This storage is independent from:

• TCF consent string (euconsent-v2)
• Google Consent Mode (__unic_consent_mode)
• USP string

Custom consent is cleared when users reset their consent via the CMP.

Still have questions?

Contact us: support@uniconsent.com