Metadata-Version: 2.4
Name: django-cookie-optin
Version: 4.1.0
Summary: A django application to manage opt-in cookie consent
License: BSD-3-Clause
License-File: LICENSE
Author: Kapt dev team
Author-email: dev@kapt.mobi
Requires-Python: >=3.10,<4
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: Django (>=1.11)
Requires-Dist: django-parler
Project-URL: Repository, https://gitlab.com/kapt/modules/django-cookie-optin
Description-Content-Type: text/markdown

# 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](https://klaro.kiprotect.com/) 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](https://github.com/kiprotect/klaro/blob/master/dist/klaro.js)).

## Project setup

### URLs

Add to your root `urls.py`:

```python
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

```python
# 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>`:

```html
{% 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:

```html
  # 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:
```js
  klaro.show()
```

To manually set a consent:
```js
  klaro.getManager().updateConsent(app.name, true)
  klaro.getManager().saveAndApplyConsents()
```

## Update fixtures

Commands to update fixtures:
```sh
  run -website dumpdata cookie_optin --indent 4 -o ~/workspace/django-cookie-optin/cookie_optin/fixtures/cookie_optin.json
```


