Services and groups

A service is anything the site loads from another server: a tracker, a chat widget, an embed. Silvertrail holds each one back until the visitor agrees to it. Every service belongs to a group, and the banner asks per group and per service.

Register a service

Register services on the silvertrail_register action, in a small plugin or the theme:

add_action( 'silvertrail_register', function () {
	silvertrail_register_service( 'hubspot', [
		'group'       => 'marketing',
		'name'        => 'HubSpot',
		'provider'    => 'HubSpot, Inc.',
		'purpose'     => 'Tracks form conversions.',
		'privacy_url' => 'https://legal.hubspot.com/privacy-policy',
		'hosts'       => [ 'js.hs-scripts.com' ],
		'handles'     => [ 'hubspot-tracking' ],
	] );
} );
Key Type Default What it does
group string none, required The group the service belongs to. A service in a group that does not exist is skipped.
name string the ID The name the banner shows.
provider string '' The company behind the service, with its address.
purpose string '' What the service does, in one sentence.
privacy_url string '' The provider's privacy policy.
cookies string '' The cookies it sets, as text.
expiry string '' How long they last, as text.
hosts list [] Hosts, or host and path, such as google.com/maps. Embeds from them wait behind a placeholder, and the trail and the Leak check name requests to them.
handles list [] Script handles held back until consent, with their before and after code.
google list [] The Consent Mode types the service grants, such as analytics_storage.
consent 'required' or 'exempt' 'required' An exempt service never needs a decision.
tag_id string '' The ID of a tracker preset, such as GTM-XXXXXXX.

A service ID starts with a lowercase letter or a digit and goes on with lowercase letters, digits, - and _. Registering the ID of a preset, or of a service the admin turned on, changes only the given fields. Registering the same ID twice keeps only the second call.

A host matches itself and every subdomain, so facebook.com also covers www.facebook.com. A pattern with a path, such as google.com/maps, matches only URLs whose path starts with it. Silvertrail strips https://, // and www. from each pattern.

The config always holds a service with the ID silvertrail in the essential group. It lists Silvertrail's own cookie in the banner, and code cannot remove it.

Keep the config the same on every request, because Silvertrail asks every visitor again whenever the set of services changes. A banner opens only when at least one service outside the essential and in-place groups needs consent.

Presets

Silvertrail ships eight presets. The tracker presets print the provider's official tag once their ID is set. The embed presets start switched on.

ID Group ID format Grants in Consent Mode
google-tag-manager marketing Container ID, GTM-XXXXXXX ad_storage, ad_user_data, ad_personalization, analytics_storage
google-analytics statistics Measurement ID, G-XXXXXXXXXX analytics_storage
google-ads marketing Conversion ID, AW-123456789 ad_storage, ad_user_data, ad_personalization
linkedin-insight marketing Partner ID, 123456 none
meta-pixel marketing Pixel ID, 1234567890 none
youtube external-media none none
vimeo external-media none none
google-maps external-media none none

Registering a preset's ID turns it on with its defaults, and only the given fields change:

add_action( 'silvertrail_register', function () {
	silvertrail_register_service( 'google-tag-manager', [ 'tag_id' => 'GTM-XXXXXXX' ] );
	silvertrail_register_service( 'youtube', [ 'cookies' => 'VISITOR_INFO1_LIVE, YSC' ] );
} );

To remove a service, even one the admin turned on, unset it in the silvertrail_config filter:

add_filter( 'silvertrail_config', function ( $config ) {
	unset( $config['services']['google-maps'] );
	return $config;
} );

The Services tab marks each preset that code turned on, changed or removed. wp silvertrail services and the silvertrail/list-services ability show the same.

Groups

The groups are essential, preferences, statistics, marketing and external-media. Add your own, or change one, with silvertrail_register_group() on the same action:

