WordPress
Install CookieBeam on WordPress with the plugin. It adds the banner first in the head, adds shortcodes for the declaration, policy and settings link, and supports the WP Consent API.
The CookieBeam plugin puts your banner on a WordPress site without editing the theme. It loads the banner as the first script in <head> and keeps caching and optimisation plugins away from it. It also adds shortcodes for your cookie declaration, your cookie policy and a "Cookie settings" link.
Requires WordPress 6.0 or newer and PHP 7.4 or newer.
Install
- In WordPress, go to Plugins → Add New Plugin → Upload Plugin and upload the CookieBeam plugin zip, then activate it. (The plugin isn't in the WordPress.org directory yet, so searching for it won't find it.)
- In the CookieBeam dashboard, open the banner and go to Deployment → Install. Copy the banner ID, which is the UUID in the script URL:
https://cdn.cookiebeam.com/banner/123e4567-e89b-12d3-a456-426614174000/default/loader.js - In WordPress, go to Settings → CookieBeam, paste the ID and save. You can paste the whole install snippet instead; the plugin takes the ID from it.
- Make sure the site's domain is listed on the banner in CookieBeam, then publish the banner.
If you previously pasted the CookieBeam <script> tag into the theme or a header-scripts plugin, remove it. Otherwise the banner loads twice.
Environments
Leave Environment empty on the live site. On a staging site, enter the environment's slug (for example staging) to load the version published to that environment:
https://cdn.cookiebeam.com/banner/<id>/env/staging/loader.jsScript placement and optimisation plugins
The plugin prints the loader at wp_head priority -1000. That comes before WordPress prints enqueued scripts and before almost every other plugin, so the banner is in place before any tracker it has to block.
With Optimisation plugins enabled (the default), the plugin keeps the banner from being deferred, delayed, combined or minified by:
- WP Rocket
- LiteSpeed Cache
- Autoptimize
- SiteGround Optimizer
- Perfmatters
It does this through each plugin's exclusion filters and the per-tag attributes they understand (nowprocket, data-no-optimize, data-noptimize, data-no-defer). Cloudflare Rocket Loader is handled by data-cfasync="false", which has its own setting.
If you use a different optimiser, exclude cdn.cookiebeam.com from its defer, delay and combine features yourself. Full-page caching is fine, because the banner decides in the browser.
Shortcodes
| Shortcode | Shows |
|---|---|
[cookiebeam_declaration] | Your cookie declaration: every cookie the scanner found, grouped by category. Use it once per page. |
[cookiebeam_policy] | Your hosted cookie policy. |
[cookiebeam_settings_link text="Cookie settings"] | A link that reopens the consent preferences. Add class="…" to style it. |
If no banner ID is set, the declaration and policy shortcodes show a setup hint to administrators and nothing to visitors.
"Cookie settings" in a menu
Most privacy laws expect visitors to be able to change their choice later. There are two ways to add a menu link for it:
- Classic themes: under Appearance → Menus, open the CookieBeam box, tick Cookie settings and click Add to Menu.
- Block themes: in the Navigation block, add a Custom Link with the URL
#cookiebeam-settings.
Any link to #cookiebeam-settings works the same way, in a footer widget, a button block or a page.
Behind the scenes these links call CookieBeam.showPreferences(). Links rendered by the plugin also carry data-cb="show-preferencesModal", which the banner handles itself.
WP Consent API
If the WP Consent API plugin is active, CookieBeam registers as the site's consent plugin and passes the visitor's choice to wp_set_consent(). Plugins that check consent through the API, such as WooCommerce and Site Kit, then follow the banner.
| WP Consent API category | Allowed when |
|---|---|
functional | Always |
preferences | functionality_storage or personalization_storage is granted |
statistics, statistics-anonymous | analytics_storage is granted |
marketing | ad_storage, ad_user_data or ad_personalization is granted |
The mapping reads the Consent Mode state the banner already resolved, so regional rules and Global Privacy Control are already applied. Withdrawing consent denies everything except functional.
Before the visitor chooses, the plugin reports the consent type as optin. To change that, use the cookiebeam_wp_consent_type filter.
AMP
The plugin doesn't add the banner to AMP pages (the official AMP plugin's amp_is_request()), because AMP can't run it. Use amp-consent there.
Developer hooks
| Hook | Type | Use |
|---|---|---|
cookiebeam_should_output_script | filter, bool | Skip the banner on specific requests. |
cookiebeam_head_priority | filter, int | wp_head priority of the script (default -1000). |
cookiebeam_script_attributes | filter, array | Attributes of the <script> tag. |
cookiebeam_loader_url | filter, string | The script URL. |
cookiebeam_optimizer_exclusions | filter, array | Patterns passed to optimisation plugins. |
cookiebeam_wp_consent_type | filter, string | Consent type reported to the WP Consent API. |
cookiebeam_cdn_url, cookiebeam_app_url | filter, string | Service base URLs. Also settable with the COOKIEBEAM_CDN_URL and COOKIEBEAM_APP_URL constants. |
Uninstalling
Deactivating the plugin removes the banner. Deleting the plugin also removes its settings, on every site of a multisite network.