django-cookie-optin

A django application that helps you manage opt-in cookie consent as required by the General Data Protection Regulation (GDPR) with the use of Klaro as consent manager.

Install

• run pip install django-cookie-optin
• add cookie_optin to your INSTALLED_APPS
• add parler to your INSTALLED_APPS
• run python manage.py migrate cookie_optin
• load initial data with
  • django-admin loaddata cookie_optin

Klaro is bundled in cookie_optin/static/cookie_optin/klaro.js (from kiprotect/klaro master).

Project setup

URLs

Add to your root urls.py:

from cookie_optin.views import ConsentApiView

urlpatterns = [
    path("cookie-optin/", include("cookie_optin.urls", namespace="cookie_optin")),
    path("cookie-optin/api/", ConsentApiView.as_view(), name="cookie_optin_api"),
    # ...
]

The cookie-optin/ include provides: config.js, api/, overview/. The cookie-optin/api/ path is where Klaro sends consent data (must match COOKIE_OPTIN_API_PATH).

Settings

# Required: URL of your privacy policy page
COOKIE_OPTIN_PRIVACY_URL = reverse_lazy("legalnotice:privacy")  # or "/privacy/"

# Optional: path where Klaro sends consent data (default: "/cookie-optin/api/")
COOKIE_OPTIN_API_PATH = "/cookie-optin/api/"

# Optional: store consent records in DB for analytics (default: True)
COOKIE_OPTIN_STORE_CONSENT_RECORDS = True

# Optional: enable consent overview/monitoring in CMS toolbar (default: False)
COOKIE_OPTIN_ENABLE_OVERVIEW = True

# Optional: cache the config.js response (default: False). When True, config.js is cached per host
# and invalidated automatically when Purpose, Application or Cookie change (or on m2m change for
# Application.purposes). Use manage.py invalidate_cookie_optin_config_cache to invalidate manually.
COOKIE_OPTIN_CONFIG_CACHE = True

# Optional: TTL in seconds for the config.js cache (default: 3600). Used only if COOKIE_OPTIN_CONFIG_CACHE is True.
COOKIE_OPTIN_CONFIG_CACHE_TIMEOUT = 3600

Template

Include the cookie consent snippet in your base template, typically in a block before </body>:

{% block cookie_optin %}
  {% include "cookie_optin/include.html" %}
{% endblock cookie_optin %}

Warning : If we have kapt_template > 6.0, this code is already integrated.

Overriding templates

Callbacks have been removed in favor of functions. If you have callback templates in your project (e.g. cookie_optin/callbacks/*.js), you can safely remove them.

Klaro JavaScript functions : callback, onInit, onAccept, onDecline

Klaro provides 4 JavaScript functions that can be overridden to add custom logic.

• callback: Called when a service is accepted or declined.
• onInit: Called when Klaro is initialized.
• onAccept: Called when a service is accepted.
• onDecline: Called when a service is declined.

Default function templates are provided for Google Analytics, Google Tag Manager, and YouTube in the cookie_optin/functions/ directory.

To create custom behavior for a given service, create a new function template in the cookie_optin/functions/ directory with the same name as the service in lowercase and without spaces.

Styling

The app ships default CSS. Customize colors via CSS variables by overriding the cookie_optin_styles block in your base template: set --cookie-optin-primary, --cookie-optin-slider, --cookie-optin-notice-image.

Configuration

Scripts loading

Modify <script> tags to let Klaro load them only when user give his consent:

  # Inline scripts
  <script
    type="opt-in"
    data-type="application/javascript"
    data-name="GoogleAnalytics"
  >
    //...
  </script>

  # External scripts and resources (img, link, ...)
  <script
    type="opt-in"
    data-src="https://analytics.7scientists.com/matomo.js"
    data-name="Matomo"
  ></script>

Django admin

All applications are initially inactive. You must go to the cookie_optin admin page to enable and create appropriate Applications, Purposes and Cookies.

Privacy policy page

The link to your privacy policy must be defined with the setting COOKIE_OPTIN_PRIVACY_URL.

Django CMS toolbar (optional)

When django-cms is installed, a "Statistic" button appears in the CMS toolbar. Clicking it opens a modal with an overview of consent metrics: accepts, declines, acceptance rate, and a time-series chart (monthly view).

Klaro Javascript API

To manually open the consent manager:

  klaro.show()

To manually set a consent:

  klaro.getManager().updateConsent(app.name, true)
  klaro.getManager().saveAndApplyConsents()

Update fixtures

Commands to update fixtures:

  run -website dumpdata cookie_optin --indent 4 -o ~/workspace/django-cookie-optin/cookie_optin/fixtures/cookie_optin.json