Developer guide

This guide is for web, backend and mobile developers who connect a site, a server or an app to PIEDAP Consent. It shows how to install the browser runtime, hold tags until a visitor allows them and read the choice in your code. It also covers recording consent from your server, handling rights requests and receiving webhooks.

Start with#

Install on a website to show the banner on your pages.
Keys and where to use them before you call the API from a server.
Test your integration before you ask for a live key.

On your website

Install on a websiteAdd the consent runtime to every page with one script tag, set its options, and pin a version or bundle it with npm.
Tag managers and CMSLoad the consent runtime through Google Tag Manager, the WordPress plugin or a Shopify theme when you cannot edit the page head yourself.
Hold tags until consentKeep scripts and iframes from running until the visitor allows them, with markup you add or automatic blocking of known hosts.
Read the choiceAsk the runtime what the visitor allowed, wait for a purpose before loading something, and react when the choice changes.
Let visitors choose partnersLet 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.
Style the bannerRestyle the banner with custom CSS or replace its first layer with your own HTML, and keep accept and reject equal so your styling is used.
Content Security PolicyAdd the sources the consent runtime needs to your Content Security Policy so the banner loads, is styled and can record a choice.

Ad signals, and laws outside India

Google Consent ModeWhat the runtime sends to Google Consent Mode v2 and other ad tags, when it sends it, and how each purpose category maps to a signal.
Turn on IAB TCF and GPPSwitch on the IAB Transparency and Consent Framework and the Global Privacy Platform for a form, install their stubs and read the strings.
Global Privacy ControlHow the runtime treats a browser's Global Privacy Control signal, which purposes it refuses, and where the signal changes nothing.

On your server

Keys and where to use themWhat the publishable key, the secret key and the identity secret are for, where each one belongs, and how scopes limit a secret key.
Record consent from your serverRecord a person's answers with a secret key when consent is given outside the banner, then change or withdraw the record.
Bring in consent given earlierRecord consent collected before you used the product, from your server, with its date, basis and notice, without replacing newer answers.
Branch, phone and paper consentSeal how consent was taken outside your website, with the channel, how the person confirmed and your reference to the evidence.
Check consentAsk whether a person allows a purpose now, by the identifier your systems use, and act on the answer before you send or share.
How a check decidesWhich of a person's records a consent check reads, which answer wins, and what never counts as yes.
Signed-in visitorsHave the banner record a signed-in visitor's answers under their account, with an identity proof your server computes.
IdentifiersHow a person is named in a consent record, how identifiers are hashed, and what linked identifiers, fingerprints and identity proofs do.
Set up email double opt-inStart a confirmed email opt-in from your server, email the confirmation link yourself, and add an unsubscribe link to your messages.

People and rights

Find a person's recordsList every consent record held for one person by an identifier your systems use, and link identifiers you learn later.
Withdraw or erase a personWithdraw everything a person agreed to, or erase what identifies them, with one call from your server, and act on the webhooks that follow.
Pass instructions to processorsRead the stop and erase instructions in withdrawal and erasure webhooks, pass them to your Data Processors and report back what each one did.
Answer an access requestExport one package with a signed receipt for every record a person has, link a rights request to your own id, and check the receipts.
Link to the hosted pagesLink to the privacy notice, rights request form and "Your consents" page your deployment serves, from your site and your emails.
Notice campaign linksFetch a notice campaign's links when a batch is ready, send them through your own mailer or SMS gateway, and act on the withdrawals people make.
Consent ManagersName a registered Consent Manager, hand it a key, and record the consent and withdrawals people send through it as sealed records.

Webhooks

Receive webhooksAdd a webhook endpoint, write a receiver that checks each delivery and handles it once, and plan for retries and events out of order.
Verify webhook signaturesCheck the signature and timestamp on every webhook delivery, in Node.js, Python, PHP or any language, and send yourself a signed test event.
Match events to your usersTell which of your users a webhook is about, by the consent id you saved, the subject fingerprint or a readable reference.

Apps and testing

Record consent in a mobile appUse the iOS or Android SDK to fetch the form, show your own consent screen, record the answer and gate your app's features on it.
Test your integrationTry every path with a test key, read the test flag on records and webhooks, check your retries, and confirm the list before you go live.
Run the sample appSet up and run Kalpa Learning, a small Node.js and Express site that shows a complete integration, and see where each part lives.