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:
   • ID: A unique identifier string (e.g. custom_analytics, ab_testing, newsletter_tracking). 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").
   • Description: A description shown when users click on the purpose for more details.
5. Click Save Changes, then Publish to deploy.

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

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
    }
  }
});

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