Skip to main content

Embedded flow

The CDK provides an End-to-End widget that handles the complete Verifiable Parental Consent (VPC) flow within a single interface, covering age gate, VPC, data notices, permissions, and preferences all in one seamless experience.

What's the end-to-end widget?​

The End-to-End Widget is a comprehensive solution that handles the complete compliance flow in a single interface, covering age gate, VPC, data notices, permissions, and preferences all in one seamless experience. This widget can be used by parents either on the child's device or on their own device, providing maximum flexibility for the consent process.

Generating the widget URL​

Call the /widget/generate-e2e-url API to create an end-to-end widget URL that handles the complete VPC flow. This returns a unique URL for users to complete the age collection and parental consent process.

Example request​

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

{
  "jurisdiction": "US-CA"
}

Configuration flags​

The optional flags parameter allows you to customize which parts of the flow to skip:

  • skipDataNotices: Skip data notices and consent collection
  • skipVerification: Skip verification step
  • skipPermissions: Skip permission management
  • skipPreferences: Skip preference settings

Pass a platform age signal (optional)​

If your game already has age data from the platform (Apple iOS, Google Play, Xbox, Meta Horizon, or a prior k-ID verification), include it as platformAgeSignal in the request body. The widget forwards the signal to the underlying age-gate check so it can skip the age gate when a verified signal indicates an adult, satisfy verified-age permissions without an extra verification step, and detect conflicts between the signal and the player's self-reported age.

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

{
  "jurisdiction": "US-CA",
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}

For the supported platforms and field shapes, see Platform age signals.

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 complete the age collection and trusted adult consent process through this interface, with available methods automatically adapting to jurisdictional requirements.

<div id="vpc-container">
  <iframe 
    id="vpc-widget"
    src="WIDGET_URL" 
    width="100%" 
    height="600"
    frameborder="0"
    allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
  </iframe>
</div>

Handling events​

When the age gate flow completes, a session is created to store the player's permissions and age status. A challenge is created whenever the flow needs one, either for Verifiable Parental Consent or for Automatic age assurance when the player claims an age old enough to skip parental consent.

The widget emits JavaScript events that you can listen to. Listen for the Widget.AgeGate.Result event, which includes a sessionId when the flow completes successfully. If a challenge was created during the flow, the event also includes the challengeId. For detailed information about challenge-specific events, see Widget.AgeGate.Challenge.

Closing the UI

Listen for the Widget.ExitReview event to determine when to close the widget UI. This event is emitted when the user clicks the 'Done' button, indicating the flow is complete and the iframe should be closed or hidden.

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  if (message.eventType === 'Widget.AgeGate.Result') {
    if (message.data.status === 'PASS') {
      const sessionId = message.data.sessionId;

      // If challengeId is present, a challenge was resolved during the flow
      // (for example, parental consent or auto age-assurance).
      if (message.data.challengeId) {
        console.log('Challenge resolved, session issued:', sessionId);
      } else {
        console.log('Session created (no challenge required):', sessionId);
      }

      grantAccess(sessionId);
    }
  }
  
  // Handle challenge-specific events if needed
  if (message.eventType === 'Widget.AgeGate.Challenge') {
    if (message.data.status === 'FAIL') {
      // Parent denied consent - restrict access
      console.log('Consent denied');
      restrictAccess();
    }
  }
  
  if (message.eventType === 'Widget.ExitReview') {
    // Close the widget UI when the user clicks 'Done'
    closeWidget();
  }
});

What the widget handles​

The widget automatically handles:

  • Age Collection: Jurisdiction-appropriate age collection methods
  • Data Notices: Data notices to accept, depending on the product's configuration in the Compliance Studio
  • Permissions: Permissions to manage, depending on the product's configuration in the Compliance Studio
  • Parental Consent Challenge: If the user is determined to be a minor, a challenge is created for trusted adult approval
  • Automatic age assurance: If the product has Automatic age assurance enabled for the jurisdiction, players who claim an age old enough to skip parental consent are asked to prove the claim (facial age estimation or ID document) inside the widget before a session is issued.

The specific flow depends on the jurisdiction and your product's configuration in the Compliance Studio.

Session creation timing with Automatic age assurance

When Automatic age assurance triggers inside the end-to-end widget, the session is created after the player passes verification rather than immediately after the age gate. The Widget.AgeGate.Result event is still fired once the flow completes and includes the sessionId on PASS. Until the event arrives, treat the flow as in progress.

For more information on implementing VPC, see the Quick Start Guide.