# UNDRR Cookie Banner Configuration v1

This folder contains the UNDRR Cookie Banner configuration using [vanilla-cookieconsent](https://github.com/orestbida/cookieconsent).

## Overview

Provides GDPR-compliant consent management for UNDRR websites.

## Files

- `config.json` - The main configuration file containing all cookie banner settings
- `cookieconsent.css` - Local copy of the vanilla-cookieconsent CSS stylesheet
- `cookieconsent.umd.js` - Local copy of the vanilla-cookieconsent JavaScript library
- `example.html` - Example implementation showing how to use the cookie banner
- `README.md` - This documentation file

### Hosted URLs

When deployed, these assets are available at:

- **Cookie Banner Config**: `https://assets.undrr.org/cookie-banner/v1/config.json`
- **Cookie Banner CSS**: `https://assets.undrr.org/cookie-banner/v1/cookieconsent.css`
- **Cookie Banner JS**: `https://assets.undrr.org/cookie-banner/v1/cookieconsent.umd.js`
- **Cookie Banner Example**: `https://assets.undrr.org/cookie-banner/v1/example.html`

## Configuration Structure

The configuration has three sections:

### 1. GUI Options (`guiOptions`)

Controls banner layout:

- **Consent Modal**: Bottom bar layout with equal weight buttons
- **Preferences Modal**: Left-positioned box layout for detailed cookie preferences

### 2. Categories (`categories`)

Defines cookie categories and defaults:

- **Necessary**: Always enabled, read-only (required for website functionality)
- **Analytics**: Optional category for tracking cookies with auto-clear functionality

### 3. Language (`language`)

Manages translations and text:

- Default language: English (`en`)
- Auto-detection: Browser language
- Complete translations for consent and preferences modals

## Usage

### Basic Implementation

```javascript
// Load the configuration
fetch('/path/to/cookie-banner/v1/config.json')
  .then(response => response.json())
  .then(config => {
    // Initialize CookieConsent with the loaded config
    if (typeof window.CookieConsent !== 'undefined') {
      window.CookieConsent.run(config);
    } else {
      console.error('CookieConsent not loaded');
    }
  });
```

### Drupal Integration

For Drupal sites, integrate with existing behavior:

```javascript
Drupal.behaviors.undrrCookieBanner = {
  attach: function (context, settings) {
    once('undrrCookieBanner', 'body', context).forEach(function (body) {
      // Load configuration from JSON file
      fetch('/sites/default/files/cookie-banner/v1/config.json')
        .then(response => response.json())
        .then(config => {
          // Merge with dynamic settings if needed
          config.language.default = settings.path.currentLanguage || 'en';

          // Initialize banner
          window.CookieConsent.run(config);
        });
    });
  }
};
```

### Customization

#### Adding New Languages

To add support for additional languages, extend the `translations` object:

```json
{
  "language": {
    "translations": {
      "en": { /* existing English translations */ },
      "fr": {
        "consentModal": {
          "title": "UNDRR utilise des cookies...",
          "description": "En continuant à utiliser notre site..."
        }
      }
    }
  }
}
```

#### Adding New Cookie Categories

To add new cookie categories (e.g., marketing, functionality):

```json
{
  "categories": {
    "necessary": { /* existing */ },
    "analytics": { /* existing */ },
    "marketing": {
      "enabled": false,
      "readOnly": false,
      "autoClear": {
        "cookies": [
          { "name": "/^_fb/" },
          { "name": "_gcl_au" }
        ]
      }
    }
  }
}
```

#### Customizing Appearance

Modify the `guiOptions` section to change the banner appearance:

```json
{
  "guiOptions": {
    "consentModal": {
      "layout": "cloud",        // Options: bar, box, cloud
      "position": "top",        // Options: top, bottom
      "equalWeightButtons": false,
      "flipButtons": true
    }
  }
}
```

## Dependencies

This configuration requires **vanilla-cookieconsent** `3.1.0`. Load it via:

### 1. Local Files (Recommended for Development)

Use included files for offline development/testing:

```html
<!-- Local implementation using included files -->
<link rel="stylesheet" href="./cookieconsent.css">
<script src="./cookieconsent.umd.js"></script>
```

### 2. UNDRR asset library (Production)

For production, use the version hosted in the UNDRR asset library:

```html
<!-- UNDRR asset library -->
<link rel="stylesheet" href="https://assets.undrr.org/cookie-banner/v1/cookieconsent.css">
<script src="https://assets.undrr.org/cookie-banner/v1/cookieconsent.umd.js"></script>
```

### 3. External CDN (Fallback)

You can also use the original third-party CDN:

```html
<!-- External CDN fallback -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orestbida/cookieconsent@3.1.0/dist/cookieconsent.css">
<script src="https://cdn.jsdelivr.net/gh/orestbida/cookieconsent@3.1.0/dist/cookieconsent.umd.js"></script>
```

### 4. NPM Implementation

```bash
npm install vanilla-cookieconsent@3.1.0
```

**Browser Support**: Modern browsers with ES6+ support are required.

## Features

- **GDPR Compliant**: Provides proper consent management
- **Customizable**: Easy to modify text, styling, and behavior
- **Multi-language Support**: Ready for internationalization
- **Auto-clear Cookies**: Automatically removes cookies when consent is withdrawn
- **Accessibility**: Built-in ARIA labels and keyboard navigation
- **Responsive**: Works on all device sizes

## Best Practices

1. **Test Thoroughly**: Always test cookie consent flows on your target browsers
2. **Privacy Policy Links**: Ensure all privacy policy links are working and up-to-date
3. **Cookie Auditing**: Regularly audit what cookies your site actually uses
4. **Performance**: Load the cookie banner early but asynchronously
5. **Compliance**: Review local privacy laws and regulations

## Troubleshooting

### Common Issues

1. **Banner not showing**: Check if CookieConsent library is loaded
2. **Styling issues**: Verify CSS conflicts with your site's styles
3. **Translation missing**: Ensure all required translation keys are present
4. **Cookies not clearing**: Check autoClear configuration and cookie names

### Debug Mode

For debugging, you can enable console logging:

```javascript
// Add to your implementation
window.CC_DEBUG = true;
```

## Support

For support:
- **Configuration**: check this documentation and examples
- **Library bugs**: report to [vanilla-cookieconsent GitHub](https://github.com/orestbida/cookieconsent)
- **UNDRR-specific issues**: contact the web development team

## Version History

- **v1.0.0**: Initial configuration extraction from Drupal implementation
  - Basic consent modal and preferences modal
  - English translations
  - Necessary and Analytics categories
  - Auto-clear functionality for analytics cookies