@playkit-js/user-kava-consent

Consent controller for KAVA analytics in Kaltura Player v7. The bundle installs a page-wide, fail-closed gate as soon as it is evaluated and gates both KAVA's internal events and direct sendAnalytics calls.

The tested compatibility matrix is:

• @playkit-js/playkit-js-kava 1.16.1
• @playkit-js/kaltura-player-js 3.17.77
• @playkit-js/playkit-js 0.84.x

Loading

Load the scripts before calling KalturaPlayer.setup, in this order:

<script src="kaltura-ovp-player.js"></script>
<script src="playkit-kava.js"></script>
<script src="playkit-user-kava-consent.js"></script>

Enable both runtime plugins:

const player = KalturaPlayer.setup({
  // ...
  plugins: {
    kava: {},
    userKavaConsent: {}
  }
});

Analytics starts disabled. Calls made while disabled resolve immediately and are dropped; they are never queued or replayed.

Message protocol

Grant or revoke consent by posting a boolean consent value:

playerFrame.contentWindow.postMessage({ type: 'userKavaConsent', consent: true }, '*');
playerFrame.contentWindow.postMessage({ type: 'userKavaConsent', consent: false }, '*');

Incoming consent messages are accepted from every origin by default. Set allowedOrigins to restrict accepted MessageEvent.origin values. A '*' entry permits every origin.

When initialized inside a frame, the plugin sends { type: 'userKavaConsentReady' } to its parent and top windows. A shared parent/top target is notified only once. Configure the protocol through the player plugin config:

plugins: {
  userKavaConsent: {
    messageType: 'analyticsConsent',
    readyMessageType: 'analyticsConsentReady',
    allowedOrigins: ['https://embed.example'],
    targetOrigins: ['https://embed.example'],
    consentFieldName: 'privacy.analytics.consent'
  }
}

targetOrigins defaults to ['*']. Each configured value is used as a postMessage target origin for the parent and top windows. When the list contains '*', one wildcard notification is sent per distinct target window.

consentFieldName defaults to consent and supports dot-separated property paths. For example, a value of privacy.analytics.consent reads this message:

{
  type: 'analyticsConsent',
  privacy: { analytics: { consent: true } }
}

Failure behavior

• If KAVA is absent, an invalid kava fallback is registered so it cannot load later outside the gate.
• If the exported KAVA class lacks the expected sendAnalytics method, KAVA is disabled through its isValid hook.
• If an unknown kava plugin is already registered but cannot be patched, startup throws synchronously rather than running analytics without consent enforcement.

Testing

Install the Playwright browsers once after installing dependencies:

yarn playwright install

Run unit, production-bundle, and browser integration tests:

yarn test

Run the Chromium smoke test against the current canary Player and KAVA UMD bundles served by unpkg:

yarn test:e2e:canary

The smoke loads a Kaltura CDN video, verifies that real playback time advances, and checks network requests generated by KAVA's internal playback event handlers while consent is closed, granted, and revoked. The Canary E2E Smoke GitHub Actions workflow runs it every weekday at 06:17 UTC and can also be started manually. It records the resolved canary versions in the Playwright report and uploads the report and failure traces for 14 days.