@reform-digital/cookie-flow 2.1.1 → 2.2.0

package/README.md

@@ -2,11 +2,13 @@
 
 ***
 
+<a href="https://www.reform.digital/tools/cookieflow" class="button primary" data-icon="webflow">Copy to Webflow</a> <a href="https://www.reform.digital/tools/cookieflow" class="button secondary" data-icon="figma">Copy to Figma</a> <a href="https://www.reform.digital/tools/cookieflow" class="button secondary" data-icon="bolt">Copy to Supabase</a>
+
 <figure><img src="https://3948747524-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyWDd0BQVjmRUYm47Xnrj%2Fuploads%2F3h17Hj5ZAxhUMFE6oHmg%2FThumb.png?alt=media&#x26;token=a7d697e2-d4cc-4310-a224-5f49fa4f3654" alt=""><figcaption></figcaption></figure>
 
 ***
 
-## Overview
+# Overview
 
 CookieFlow™ is a comprehensive cookie consent management solution developed by [Reform Digital®](https://reform.digital) specifically for Webflow websites. It provides a compliant, customizable framework for handling user consent preferences across different geographical regions, automatically adapting to privacy regulations like GDPR, CCPA, and others.
 
@@ -16,16 +18,16 @@ CookieFlow™ is a comprehensive cookie consent management solution developed by
 * **Manages cookie consent** across multiple categories (marketing, analytics, personalization)
 * **Complies with regional regulations** (GDPR, CCPA, etc.)
 * **Stores consent records** in your Supabase database for audit trails
-* **Integrates seamlessly** with Google Tag Manager and Webflow Analytics
+* **Integrates seamlessly** with Google Tag Manager and Webflow Analyze
 * **Respects privacy signals** like Do Not Track (DNT) and Global Privacy Control (GPC)
 
 ***
 
-### Features
+## Features
 
-#### 🔍 Automatic Geolocation
+### 🔍 Automatic Geolocation
 
-CookieFlow™ automatically detects your visitors' location using IP-based geolocation and displays the appropriate consent banner based on their region. If geolocation fails, it intelligently falls back to timezone-based detection.
+CookieFlow™ automatically detects your visitors' location using IP-based geolocation and displays the appropriate consent banner based on their region. If geolocation fails or returns invalid data, we default to ZONE_3 (GDPR/strictest) to stay compliant.
 
 **How It Works:**
 
@@ -41,22 +43,28 @@ CookieFlow™ automatically detects your visitors' location using IP-based geolo
 * Geolocation data is used only to determine compliance zone
 * No personally identifiable information is collected during detection
 
-#### 📍 Regional Compliance (3 Zones)
+**Cloudflare Worker response**
+
+* The worker returns JSON (`{ country, ip }`) so the client can parse it reliably.
+* IPs are masked in the worker itself (last octet zero) before the JSON payload is delivered.
+* `supabaseClient.js` still runs an additional anonymization pass as a safety net.
+
+### 📍 Regional Compliance (3 Zones)
 
 * **ZONE\_1 (Basic Notice)**: Simple notice-only approach for 130 countries with minimal compliance requirements
 * **ZONE\_2 (Opt-Out/CCPA)**: For 6 CCPA-affected regions (US, PR, GU, AS, MP, VI) with "Do Not Sell" option
 * **ZONE\_3 (Opt-In/GDPR)**: For 50 GDPR-affected regions (EU, UK, Canada, Brazil, Japan, etc.) with detailed consent options
 * **Customizable**: Override defaults with script attributes if privacy regulations change
 
-#### ⏰ Configurable Cookie Expiry
+### ⏰ Configurable Cookie Expiry
 
 Set how long consent cookies should last (default is 6 months). Users can be prompted to renew their consent when it expires.
 
-#### 📊 Consent Record Storage
+### 📊 Consent Record Storage
 
 GDPR and other privacy regulations require consent records to be stored and maintained for audit trails. CookieFlow™ is built to work seamlessly with Supabase due to its ease of setup and free tier availability. Once configured, all consent records are automatically stored in your Supabase database, providing a complete compliance audit trail without additional maintenance.
 
-#### 🔒 Privacy Signal Respect
+### 🔒 Privacy Signal Respect
 
 CookieFlow™ automatically respects and responds to:
 
@@ -64,21 +72,21 @@ CookieFlow™ automatically respects and responds to:
 * Global Privacy Control (GPC) signals
 * Automatically opts users out if these signals are detected
 
-#### 🤖 Bot Detection
+### 🤖 Bot Detection
 
 Crawlers and bots won't see consent banners, keeping your site's SEO intact.
 
-#### 🔄 Consent ID Tracking
+### 🔄 Consent ID Tracking
 
 Tracks and displays a unique consent ID to users (GDPR requirement for EU visitors).
 
-#### 🎨 Fully Customizable
+### 🎨 Fully Customizable
 
 Complete control over styling and layout using Webflow's native design tools.
 
 ***
 
-### Compliance
+## Compliance
 
 ✔ **Equal Prominence**: "Accept" and "Reject" buttons are identical in design.\
 ✔ **No Pre-Checked Boxes**: Users must actively opt in to non-essential cookies.\
@@ -99,35 +107,35 @@ Complete control over styling and layout using Webflow's native design tools.
 
 CookieFlow™ has been built with these regulations in mind, for full compliance implement it according to the documentation, do not change its functionality and only edit and style it considering the above rules.
 
-### Considerations
+## Considerations
 
 While CookieFlow™ provides comprehensive cookie consent management, there are several Webflow-specific features that require additional attention to ensure full GDPR compliance:
 
-#### Webflow E-Commerce is not GDPR compliant
+### Webflow E-Commerce is not GDPR compliant
 
 Webflow's native e-commerce solution is not fully GDPR compliant by default, as it uses cookies that may track users without explicit consent. Since these cookies are managed directly by Webflow, our cookie consent solution, CookieFlow, cannot control or block them. If you are using Webflow e-commerce, we recommend consulting a legal expert and exploring additional compliance measures to ensure your store meets GDPR requirements.
 
-#### Webflow's native video element for YouTube
+### Webflow's native video element for YouTube
 
 YouTube videos do not comply with GDPR regulations by default. To ensure users have control over their data, it's best to use embedded iFrames. If you add YouTube videos to your Webflow site using the native video element, personal data is automatically shared with YouTube and its parent company, Google, as soon as the page loads. To avoid this, consider using a custom code embed instead.
 
-#### Webflow's map is not GDPR compliant
+### Webflow's map is not GDPR compliant
 
 Webflow's native map element does not comply with GDPR regulations, as it automatically shares personal data with third parties like Google without user consent. To prioritize user privacy and provide better control over data sharing, it's advisable to use an embedded Google Map instead.
 
-#### Webflow's reCaptcha is not GDPR compliant
+### Webflow's reCaptcha is not GDPR compliant
 
 Webflow's built-in reCaptcha does not fully comply with GDPR, as it collects user data (such as IP addresses and behavior) without explicit consent. To maintain compliance and safeguard user privacy, it's best to integrate reCaptcha manually into your forms.
 
-#### Remove `<noscript>` tags for compliance
+### Remove `<noscript>` tags for compliance
 
 `<noscript>` tags are not compliant with cookie consent regulations and should be removed. These tags execute even when JavaScript is disabled, which can bypass cookie consent mechanisms and potentially collect user data without proper authorization. To ensure GDPR compliance, it is essential to eliminate all `<noscript>` tags from your website.
 
 ***
 
-### Support
+## Support
 
-#### Getting Help
+### Getting Help
 
 Need assistance with CookieFlow™? Try these steps:
 
@@ -137,7 +145,7 @@ Need assistance with CookieFlow™? Try these steps:
 4. **Validate Supabase credentials** - Confirm your Supabase URL and API key are correct and have proper permissions
 5. **Still stuck?** - Join our [Slack community](https://join.slack.com/t/rdcommunity/shared_invite/zt-2zser6sir-3CnFYB6gP4lvQsV2rY3wGw) for direct support from our team
 
-#### Feature Requests & Bugs
+### Feature Requests & Bugs
 
 CookieFlow™ is actively maintained and continuously improved. We welcome your feedback:
 
@@ -149,13 +157,15 @@ Join our [Slack community](https://join.slack.com/t/rdcommunity/shared_invite/zt
 
 ***
 
-## Recommended Setup
+# Recommended Setup
 
-### Quick Start
+## Quick Start
+
+We provide a ready-to-use Webflow component that includes all necessary elements, attributes, and scripts out of the box. Simply copy the component from our website and paste it into your Webflow project. You can also copy the original Figma design so you can style CookieFlow as needed.
 
-We provide a ready-to-use Webflow component that includes all necessary elements, attributes, and scripts out of the box. Simply copy the component from our demonstration website and paste it into your Webflow project.
+<a href="https://www.reform.digital/tools/cookieflow" class="button primary" data-icon="webflow">Copy to Webflow</a> <a href="https://www.reform.digital/tools/cookieflow" class="button secondary" data-icon="figma">Copy to Figma</a> 
 
-#### What's Included
+### What's Included
 
 The prebuilt component comes with:
 
@@ -166,7 +176,7 @@ The prebuilt component comes with:
 * **Manager button** for reopening the consent interface
 * **GDPR consent info banner**
 
-#### Important: Script Configuration
+### Important: Script Configuration
 
 The prebuilt component includes the CookieFlow™ script already. You just need to:
 
@@ -177,7 +187,7 @@ The prebuilt component includes the CookieFlow™ script already. You just need
 
 ***
 
-### Supabase Setup
+## Supabase Setup
 
 CookieFlow™ requires a Supabase database to store consent records for compliance and audit purposes. If you don't already have a Supabase account and database set up:
 
@@ -288,11 +298,11 @@ revoke all on function public.heartbeat() from public;
 
 ***
 
-### Script Configuration
+## Script Configuration
 
 The prebuilt component includes an embed element called "Component Scripts" with the required CookieFlow™ script already configured. To get started with the default configuration, simply update the script's attributes with your Supabase credentials (see [Supabase Setup](#-supabase-setup) above).
 
-#### Basic Configuration
+### Basic Configuration
 
 The script requires these two essential attributes to function:
 
@@ -304,7 +314,7 @@ The script requires these two essential attributes to function:
 ></script>
 ```
 
-#### Advanced Configuration (Optional)
+### Advanced Configuration (Optional)
 
 Beyond the basic setup, CookieFlow™ supports additional customizations to meet your specific compliance needs and preferences.
 
@@ -312,7 +322,7 @@ Beyond the basic setup, CookieFlow™ supports additional customizations to meet
 
 **Default Behavior**: By default, the consent cookie expires after **6 months**. This setting works well for most countries and aligns with common GDPR requirements.
 
-**How It Works**: CookieFlow™ stores a consent cookie called `cookieconsent_status` that remembers the user's choices. The expiration of this cookie is controlled by the `rd-consent-expiry` attribute in your script tag.
+**How It Works**: CookieFlow™ stores a consent cookie called `rd-cf-consent` that remembers the user's choices. The expiration of this cookie is controlled by the `rd-consent-expiry` attribute in your script tag.
 
 **Setting a Custom Expiration**: If you need to set a different expiration period based on your specific country's GDPR regulations, you can override the default by adding the `rd-consent-expiry` attribute to your script tag along with a value in **months**. For example, if your country states that consents should expire after 3 months instead of six, then you would update the attribute as follows:
 
@@ -391,12 +401,12 @@ CookieFlow™ automatically adapts to your visitors' location, showing the appro
 
 **Automatic Detection**
 
-CookieFlow™ uses a two-step detection process:
+CookieFlow™ uses IP-based geolocation via a Cloudflare Worker that leverages Cloudflare's built-in geolocation data. This approach is GDPR-compliant as no third-party services receive user IP addresses.
 
-1. **Primary**: IP-based geolocation (via ipapi.co)
-2. **Fallback**: Timezone-based detection if IP lookup fails
+1. **Primary**: IP-based geolocation (via Cloudflare Worker using `request.cf.country`)
+2. **Fallback**: Defaults to ZONE_3 (GDPR/strictest) if geolocation fails
 
-You don't need to configure anything for this to work—it's automatic.
+You can configure your Cloudflare Worker URL via the `rd-geo-worker-url` script attribute, or it will use the default worker URL.
 
 **Regional Configuration Override**
 
@@ -454,15 +464,22 @@ To customize country assignments, add these attributes to your script tag:
 
 * Comma-separated list of country codes (2-letter ISO format)
 * Used to override default regional assignments
+
+**`rd-geo-worker-url` (Optional)**
+
+* Your Cloudflare Worker URL for geolocation
+* Format: `https://your-worker.your-subdomain.workers.dev`
+* Default: Uses a default worker URL if not specified
+* The worker should return a 2-letter country code and accept the `x-cookieflow: 1` header
 * Format: `"US,CA,MX"`
 
 ***
 
-### Store Consents
+## Store Consents
 
 CookieFlow™ automatically stores comprehensive consent records in your Supabase database for compliance and audit purposes. Each time a user interacts with the consent banner, a detailed record is created that includes both technical metadata and the user's specific consent choices.
 
-#### What Information is Stored
+### What Information is Stored
 
 Every consent record contains the following information:
 
@@ -497,7 +514,7 @@ Every consent record contains the following information:
 * **`button_clicked`**: Text content of the specific button the user clicked
 * **`modal_text`**: The full text content of the consent banner/modal
 
-#### Consent Record Examples
+### Consent Record Examples
 
 **Example 1: Accept All (GDPR Region)**
 
@@ -565,7 +582,7 @@ Every consent record contains the following information:
 }
 ```
 
-#### Privacy & Security Features
+### Privacy & Security Features
 
 **IP Anonymization**
 
@@ -585,7 +602,7 @@ Every consent record contains the following information:
 * Anonymous users can only INSERT records (no SELECT/UPDATE/DELETE)
 * Consent retrieval requires specific function calls with proper permissions
 
-#### Compliance Benefits
+### Compliance Benefits
 
 **Audit Trail**
 
@@ -605,7 +622,7 @@ Every consent record contains the following information:
 * Geographic region tracking for multi-jurisdictional compliance
 * Detailed consent method tracking for audit purposes
 
-#### Accessing Consent Records
+### Accessing Consent Records
 
 **For Users (ZONE\_3/GDPR)**
 
@@ -641,29 +658,29 @@ SELECT * FROM get_consent_by_id('USER_CONSENT_ID');
 
 ***
 
-### Consent Categories
+## Consent Categories
 
 CookieFlow™ manages consent across four main categories:
 
-#### 1. Marketing Cookies
+### 1. Marketing Cookies
 
 **Purpose**: Used for advertising and tracking across websites\
 **Includes**: Social media pixels, retargeting pixels, advertising cookies\
 **Control**: Users can enable or disable this category
 
-#### 2. Analytics Cookies
+### 2. Analytics Cookies
 
 **Purpose**: Used to understand how visitors interact with your site\
-**Includes**: Google Analytics, Webflow Analytics, heatmap tools\
+**Includes**: Google Analytics, Webflow Analyze, heatmap tools\
 **Control**: Users can enable or disable this category
 
-#### 3. Personalization Cookies
+### 3. Personalization Cookies
 
 **Purpose**: Used to remember user preferences and personalize experience\
 **Includes**: Language preferences, theme preferences, saved settings\
 **Control**: Users can enable or disable this category
 
-#### 4. Essential Cookies (Always On)
+### 4. Essential Cookies (Always On)
 
 **Purpose**: Necessary for website functionality\
 **Includes**: Authentication, security, site functionality\
@@ -671,11 +688,11 @@ CookieFlow™ manages consent across four main categories:
 
 ***
 
-### Adding Project Scripts
+## Adding Project Scripts
 
 Once CookieFlow™ is set up, you need to configure your existing scripts to respect user consent preferences. CookieFlow™ provides two methods for script integration:
 
-#### Method 1: Adding Scripts Directly in Webflow
+### Method 1: Adding Scripts Directly in Webflow
 
 This method is ideal if you manage scripts directly within your Webflow project using embed elements or custom code.
 
@@ -700,15 +717,15 @@ This `<noscript>` tag loads tracking scripts even when JavaScript is disabled, c
 
 **Essential Scripts**
 
-**Attribute**: `rd-cookieflow="essential"`\
+**Attribute**: `type="disabled" rd-cookieflow="essential"`\
 **Use for**: Authentication, security, payment processing, accessibility scripts, form validation, load balancing, privacy & consent management
 
 ```html
 <!-- Stripe JS Library -->
-<script rd-cookieflow="essential" src="https://js.stripe.com/v3/"></script>
+<script type="disabled" rd-cookieflow="essential" src="https://js.stripe.com/v3/"></script>
 
 <!-- Authentication Script -->
-<script rd-cookieflow="essential">
+<script type="disabled" rd-cookieflow="essential">
   // Your authentication code here
 </script>
 ```
@@ -802,7 +819,7 @@ fbq('track', 'PageView');
 
 ***
 
-#### Method 2: Adding Scripts via Google Tag Manager
+### Method 2: Adding Scripts via Google Tag Manager
 
 This method is recommended if you use Google Tag Manager to manage your website scripts and tracking.
 
@@ -905,13 +922,13 @@ For each tag, go to **Tag Configuration → Advanced Settings → Consent Settin
 
 ***
 
-## Manual Setup
+# Manual Setup
 
-### Setup Guide
+## Setup Guide
 
 If you prefer to build your own UI or need to customize the implementation beyond the prebuilt component, you can manually set up CookieFlow™ by adding the required HTML elements and attributes to your Webflow project.
 
-#### Quick Start
+### Quick Start
 
 1. Add the CookieFlow™ script to your Webflow project
 2. Create the required HTML elements in your Webflow project
@@ -920,7 +937,7 @@ If you prefer to build your own UI or need to customize the implementation beyon
 
 ***
 
-### Adding the Script
+## Adding the Script
 
 Add the following script to your Webflow project's **global settings**, inside the `<head>` tag:
 
@@ -932,7 +949,7 @@ Add the following script to your Webflow project's **global settings**, inside t
 ></script>
 ```
 
-#### What's Next?
+### What's Next?
 
 * **Configure your Supabase database**: Follow the [Supabase Setup](#-supabase-setup) guide in Option 1
 * **Learn about script attributes**: See the [Script Configuration](#-script-configuration) section for all available attributes and customization options
@@ -940,11 +957,11 @@ Add the following script to your Webflow project's **global settings**, inside t
 
 ***
 
-### Elements & Attributes
+## Elements & Attributes
 
 CookieFlow™ uses **HTML data attributes** to identify and control UI elements. These attributes start with `rd-cookieflow` (Reform Digital CookieFlow).
 
-#### Core Components
+### Core Components
 
 **1. Wrapper Element**
 
@@ -1014,7 +1031,7 @@ There are **three banner types**, one for each compliance zone:
 **Attribute**: `rd-cookieflow="consent-banner"`\
 **Additional**: Add `rd-cookieflow="consent-interaction"` to control show/hide state
 
-#### Essential UI Elements Within Components
+### Essential UI Elements Within Components
 
 **Consent Buttons**
 
@@ -1053,7 +1070,7 @@ To prevent page scrolling when the settings modal is open, add this attribute to
 </div>
 ```
 
-#### Example Structure
+### Example Structure
 
 Here's an example of a complete CookieFlow™ structure:
 
@@ -1130,3 +1147,24 @@ Here's an example of a complete CookieFlow™ structure:
 ```
 
 ***
+
+# Product Tracking
+
+CookieFlow™ includes an extremely lightweight telemetry module that helps us understand product adoption patterns. This information allows us to focus our support efforts and prioritize product enhancements where they matter most.
+
+**What We Track:**
+
+* **Product Identifier**: The name of the product (e.g., "COOKIE\_FLOW")
+* **Domain**: The public hostname where the product is installed (e.g., "example.com")
+
+**Privacy & Performance:**
+
+* No cookies, fingerprinting, or personally identifiable information
+* Only runs on live, public domains (never on localhost or development environments)
+* Single lightweight request sent once per page load
+* Data is aggregated for internal analytics only
+* Not used for advertising, marketing, or tracking
+
+This anonymous usage data helps us ensure CookieFlow™ evolves to meet real-world needs.
+
+***

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reform-digital/cookie-flow",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "CookieFlow™ is a comprehensive cookie consent management solution developed by Reform Digital® specifically for Webflow websites. It provides a compliant, customizable framework for handling user consent preferences across different geographical regions, automatically adapting to privacy regulations like GDPR, CCPA, and others.",
   "author": "Reform Digital®",
   "keywords": [],