Appearance

Migration Guide: V1 to V2 ​

This guide covers migrating from Consent Pro V1 to V2, including breaking changes, new features, and updated patterns.

Overview ​

Why Upgrade? ​

V2 Benefits:

  • Multi-Region Support: Target different regions with different banners
  • Reactive State: Predictable, efficient state updates
  • Enhanced Blocking: Smarter script/iframe blocking with provider matching
  • Better Analytics: Google Consent Mode V2, comprehensive tracking
  • Improved API: More intuitive, fully typed, better organized

Migration Complexity ​

Consent Pro Webflow app will handle the migration for you automatically.

Breaking Changes ​

Script Loading ​

V1:

html
<script src="{script-url}" type="module" async></script>

V2:

html
<script src="{script-url}" type="text/javascript" async></script>
<!-- OR (default NON-ASYNC - recommended for compliance) -->
<script src="{script-url}" type="text/javascript"></script>

What Changed? ​

V2 moves from ES modules (type="module") to standard JavaScript (type="text/javascript") and gives you control over async loading. By default, the script loads synchronously (blocking), but you can enable async loading in the Configurator under Script Settings.

Key Changes:

  • Module Type: type="module" → type="text/javascript"
  • Loading Control: Fixed async behavior → Configurable async/sync loading
  • Default Behavior: Synchronous loading (blocking) for immediate consent enforcement
  • Performance Option: Async loading available for better Core Web Vitals

Why This Matters for Performance ​

Non-Async (Default - Recommended for Compliance):

  • GDPR/Legal Compliance: Blocks third-party scripts before user consent
  • Immediate Banner Display: Cookie banner appears instantly on page load
  • Predictable Behavior: Script executes in document order
  • No Flash of Unstyled Content: Banner styling loads before page renders
  • Prevents Race Conditions: Third-party scripts can't initialize before blocking
  • Render-Blocking: Script blocks HTML parsing
  • Delays Page Interactivity: May impact Time to Interactive metric

Async Loading (Optional - Better for Performance):

  • Faster Initial Page Load: Script doesn't block HTML parsing
  • Better Core Web Vitals: Improves First Contentful Paint and Largest Contentful Paint
  • Improved Time to Interactive: Page becomes interactive sooner
  • Non-Blocking: HTML parsing continues while script loads
  • Delayed Banner Display: Banner may appear after page content loads
  • Compliance Risk: Brief window where unconsented scripts might execute
  • Race Conditions: Third-party scripts may initialize before consent blocking is active

Lighthouse Impact ​

Non-Async (Default):

  • Lower Performance Score: Render-blocking resource penalty
  • Slower First Contentful Paint: Script execution delays initial render
  • Reduced Time to Interactive: Synchronous execution blocks main thread
  • Better Compliance: No unconsented script execution window
  • Best for: Sites prioritizing legal compliance over performance metrics

Async:

  • Higher Performance Score: No render-blocking penalty
  • Faster First Contentful Paint: HTML parsing isn't blocked
  • Better Time to Interactive: Page becomes interactive while script loads
  • Improved Core Web Vitals: Better LCP, FID, and CLS scores
  • Compliance Trade-off: Higher risk window for unconsented tracking
  • Best for: Performance-critical sites with less strict compliance requirements

How to Configure ​

You can toggle async loading in the Consent Pro app:

  1. Open your Cookie Banner inside the Configurator
  2. Scroll to Script Settings
  3. Toggle Load Script Asynchronously
  4. Save and republish your site

Next Steps ​

Support ​

Need help migrating?

Include your V1 configuration when requesting support.