Ketch web infrastructure tag!
-
NCC
npm i -g @vercel/ncc
npm install
npm run build
docker compose -f base.yml -f docker-compose.yml up --build
- Navigate to https://localhost:8080/ketchtag/test/?swb_debug
You can test ketch-plugins or lanyard locally by including the following in ./docker-compose.yml
under volumes
.
- "{path-to-local-directory}/dist/plugins.js:/ketch/public/plugins.js"
Then update ./test/fixtures/index.html
to point to the new file:
<script src="../plugins.js"></script>
The following querystring parameters are checked at various points during the initialization and operation of the Ketch tag.
parameter | allowed values | description |
---|---|---|
ketch_log (swb_log) | trace, debug, info, warn, error | enables console logging by Ketch components |
ketch_env (swb_env) | staging, production | overrides environment detection and uses a specific environment |
ketch_region (swb_region) | ISO-3166 country code | overrides region detection and uses a specific region |
ketch_jurisdiction (swb_p) | jurisdiction code | overrides jurisdiction detection and uses a specific jurisdiction |
ketch_lang (lang, swb_l) | ISO 639-1 language code, with optional regional extension | overrides language detection and uses a specific language |
ketch_show (swb_show) | cd, preferences | forces an experience to show |
ketch_preferences_tab (swb_preferences_tab) | overviewTab, rightsTab, consentsTab | forces a particular tab of the preferences experience to show |
Newer bootstrap tags include the definition of a ketch
function that should be the primary entrypoint
into the Ketch Tag API. The old semaphore.push
will still be supported until the next major release.
ketch('on', 'consent', consent => {
console.log('consent updated', consent)
})
The equivalent using semaphore.push
is as follows:
semaphore.push(['on', 'consent', consent => {
console.log('consent updated', consent)
}])
The remainder of the examples will use the ketch
function, but the equivalent semaphore.push
can be used.
The consent experience can be shown to a data subject using the following:
ketch('showConsent', {
// options
})
The preferences experience can be shown to a data subject using the following:
ketch('showPreferences', {
// options
})
The Ketch tag will emit a variety of events to allow integrating into a site and extending functionality.
To handle every occurrence of an event (consent
in this example), use the following:
function handleConsentChange(consent: Consent) {
// TODO - do something with the consent
}
ketch('on', 'consent', handleConsentChange)
To handle just a single occurrence of an event, use the following:
ketch('once', 'consent', handleConsentChange)
To stop handling events, use the following:
ketch('off', 'consent', handleConsentChange)
The consent
event is emitted whenever consent is resolved, either by loading from local storage, remote storage or
by prompting the user. The argument to the event is a consent object, where the keys are the purposes and the value is
a boolean denoting whether the user has consented to the purpose.
The environment
event is emitted whenever the environment is resolved from configuration.
The geoip
event is emitted whenever the location has been resolved from the IP address.
The identities
event is emitted whenever the identities collected about the user have changed.
The jurisdiction
event is emitted whenever the jurisdiction of the user has resolved or changed.
The regionInfo
event is emitted whenever the region information about the user has resolved or changed.
The willShowExperience
event is emitted when an experience is shown to the user.
The hideExperience
event is emitted when an experience is hidden from the user.
The Ketch tag exposes several properties available to interrogate.
To get the current configuration, use the following:
ketch('getConfig', handleConfig)
The Ketch Tag allows extending functionality by registering plugins. The plugin is a function that receives an instance of the Ketch Tag and the configuration of the plugin.
function myPlugin(host: Ketch, _config: any) {
host.on('consent', consent => {
console.log('consent changed to: ', consent)
})
}
ketch('registerPlugin', myPlugin)
To test the tag locally, run the following:
npm run all
docker compose --file base.yml up -d
docker compose up -d
open https://localhost:8080/ketchtag/test/
The test page is located in ./test/fixtures/index.html
. The configuration is in ./test/fixtues/boot.js
.