Add Contextual Consent (optional)
Block third-party content until consent is obtained and implement contextual consent for embedded services such as videos, maps, and social media features.
This work is licensed under CC BY-SA 4.0
Third-party content—such as maps, videos, or social media features—often transmits your visitors’ personal data to the provider the moment it loads. You must prevent this until the visitor has consented. Contextual consent does exactly that: instead of asking for everything up front in the cookie banner, you keep a specific embed blocked and ask for consent right where the content appears, at the moment the visitor wants to use it.
In practice this means:
- The embed stays blocked—so no personal data reaches the provider—until the visitor consents.
- The visitor consents directly at the embed, which loads the content in place.
- Once that consent is recorded, the embed loads automatically for the visitor on their next visit, with no further prompt.
You can implement this with our ready-made consent gate, which handles the blocking and unblocking for you, or build your own gate on the Consenter API. Either way, start by working out which consent you need to collect.
Choose your contextual consent type
Some third-party integrations process personal data solely to provide their service, while others also use data for their own additional purposes (e.g. advertising). The consent you need to collect — and therefore the type of contextual consent you implement — depends on which applies to your provider.
The three scenarios below show when contextual consent is needed and which type to use (type 1 or type 2).
If unsure whether your TPP requires contextual consent of type 1 or type 2, check out our TPP configuration guides or refer to the privacy policy or documentation of the TPP.
Add contextual consent to your site
Once you know which consent type you need, embed the provider behind a consent gate. There are two ways to do this:
- Built-in consent gate — add our script and a few HTML attributes, and Consenter renders the gate for you. This is the quickest option and the right default for most sites.
- Custom integration — load only the banner script, block the content yourself, and drive consent through the Consenter API. Choose this when you want full control over the gate’s look and behaviour.
Both methods identify the provider with the same Service ID and Purpose IDs from your banner, so you can switch between them later without reconfiguring — see Finding your Service and Purpose IDs.
Contextual consent only works if your Consenter Banner is configured correctly in the Consenter Manager: the purposes used by the third-party provider must match the purposes enabled in your banner. If they do not match, contextual consent cannot be applied.
Built-in consent gate
Add the two scripts below, then mark up the embed you want to gate. Consenter blocks the content, renders its consent gate in its place, and unblocks the content once the visitor consents (or immediately, if they already have).
- Add the contextual consent scripts
Place the contextual consent script at the top of the
<head>section:index.html <script src="https://banner.consenter.eu/contextual-consent.js"></script> <script src="https://banner.consenter.eu/YOUR_DOMAIN_ID/cb.js" async ></script> - Add Consenter attributes to your embed
Remove the original
srcattribute, and add Consenter data attributes inside the<iframe>where you want to enable contextual consent. Put the URL that should load after consent intodata-consenter-content-url, and indata-consenter-purpose-idslist the purpose IDs this service needs consent for — the same purposes you configured for it when you set up the banner. Replace the placeholders with your own values:index.html <iframe width="560" height="315" data-consenter-language="DE" data-consenter-tpp-id="YOUR_SERVICE_ID" data-consenter-tpp-label="YOUR-SERVICE-NAME" data-consenter-content-label="YOUR-CONTENT-DESCRIPTION" data-consenter-content-url="YOUR_SERVICE_URL" data-consenter-purpose-ids="additional-features,service-improvement,customise-ads" > ... </iframe>
The older per-purpose attributes
(data-consenter-tpp-purpose-improve-the-service,
data-consenter-tpp-purpose-marketing-analytics,
data-consenter-tpp-purpose-customise-ads) still work but are deprecated and
log a console warning. Migrate to a single data-consenter-purpose-ids
attribute.
What each attribute does (quick reference)
| Attribute | What it does | Notes |
|---|---|---|
data-consenter-tpp-id | Tells Consenter which TPP this embed belongs to. | Required. The service ID from your banner — see Finding your Service and Purpose IDs. |
data-consenter-tpp-label | Display name shown to the user (e.g., “YouTube video”). | Required. Use something users immediately understand. |
data-consenter-content-url | The URL that loads after the user unblocks / consents. | Required. Usually the original iframe/embed src. Remove the original src attribute so the content is blocked before consent. |
data-consenter-content-label | Short description of the specific content (e.g., “Product Demo”). | Required. Helps users understand what they are enabling. |
data-consenter-language | Sets the language of the contextual consent UI. | Optional. Supports EN and DE. If missing, the browser language is used when it is English; otherwise German is used. |
data-consenter-purpose-ids | Comma-separated list of the purpose IDs this flow needs consent for. | Required. Declare exactly the purpose(s) your case needs — one or several. See Finding your Service and Purpose IDs. |
Custom integration
The built-in gate renders Consenter’s own UI over the blocked content. If you want full control over the look and feel — your own “show the content” button, styling, and layout — you can build the gate yourself and drive consent through the Consenter API instead.
In this mode you load only the banner script (not contextual-consent.js),
block the third-party content yourself, then:
- call
grantContextualConsent(tppId, purposeIds)when the user opts in, and
See the JavaScript API for the full method reference.
<script src="https://banner.consenter.eu/YOUR_DOMAIN_ID/cb.js" async></script>Example
This example keeps a video blocked behind a custom button, grants consent on
click, and reveals the content once consent is saved. The same subscribe
callback also reveals the content immediately for visitors who have already
consented.
<div id="video-gate">
<p>This video is provided by Vimeo and may process your data.</p>
<button id="enable-video">Show the video</button>
</div>
<script>
// Vimeo uses data for its own purposes, so it needs all three.
var tppId = "YOUR_SERVICE_ID";
var purposeIds = [
"additional-features",
"service-improvement",
"customise-ads",
];
function revealVideo() {
document.getElementById("video-gate").innerHTML =
'<iframe src="https://player.vimeo.com/video/VIDEO_ID" allow="autoplay"></iframe>';
}
function wireUp() {
// state is an object keyed by purpose ID; fires now and on every change.
window.consenter.subscribe(
function (state) {
var granted = Object.keys(state).every(function (id) {
return state[id];
});
if (granted) revealVideo();
},
{ serviceId: tppId, purposeIds: purposeIds },
);
document
.getElementById("enable-video")
.addEventListener("click", function () {
var result = window.consenter.grantContextualConsent(tppId, purposeIds);
if (result !== "success") console.error("Consenter:", result);
});
}
if (window.consenter) {
wireUp();
} else {
document.addEventListener("consenter:ready", wireUp);
}
</script>Finding your Service and Purpose IDs
Both integration methods need your provider’s Service ID and the Purpose IDs it requires. Find them in the Consenter Manager:
- Select your website.
- Open your active banner version to reach the Technologies Configuration page.
- Hover over the service or purpose label and click the copy button in the tooltip.
Declare exactly the purpose(s) your case needs — one or several. The standard purpose IDs are:
| Purpose | Purpose ID |
|---|---|
| Unlock additional website features | additional-features |
| Improve the service | service-improvement |
| Support marketing analytics | marketing-analytics |
| Customise online ads | customise-ads |
How is this guide?
Shape Consenter Together
Consenter is built on an open and participatory process that grows through community collaboration. Whether you share feedback, improve the documentation, or contribute to the Risk Configuration Guides or Technical Integration Guides, your expertise helps make Consenter more privacy-friendly, interoperable, and useful for everyone—including your own users and services: Get finally your benefits and control the risks when sharing personal data.
Last updated on