Skip to main content

Data notices

When building custom VPC flows with the k-ID API, you can use the data notices widget to display product data notices and collect user consent. The widget shows jurisdiction-appropriate disclosures and handles the consent acceptance workflow.

For general information about data notices, including when they're required, and what data is stored, see Data Notices in the Core concepts section.

Generating the data notices widget URL​

Call the /widget/generate-direct-notices-url API to create a data notices widget URL. This returns a unique URL for users to view and accept data notices.

Example request​

POST /api/v1/widget/generate-direct-notices-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
}

Request parameters​

PropertyDescriptionRequired?
jurisdictionThe jurisdiction in which the data notices should be displayedYes
sessionIdThe session ID for the player (if available)No

Example response​

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

Embedding the widget​

Use the returned URL to create an iframe in your website or app. Users view data notices and provide consent through this interface:

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

Data notice consent is tracked as part of the session. When data notices are accepted, the consent is recorded in the session. You can check data notice consent status in the session by calling the /session/get API.

For real-time updates, you can also listen for session-related events:

JavaScript events (client-side)​

For detailed information about the event structure, see Widget.DataNotices.ConsentApproved.

If the data notices widget is embedded in an iframe, you can listen for window messages from the widget:

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // Handle widget completion events
  if (message.eventType === 'Widget.DataNotices.ConsentApproved') {
    // Data notices have been accepted
    console.log('Data notices accepted:', message.data.jurisdiction);
    handleConsentAccepted();
  }
});

Example event:

{
  "eventType": "Widget.DataNotices.ConsentApproved",
  "data": {
    "jurisdiction": "US"
  }
}

Webhooks (server-side)​

For detailed information about the webhook event structure, see Session.ChangePermissions.

Configure a webhook endpoint to receive session-related events. When data notice consent is updated, session changes are reflected in Session.ChangePermissions events. For more information, see Webhooks.

Data notices and sessions​

When a session is created, data notice consents are included in the session. The session tracks which data notices have been accepted and when they were accepted. You can retrieve the session by calling the /session/get API to check data notice consent status.

For more information about how data notices work with sessions, see Data Notices in the Core concepts section.