VisionPlayer Documentation | Module: src/consent/Consent

Version: 1.0.0
Author: Frank Kudermann - alphanull
License: MIT
Requires: DomSmith; object; ConsentError
Source: Consent.js, line 18

Constructor

Creates an instance of the Consent component.

Parameters:

Name Type Attributes Description

player

Player

Reference to the VisionPlayer instance.

parent

Player

Reference to the parent instance.

options

Object

optional

Additional options.

Parameters:

Name	Type	Attributes	Description
`apiKey`	symbol	optional	Token for extended access to the player API.

Members

private, static #purposeIds :Array<string>

Purpose tokens the overlay can turn into translated fragments.

Type: Array<string>
Source: Consent.js, line 24

private #config :Object

Holds the instance configuration for this component.

Properties

Name	Type	Attributes	Default	Description
`storage`	string	optional	'local'	Storage backend: `'local'`, `'session'` or `'none'`.
`storageKey`	string	optional	'vip-consent'	Key used in Web Storage.
`expires`	number	optional	180	Grant lifetime in days.
`privacyUrls`	Object	optional		Privacy-policy URLs keyed by service id. Set a value to `false` or `''` to hide that link.

Type: Object
Source: Consent.js, line 34

private #player :Player

Reference to the main player instance.

Type: Player
Source: Consent.js, line 48

private #apiKey :symbol

Secret key only known to the player instance and initialized components. Used to restrict access to API methods in secure mode.

Type: symbol
Source: Consent.js, line 55

private #services :Map<string, Consent~service>

Registered services keyed by id.

Type: Map<string, Consent~service>
Source: Consent.js, line 61

private, nullable #handler :Consent~consentHandler

External consent handler. When set, it replaces the internal overlay/storage path.

Type: Consent~consentHandler
Source: Consent.js, line 67

private #inFlight :Map<string, Promise<boolean>>

In-flight request() promises, keyed by service id, so parallel callers share one decision.

Type: Map<string, Promise<boolean>>
Source: Consent.js, line 73

private #memoryStore :Object

Fallback store used when Web Storage is unavailable or storage is 'none'.

Type: Object
Source: Consent.js, line 79

private, nullable #dom :DomSmith

Overlay DOM, created lazily and destroyed after the user decides.

Type: DomSmith
Source: Consent.js, line 85

private, nullable #settingsDom :DomSmith

Settings-menu row for revoking stored grants. Absent when the settings popup is not in the build.

Type: DomSmith
Source: Consent.js, line 91

private, nullable #overlayResolver :function

Resolver for the currently visible overlay.

Type: function
Source: Consent.js, line 97

private, nullable #overlayReject :function

Rejects the overlay waiter when the pending request is cancelled (engine switch).

Type: function
Source: Consent.js, line 103

private #subscriptions :Array<number>

Subscription tokens for player events.

Type: Array<number>
Source: Consent.js, line 109

Methods

private #assertApiKey(apiKeyopt)

Throws if secure mode is on and the caller did not pass the matching apiKey.

Parameters:

Name	Type	Attributes	Description
`apiKey`	symbol	optional	Token for extended access to the player API.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Consent.js, line 146

private #register(id, name, optionsopt, apiKeyopt)

Registers a service so the overlay can show a name, purposes and third-country notice. Does not grant or deny anything; request() still asks even for unknown ids.

Parameters:

Name	Type	Attributes	Description
`id`	string		Service id, e.g. `'youtube'`.
`name`	string		Display name used in the overlay and events.
`options`	Consent~serviceMeta	optional	Optional overlay metadata. Omit when passing `apiKey` as the third argument.
`apiKey`	symbol	optional	Token for extended access to the player API.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Consent.js, line 163

private #request(id, apiKeyopt) → Promise<boolean>

Awaits a consent decision for id. Shared in-flight callers reuse the same Promise.

Parameters:

Name	Type	Attributes	Description
`id`	string		Service id, e.g. `'youtube'`.
`apiKey`	symbol	optional	Token for extended access to the player API.

Fires: consent/required; consent/granted; consent/denied
Returns: true if the resource may load, otherwise false.; Type Promise<boolean>
Throws: If apiKey does not match in secure mode.

