OneTrust and Segment Integration: A Step-by-Step Guide

You have come to the right place if you want a OneTrust and Segment integration. This article will introduce two methods to leverage OneTrust within your Segment landscape—one for Free and Team plan users and one for Business plan users. The OneTrust and Segment integration will allow you to determine to which destinations you may send data while respecting the user’s consent level.

OneTrust and Segment integration flow explained

The solution, in general, makes use of Segment’s Plugin architecture for their Analytics.js SDK. It functions like middleware in that you can perform specific tasks to the analytics.js functionality and payload in-flight. There are currently five types of plugins that you can create:

before – Executes before event processing begins. These are plugins that run before any other plugins run.
enrichment – Executes as the first level of event processing. These plugins modify an event.
destination – Executes as events begin to pass off to destinations.
after – Executes after all event processing completes. You can use this to perform cleanup operations.
utility – Executes once during the bootstrap to allow you to modify how Analytics.js works internally.

For the OneTrust and Segment integration, we will use the enrichment-type plugin.

The enrichment plugin will allow us to modify the event’s payload before being sent. In our case, we want to add either an integrations object (Free & Team plan users) or the OneTrust OptanonConsent-cookie value to the event’s context (Business plan users).

Since Free and Team plan users cannot use Destination Filters, we will leverage the default integrations object functionality. The integrations object will help you control how Segment routes collected data to specific destinations. The script calls a relatively unknown Projects API integrations endpoint. Together with your write key, you can retrieve a list of active destinations set up in your workspace.

The API returns an array of your active destinations, including a name and category, both of which will be used to build the integrations object.

If the OneTrust cookie contains consent for a specific category of tags, all destinations that match that category will be assigned a value of true. Otherwise they will be set to false, preventing Segment from forwarding that data.

Business plan users have it a bit easier. Their method will only require the injection of the OneTrust cookie value, particularly the groups variable, from which Destination Filters can be built within Segment. No API call needs to be made, so this method is quicker. The location where the OneTrust cookie values are injected is the context object. The reason that we do not use the integrations object is that that would require an API call. Although the properties object would also be a feasible location, it would not match with identify calls where the properties object is replaced with a traits object.

In the end, the location does not matter; you can easily set up destination filters clearly and concisely.

OneTrust and Segment integration plugin Feature overview

failsafes for missing OneTrust cookies.
Listeners for click on OneTrust consent banners to reread the OneTrust cookie and rebuild the integrations object.
API call to retrieve a list of active integrations (Free & Team plan solution only)
Plugin that allows for the integration of consent data with every page, track, and identify calls (can be extended to more call types in the code)

Setting up the OneTrust and Segment integration

The requirements for setting up the OneTrust and Segment integration are as follows:

your Segment Workspace Analytics.js Source write key
our OneTrust and Segment integration plug script
access to the source code
the proper rights in the Segment to setup Destination Filters (Business plan only)

Finding your Segment Workspace analytics.js write key

To find this, go into Segment > Connections > Sources and click on the Javascript source you want to implement the integration for. The key is not a secret; it can be found on any website using Segment.

Copy the write key and save it for later.

Copy the OneTrust and Segment integration script

This step is essential. Please select and copy the script from our GitHub repository that works best for you. There are two scripts to choose from:

Business plan users can use either script, but their script is quicker, 54 versus 116 lines of code since it does not require an API call to retrieve destination information from Segment.

Update the write key value in either script in the WEBSITE_WRITE_KEY constant.

Set default values

Several variables can be configured. For the Free/Team tier, there is one variable besides the write key variable, and for the Business tier, there are three.

all_default: [Free/Team tier] Since we need to do an API call to retrieve all the destinations in the Segment account, it is wise to have a value to fall back on, just in case of an error. The failsafe, in this case, is the All key in the integrations object with the default value of false. This will prevent data from reaching any destination in case of an error. Change this value to true to reverse the effect.
OPT_IN: [Free/Team tier] This value will be assigned to the Segment.io destination allowing you to still capture data within Segment and your data warehouse storage destination. I have set the default to true, but feel free to adjust this if needed.
INDOMAIN_INSTRUMENTATION_URL: [All tiers] If you use Segment’s CNAME cloaking feature for first-party features, change the default url to whatever you need. If not, leave it as it is.

Place (or replace) the Analytics.js on your website with the new script

If you have not already placed the Segment analytics.js SDK on your website, use our OneTrust and Segment integration script instead. If you already have the Segment analytics.js SDK script, replace it with our OneTrust and Segment integration script.

We would recommend that you place the script below the OneTrust script.

Publish and test your script.

Update your Destination Filters for each destination [Business plan only]

If you are on a Business plan, you can use Destination Filters to filter data based on rules. These rules can be defined per destination. Please remember to set the right filter for the correct type of destination. You should do this using OneTrust’s group ids.

C0002:1 – consent is given for Analytics destinations. See list of Segment Analytics destinations.
C0003:1 – consent is given for Functional destinations. See list of Segment Functional a.k.a. Personalization destinations.
C0004:1 – consent is given for Targeting destinations. See list of Segment Functional a.k.a. Advertising destinations.
C0005:1 – consent is given for Social Media destinations. Segment does not have Social Media destinations; these usually fall under Advertising C0004.

Step 1 – Create a New Filter

Step 2 – Add conditionals to the filter

Select ‘Only Send Event’ option from the first dropdown.
Select ‘Event Field’ in the second dropdown list.
Type ‘onetrust’ in the field behind the ‘Event Field’ dropdown list, and it should show you the value collected in the context object.
Select ‘contains’ in the following field.
Enter the OneTrust group id relevant to the destination for which you are creating a filter.

Step 3 – Test the filter

Click on Test Event to test the filter.

Make sure to test with C0002:0, C0002:1, and without. You can manually add these values in the text editor.

With C0002:1, the filter will send the event.

With C0002:0, the filter will block the event.

Step 4 – Save the filter

When satisfied with the test results, save the filter.

Conclusion

Although this solution requires manual effort, the results will benefit your company in several ways. It will allow you to collect data while respecting the user’s consent and significantly prevent you from failing any regulatory board audit, such as GDPR, CCPA, VCDPA, etc.

If you have any questions or suggestions on improving these scripts, please feel free to contact me via LinkedIn or the contact form.

This solution was inspired by the Segment TrustArc integration by Chris Sperandino.