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.

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, Simple Mode (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.

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>

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