Type Error; AbortError if the overlay is dismissed because the engine changes.

Type DOMException
Source: Consent.js, line 198

private #setHandler(handler)

Registers or clears an external consent handler. Intended for cookie managers. A new handler replaces the previous one. Pass null to return to the internal path. Does not require an apiKey, so it remains usable when secureApi is on.

Parameters:

Name	Type	Description
`handler`	Consent~consentHandler \| null	Handler that returns a boolean or Promise.

Source: Consent.js, line 222

private #revoke()

Forgets all stored grants. Does not unload a provider that is already playing. Does not require an apiKey, so it remains usable when secureApi is on.

Source: Consent.js, line 235

async, private #resolveRequest(id) → Promise<boolean>

Resolves one consent decision for id via handler, storage, or overlay.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: Whether loading is allowed.; Type Promise<boolean>
Source: Consent.js, line 256

private #service(id) → Consent~service

Returns overlay metadata for id, with the id as the name when unregistered.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: Service record.; Type Consent~service
Source: Consent.js, line 284

private #emitResult(payload, granted)

Publishes granted/denied and, on deny, a consent-specific notification.

Parameters:

Name Type Description

payload

Object

Event payload.

Parameters:

Name	Type	Description
`id`	string	Service id.
`name`	string	Display name.

granted

boolean

Whether consent was given.

Source: Consent.js, line 297

private #hasGrant(id) → boolean

Returns true when a non-expired grant for id exists in storage.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: Whether a valid grant is stored.; Type boolean
Source: Consent.js, line 316

private #persistGrant(id)

Persists a grant for id. Denials are not stored so a retry does not need a storage wipe.

Parameters:

Name	Type	Description
`id`	string	Service id.

Source: Consent.js, line 337

private #readStore() → Object

Reads the consent store. Falls back to the runtime map if Web Storage throws.

Returns: Parsed store object.; Type Object
Source: Consent.js, line 353

private #writeStore(store)

Writes the consent store. Falls back to the runtime map if Web Storage throws.

Parameters:

Name	Type	Description
`store`	Object	Store object to persist.

Source: Consent.js, line 372

private #storage() → Storage

Returns the configured Web Storage object.

Returns: sessionStorage or localStorage.; Type Storage
Source: Consent.js, line 391

private #privacyHref(id) → string

Returns a safe http(s) href for the overlay privacy link, or an empty string to hide it.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: Absolute URL, or ''.; Type string
Source: Consent.js, line 402

private #purposeSentence(purposes) → string

Builds the purposes sentence, or an empty string when nothing usable was registered.

Parameters:

Name	Type	Description
`purposes`	Array<string>	Purpose tokens.

Returns: Translated sentence, or ''.; Type string
Source: Consent.js, line 422

private #countrySentence(code) → string

Builds the third-country sentence, or an empty string when no code was registered.

Parameters:

Name	Type	Description
`code`	string	ISO 3166-1 alpha-2 code.

Returns: Translated sentence, or ''.; Type string
Source: Consent.js, line 439

private #joinList(items) → string

Joins translated fragments with a localized separator and final conjunction.

Parameters:

Name	Type	Description
`items`	Array<string>	Translated fragments.

Returns: Joined list.; Type string
Source: Consent.js, line 455

private #overlayText(id) → string

Builds the overlay body from message, purposes and third-country fragments.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: Combined paragraph text.; Type string
Source: Consent.js, line 472

private #showOverlay(id) → Promise<boolean>

Shows the blocking overlay and waits for agree or decline.

Parameters:

Name	Type	Description
`id`	string	Service id.

Returns: User decision.; Type Promise<boolean>
Source: Consent.js, line 489

private #settleOverlay(granted)

Completes the overlay decision, removes the DOM, and resolves the waiter.

Parameters:

Name	Type	Description
`granted`	boolean	User decision.

Source: Consent.js, line 556

private #teardownOverlay()

Removes overlay DOM without resolving a pending waiter.

Source: Consent.js, line 567

private #abortOverlay()

Dismisses a pending overlay without grant or deny. Used when media switches away from the engine that opened it, so the overlay cannot cover the next item.

