Skip to main content

Cookie Consent Plugin

Introduction​

The cookie consent plugin asks the user for permission on what cookies they wish to allow or disallow on a site.

Installation​

composer require jump/oc-cookie-consent-plugin`

If you're upgrading an older project, in your site config directory add, cookie.php and paste the contents below:

/config/cookie.php
<?php

return [
    'unencryptedCookies' => [
        'jump_cookie_consent',
        'jump_cookie_consent_4', // If you're using version >4
    ],
];

Repository​

Github

Getting Started​

Publishing Plugin Assets​

Herd​

In the root of the project run

herd php artisan vendor:publish --tag=cookie-assets

with --force if necessary

Docker​

Inside your docker container, docker-compose exec app sh, run

php artisan vendor:publish --tag=cookie-assets

with --force if necessary

Styles​

In your app.css

@import "components/CookieConsent";
@import "components/CookiePreferences";

Then customise your cookie css custom properties to match your sites theme.

--cookie-preferences-radio: #ddd;
--cookie-preferences-radio-dot: #fff;
--cookie-preferences-radio-hover: #ccc;
--cookie-preferences-radio-primary: #06c;

--cookie-consent-border: #000;
--cookie-consent-background: #fff;
--cookie-consent-text-on-background: #000;

Create the preferences page​

In the pages plugin section create a new page with the suggested url 'cookie-preferences' and include the cookie preferences page section and save.

Usage​

For cookie perfence types that are optional, any scripts, snippets or markup that will create or use the specific cookie should be wrapped in an if statment to check if the user has accepted or denied that cookie in their preferences.

{% if cookie_preferences_check('google-tag-manager') %}

    {{ tag_manager('script') }}

{% endif %}
info

Google Consent Mode in v4

If you're using version 4 or higher, Google Consent mode is baked in. You no longer need to wrap {{ tag_manager('script') }} in an if check. If upgrading a website, please remove the if check.

It should just read:

    {{ tag_manager('script') }}

By default the October session cookie type is registered automatically with the plugin as a required cookie type, as all sites will require this.

Analytics Cookie(s)​

If the analytics plugin is installed on your this will register analytics as an optional cookie usage.

info

If a cookie usage can be overwritten and set to required or optional from its default state if a site depends on it. This is done in the backend settings interface.

To create additional cookie perferences on a site for users to customise there experience you can regsiter cookie types in your app.

info

This will need to be registered in the Plugin.php in the registerCookies() function.

The easiest way is to use the create:cookie command but the files can be made manually if you wish.

php artisan create:cookie App.Site ExampleCookieType

This will generate a file in the cookies directory of the plugin.

<?php

namespace App\Site\Cookies;

use Jump\CookieConsent\Classes\CookieBase;

/**
 *
 */
class ExampleCookieType extends CookieBase
{
    /**
     * @inheritdoc
     */
    public function cookieDetails()
    {
        return [
            'name' => 'ExampleCookieType',
            'description' => 'No description provided yet...',
            'preference' => self::OPTIONAL,
            'editable' => true,
        ];
    }
}

The options for preference are REQUIRED or OPTIONAL (default). If a cookie type is required the user cannot opt out of its usage due to its critical business requirement.

Each cookie type will be listed on the cookie preferences page so users can customise their experience and choose which cookies to allow or deny.

info

Remember to wrap any scripts, iframes etc. that use this new cookie in an if cookie_preferences_check, so it is not ran before accepting or denying.

info

Google Consent Mode in v4

CookieBase now has a new getGoogleConsentType method for returning a Google Consent Type string. If provided, the user accepting or denying that cookie will also set their consent type within GTM (via gtag)

Troubleshooting​

  • If you receive an error when viewing the cookie preferences page the first time, be sure to go to the cookie consent settings and do the initial save. /backend/system/settings/update/jump/cookieconsent/settings#primarytab-consent-popup
  • If the cookie popup is showing on every page after it has been dismissed or accepted, check the config/cookie.php file of the site has the cookie listed as unencrypted so the JavaScript can read it (Should only apply to sites on October v1)
    'unencryptedCookies' => [
        'jump_cookie_consent',
        'jump_cookie_consent_4', // If you're using version >4
    ],
danger

For older October 1.0 sites, ensure you are on at least 1.0.438 (which added support for unencrypted cookies)