Consent Docs

Put consent inside your own form

Show consent boxes inside your sign-up, upload or checkout form, and record the answers with the form from your server.

How-to2 min readFor web, backend and mobile developers

A form of the type Consent inside your own form is drawn inside a form on your page. It shows an information box, a box for each purpose and an optional "I have read the notice" box, all unticked. The answers go to your server with the form, which records them under the new account.

Before you start#

Add the boxes to your form#

  1. Put an element with the form's key where the boxes go, inside your <form>.

    HTML
    <form method="post" action="/signup">
      <input type="email" name="email" required>
      <div data-piedap-form="signup-20wz"></div>
      <button type="submit">Create account</button>
    </form>
  2. Leave the rest to the runtime. It draws the boxes, and the browser stops the form while a required box is unticked.

  3. On your server, read the field piedap_consent and record it under the new account.

    JavaScript
    const answers = JSON.parse(req.body.piedap_consent);
    await consent.recordConsent({
      ...answers,
      subjectId: user.id,
      subjectType: 'USER_ID',
      identifiers: [{ subjectType: 'EMAIL', subjectId: user.email }],
      countryCode: 'IN',
      interaction: 'SAVE_PREFERENCES',
    });

The field holds formKey, formVersion, acknowledged and one decision for each box. Sending formVersion files the record against the version the person saw. A form that asks for the notice box refuses a record without acknowledged: true, with ACKNOWLEDGEMENT_REQUIRED.

When the form asks "Are you 18 or older?", the field also holds ageDeclaration. A person under 18 cannot give the consent themselves. Recording it needs the verified parent or guardian in guardian, otherwise it is refused with GUARDIAN_CONSENT_REQUIRED. Send that person to your page for a parent or guardian.

In a React app#

React submits forms in code, so draw the boxes with block() and read them on submit.

JavaScript
function ConsentBlock({ formKey, blockRef }) {
  const element = useRef(null);
  useEffect(() => {
    let block;
    (window.piedapConsentQueue ||= []).push((consent) => {
      block = consent.block(element.current, { formKey });
      if (blockRef) blockRef.current = block;
    });
    return () => block?.destroy();
  }, [formKey]);
  return <div ref={element} />;
}

In your submit handler, stop when consentRef.current.reportValidity() is false. Otherwise send consentRef.current.value with the rest of the form.

Match your page#

The boxes take your page's font and colours. To set them for the form instead, use Look and Brand on the form. They follow the accent colour, corner radius, font, text and link colours there. For more, style the classes .pc-block, .pc-block-note and .pc-block-item in your own CSS.

Record from the browser instead#

Add data-piedap-record="browser" to record the answers from the page when the form is submitted. The record is filed under the browser's id, like the banner's. Use it where your server cannot record, and link the account later with an identity proof.

↑↓ to move, Enter to open