Listens: player/engine/set
Source: Consent.js, line 579

private #mountSettings()

Adds a revoke control to the settings popup when that popup exists in this build.

Source: Consent.js, line 592

private #syncRevokeButton()

Disables the revoke button when no grant is stored.

Source: Consent.js, line 620

private #hasStoredGrants() → boolean

Returns true when at least one non-expired grant exists in the store.

Returns: Whether a stored grant is present.; Type boolean
Source: Consent.js, line 632

private #unmountSettings()

Removes the settings revoke row. Used when an external handler owns consent UI.

Source: Consent.js, line 641

destroy()

This method removes all API methods and DOM nodes created by this component.

Source: Consent.js, line 651

Type Definitions

serviceMeta

Overlay metadata passed to register().

Properties

Name	Type	Attributes	Description
`thirdCountry`	string	optional	ISO 3166-1 alpha-2 code for a third-country transfer, e.g. `'US'`.
`purposes`	Array<string>	optional	Tokens: `'playback'`, `'cookies'`, `'advertising'`. Unknown values are ignored.

Type: Object
Source: Consent.js, line 663

service

Stored service record used by the overlay.

Properties

Name	Type	Description
`name`	string	Display name.
`thirdCountry`	string	ISO country code, or `''`.
`purposes`	Array<string>	Filtered purpose tokens.

Type: Object
Source: Consent.js, line 670

consentHandler(service) → boolean|Promise<boolean>

External handler invoked by request() when set. Receives the service id and display name.

Parameters:

Name Type Description

service

Object

Service being requested.

Parameters:

Name	Type	Description
`id`	string	Service id, e.g. `'youtube'`.
`name`	string	Display name.

Type: function
Returns: true to allow loading, false to deny.; Type boolean | Promise<boolean>
Source: Consent.js, line 678

Events

Fired when consent is about to be requested for a service.

Parameters:

Name Type Description

data

Object

Event payload.

Parameters:

Name	Type	Description
`id`	string	Service id.
`name`	string	Display name.

Source: Consent.js, line 687

Fired when consent was granted for a service.

Parameters:

Name Type Description

data

Object

Event payload.

Parameters:

Name	Type	Description
`id`	string	Service id.
`name`	string	Display name.

Source: Consent.js, line 695

Fired when consent was denied for a service.

Parameters:

Name Type Description

data

Object

Event payload.

Parameters:

Name	Type	Description
`id`	string	Service id.
`name`	string	Display name.

Source: Consent.js, line 703

Module: src/consent/Consent

Constructor

new Consent(player, parent, optionsopt)

Members

private, static #purposeIds :Array<string>

private #config :Object

private #player :Player

private #apiKey :symbol

private #services :Map<string, Consent~service>

private, nullable #handler :Consent~consentHandler

private #inFlight :Map<string, Promise<boolean>>

private #memoryStore :Object

private, nullable #dom :DomSmith

private, nullable #settingsDom :DomSmith

private, nullable #overlayResolver :function

private, nullable #overlayReject :function

private #subscriptions :Array<number>

Methods

private #assertApiKey(apiKeyopt)

private #register(id, name, optionsopt, apiKeyopt)

private #request(id, apiKeyopt) → Promise<boolean>

private #setHandler(handler)

private #revoke()

async, private #resolveRequest(id) → Promise<boolean>

private #service(id) → Consent~service

private #emitResult(payload, granted)

private #hasGrant(id) → boolean

private #persistGrant(id)

private #readStore() → Object

private #writeStore(store)

private #storage() → Storage

private #privacyHref(id) → string

private #purposeSentence(purposes) → string

private #countrySentence(code) → string

private #joinList(items) → string

private #overlayText(id) → string

private #showOverlay(id) → Promise<boolean>

private #settleOverlay(granted)

private #teardownOverlay()

private #abortOverlay()

private #mountSettings()

private #syncRevokeButton()

private #hasStoredGrants() → boolean

private #unmountSettings()

destroy()

Type Definitions

serviceMeta

service

consentHandler(service) → boolean|Promise<boolean>

Events

consent/required

consent/granted

consent/denied

Settings