Consent Docs
Open console

Let visitors choose partners

Let a visitor allow a purpose and still switch off one of its partners, then hold each partner's tag and read the answer in your code.

How-to2 min readFor web, backend and mobile developers

A purpose can name the partners it shares data with, such as Google Analytics and Matomo under analytics. With partner choices on, a visitor can allow the purpose and still switch one partner off.

Before you start#

  • Each purpose lists its partners. See Add partners.
  • You can edit and publish the form.

Turn partner choices on#

  1. In the console, open Consent forms and choose the form.
  2. In Settings, switch on Let visitors choose partners one by one.
  3. Publish the form.

The setting is frozen into each published version, so it takes effect at the next publish. In the preferences dialog, a purpose with partners now shows Choose partners. Opening it lists each partner with its own switch.

Hold and read one partner#

Tags, cookies and the API name a partner by its key. If you set no key in the console, one is made from the name: Google Analytics becomes google-analytics.

  1. Add data-partner next to data-consent on each partner's tag. data-consent must be the purpose key here, not a category.

    HTML
    <script type="text/plain" data-consent="analytics"
        data-partner="matomo"
        src="https://matomo.example.in/matomo.js"></script>

  2. In your own code, pass the partner key as the second argument.

    JavaScript
    PiedapConsent.hasConsent('analytics', 'matomo');

PiedapConsent.whenGranted('analytics', 'matomo').then(() => {
  console.log('Matomo may run');
});

  3. Open your site, allow analytics in the preferences and switch Matomo off.

The Matomo tag stays held while the other analytics tags run. PiedapConsent.getConsent().partners lists every answer:

JSON
{ "analytics": { "google-analytics": true, "matomo": false } }

hasConsent('analytics') stays true while at least one partner is allowed. Ask for the partner when a tag belongs to one. A partner key the purpose does not list is never allowed.

Automatic blocking and Consent Mode ignore partners

Automatic blocking releases a host when its category is allowed, and Google Consent Mode signals follow purposes. To hold one partner's tag, mark it up as above.

How answers combine#

The runtime and the API apply the same rules.

Situation Result
The purpose is refused Every partner is refused
The purpose is allowed and every partner is refused The purpose is recorded as refused
The purpose is allowed and a partner is not answered That partner is allowed
The purpose is allowed and some partners are refused The answers are stored, and they list every partner
The purpose is always on Every partner stays on

Accept all and Reject all set every partner. A stored decision without partners means all partners follow the purpose.

Read partner answers on your server#

While a partner is off under an allowed purpose, the runtime writes a second cookie, piedap_partners. The server helpers read both cookies:

Node.jsJavaScript
import { consentFromCookieHeader } from '@piedap/consent/server';

const consent = consentFromCookieHeader(req.headers.cookie);
const matomoAllowed = consent?.granted('analytics', 'matomo') ?? false;
Python
from piedap_consent import parse_consent_cookie

consent = parse_consent_cookie(
    request.cookies.get("piedap_consent"),
    request.cookies.get("piedap_partners"),
)
matomo_allowed = bool(consent and consent.granted("analytics", "matomo"))

The cookie format is in Cookies and browser storage. Records and consent webhooks carry the same answers as partners on a decision. To send them yourself, see Record consent from your server.

Where IAB TCF applies, IAB vendors are a separate list and their answers go into the TC string, not into partners. See Turn on IAB TCF and GPP.

↑↓ to move, Enter to open