add_action( 'silvertrail_register', function () {
	silvertrail_register_group( 'support', [
		'name'        => 'Support',
		'description' => 'Lets you chat with us on this page.',
		'consent_api' => 'preferences',
	] );
} );
Key Type Default What it does
name string the ID The name the banner shows.
description string '' One sentence under the name.
locked bool false A locked group is always on. essential is always locked.
consent_api string 'marketing' The WP Consent API category: functional, preferences, statistics, statistics-anonymous or marketing.
in_place bool false Its services ask on their placeholder and never open the banner. external-media asks in place.
Group Locked WP Consent API Asks in place
essential yes functional no
preferences no preferences no
statistics no statistics no
marketing no marketing no
external-media no marketing yes

A group that asks in place suits embeds only. A service in it that lists handles or a tag_id gets a warning, because the banner never prompts for it.

The config filter

The silvertrail_config filter runs last, after every registration and the admin's presets. It receives the whole config and returns it:

[
	'groups'   => [ 'essential' => [ 'name' => …, 'description' => …, 'locked' => true, 'consent_api' => 'functional', 'in_place' => false ], … ],
	'services' => [ 'hubspot' => [ 'group' => 'marketing', 'name' => 'HubSpot', … every key from the table above ], … ],
	'google'   => [ 'mode' => 'basic', 'url_passthrough' => false ],
]

Under google, mode is basic or advanced, and url_passthrough passes ad click IDs in links while ad cookies are denied:

add_filter( 'silvertrail_config', function ( $config ) {
	$config['google']['mode']            = 'advanced';
	$config['google']['url_passthrough'] = true;
	return $config;
} );

Unknown keys, unknown Consent Mode types, a service in a group that does not exist and a tracker ID from code that does not fit its preset each trigger a _doing_it_wrong notice. wp silvertrail validate lists them.

Gate a script

Mark a script in the HTML, and the browser ignores it until the visitor agrees to its service:

<script type="text/plain" data-silvertrail="hubspot" src="https://js.hs-scripts.com/123.js"></script>

Then Silvertrail swaps in a real script and keeps the order of inline and external scripts. A module keeps its type in data-silvertrail-type:

<script type="text/plain" data-silvertrail="hubspot" data-silvertrail-type="module" src="/widget.js"></script>

A script that WordPress enqueues needs no change. List its handle under the service's handles, and Silvertrail gates it together with the code WordPress adds before and after it. Data from wp_localize_script() stays as it is, because it loads nothing.

To find the handle of a script another plugin adds, open the page's source. WordPress prints the script as <script src="…" id="example-tracker-js">, and the handle is the ID without -js:

add_action( 'silvertrail_register', function () {
	silvertrail_register_service( 'example-tracker', [
		'group'   => 'statistics',
		'name'    => 'Example Tracker',
		'purpose' => 'Counts visits and page views.',
		'handles' => [ 'example-tracker' ],
		'hosts'   => [ 'cdn.example-tracker.com', 'collect.example-tracker.com' ],
	] );
} );

A script that a plugin prints as plain HTML has no handle. Ask its author for a filter, or turn the plugin's output off and print the tag yourself, gated as above.

A gated script that waits for DOMContentLoaded misses it, because the event has passed by the time the visitor agrees. Such a service starts only on the next page. The Leak check reports it.

Embeds

Every <iframe> whose address matches a service's hosts waits in an empty <template> behind a placeholder, unless the service is essential. Silvertrail finds them in oEmbeds, in post content, in Custom HTML blocks anywhere, including templates, template parts and patterns, and in text and HTML widgets. The placeholder asks for this once or for good, and opens no banner.

An iframe that the theme prints in PHP passes none of these filters. Render it as a Custom HTML block, so it gets its placeholder too:

echo do_blocks( '<!-- wp:html --><iframe src="https://www.youtube-nocookie.com/embed/VIDEO" title="Video"></iframe><!-- /wp:html -->' );

Styling shows how to change the placeholder's markup.

To read the visitor's choice in PHP or in the browser, see the API.