@whotechs/react-gdpr-cookie-banner/README.md

A modern, customizable GDPR & Google Consent Mode v2 compliant cookie consent banner

# React GDPR Cookie Banner

A modern, customizable, and GDPR-compliant cookie consent banner for React applications. Fully compatible with Google Consent Mode v2.

## Features

- 🎨 Fully customizable UI
- 📱 Responsive design
- ✅ GDPR compliant
- 🔄 Google Consent Mode v2 integration
- 🌐 TypeScript support
- 💾 Persistent preferences
- 🎯 Google Tag Manager support
- ♿ Accessibility features

## Installation

```bash
# Using npm
npm install @whotechs/react-gdpr-cookie-banner

# Using yarn
yarn add @whotechs/react-gdpr-cookie-banner

# Using pnpm
pnpm add @whotechs/react-gdpr-cookie-banner
```

Make sure you have the peer dependencies installed:
```bash
npm install styled-components
```

## Quick Start

1. Add your Google Tag Manager ID to your environment variables:
```env
VITE_GTM_ID="GTM-XXXXXX"  # For Vite
# or
REACT_APP_GTM_ID="GTM-XXXXXX"  # For Create React App
```

2. Import and use the component:
```jsx
import { CookieBanner } from '@whotechs/react-gdpr-cookie-banner';

function App() {
  return (
    <div>
      <CookieBanner 
        gtmContainerId={import.meta.env.VITE_GTM_ID || ''}  // For Vite
        // or
        // gtmContainerId={process.env.REACT_APP_GTM_ID || ''}  // For Create React App
        primaryColor="#007bff"
        onPreferencesUpdate={(preferences) => {
          console.log('Cookie preferences updated:', preferences);
        }}
      />
      {/* Your other components */}
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| primaryColor | string | '#FFD700' | Primary color used for buttons and switches |
| textColor | string | '#FFFFFF' | Text color for the banner |
| backgroundColor | string | 'rgba(0, 0, 0, 0.95)' | Background color for the banner |
| className | string | '' | Custom CSS class for the banner container |
| onPreferencesUpdate | function | () => {} | Callback function when preferences are updated |
| titleText | string | 'Privacy Preferences Center' | Custom text for the title |
| descriptionText | string | '...' | Custom text for the description |
| showDelay | number | 1000 | Wait time in milliseconds before showing the banner |
| gtmContainerId | string | '' | Google Tag Manager container ID |

## Cookie Preferences

The banner manages the following cookie categories:

- Essential (Always enabled)
- Analytics
- Advertising
- Ad Personalization
- User Data Processing

## Google Consent Mode v2 Integration

This banner automatically integrates with Google Consent Mode v2, managing the following consent types:

- ad_storage
- analytics_storage
- ad_user_data
- ad_personalization

## Example with Custom Styling

```jsx
import { CookieBanner } from '@whotechs/react-gdpr-cookie-banner';

function App() {
  return (
    <CookieBanner
      gtmContainerId="GTM-XXXXXX"
      primaryColor="#4CAF50"
      textColor="#FFFFFF"
      backgroundColor="rgba(33, 33, 33, 0.98)"
      titleText="Cookie Settings"
      descriptionText="We use cookies to enhance your experience."
      onPreferencesUpdate={(prefs) => {
        console.log('Updated preferences:', prefs);
      }}
    />
  );
}
```

## TypeScript Support

The package includes built-in TypeScript declarations. You can import types like this:

```typescript
import { CookieBanner, CookieBannerProps, CookiePreferences } from '@whotechs/react-gdpr-cookie-banner';
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- IE 11 (with appropriate polyfills)

## Post-Installation Setup

1. **Google Tag Manager Setup:**
   ```html
   <!-- Add this in your index.html head section -->
   <script>
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
   </script>
   ```

2. **Environment Variables:**
   Create a `.env` file in your project root:
   ```env
   # For Vite
   VITE_GTM_ID=GTM-XXXXXX

   # For Create React App
   REACT_APP_GTM_ID=GTM-XXXXXX
   ```

3. **Add to Your Root Component:**
   ```jsx
   // App.jsx or App.tsx
   import { CookieBanner } from '@whotechs/react-gdpr-cookie-banner';

   function App() {
     const handlePreferencesUpdate = (preferences) => {
       // Optional: Handle preference updates
       console.log('Cookie preferences updated:', preferences);
       
       // Example: Trigger analytics based on preferences
       if (preferences.analytics_storage) {
         // Initialize analytics
       }
       
       // Example: Handle advertising preferences
       if (preferences.ad_storage) {
         // Initialize ad services
       }
     };

     return (
       <>
         <CookieBanner 
           gtmContainerId={import.meta.env.VITE_GTM_ID || ''}
           primaryColor="#007bff"
           onPreferencesUpdate={handlePreferencesUpdate}
         />
         {/* Your app content */}
       </>
     );
   }
   ```

4. **Styled Components Setup:**
   If you're using TypeScript, add styled-components types:
   ```bash
   npm install @types/styled-components
   ```

5. **TypeScript Configuration (if using TypeScript):**
   Make sure your `tsconfig.json` includes:
   ```json
   {
     "compilerOptions": {
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true
     }
   }
   ```

6. **Testing Cookie Banner:**
   - Clear your browser's cookies and localStorage
   - Refresh your page
   - The banner should appear on first visit
   - Test all preference toggles
   - Verify GTM integration using Google Tag Assistant

7. **Optional: Custom Styling**
   ```jsx
   // Example with theme integration
   import { ThemeProvider } from 'styled-components';

   const theme = {
     cookieBanner: {
       primary: '#007bff',
       text: '#FFFFFF',
       background: 'rgba(0, 0, 0, 0.95)'
     }
   };

   function App() {
     return (
       <ThemeProvider theme={theme}>
         <CookieBanner 
           gtmContainerId={import.meta.env.VITE_GTM_ID || ''}
           primaryColor={theme.cookieBanner.primary}
           textColor={theme.cookieBanner.text}
           backgroundColor={theme.cookieBanner.background}
         />
         {/* Your app content */}
       </ThemeProvider>
     );
   }
   ```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © [whotechs]