consently 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e94002d1ea10654641d354b24f94f18c97a106e71cf737a9fede52de32b6141
-  data.tar.gz: 5dd2300f3e1b7e8f7c696dd8dc86d5cdd098c7889e6a070f00b379b2f546b105
+  metadata.gz: b563d7b5602bb17c10a2ac0ee0b04c6c59642df56920a36e292d808bfef5c89b
+  data.tar.gz: 0ae29edf9f32feb8fc79cbb7e2717e0a68fee7bef0dafdb38b9e4e5f1523b754
 SHA512:
-  metadata.gz: 5d47ad72af0dd8538c124c383ebe809605675a05f68ab496a97e88a1f089d9eca4e1e1f779617ffb3361c4d5a0bc7a9eb8dc2ba1b13799b67aeb3e32a6b0856d
-  data.tar.gz: c56ac8259f0b480dd6d7c34c0649ca2ac02b365cb3e32d894600d8692918bd21d4c76f32cfc537e30481ebe8c16bf65890ceebc1fa7983e0673d4c0184e632df
+  metadata.gz: e71581b2492efb315e7679f1a5d534dd45d8771fe6b552d75b946e763678bad95fccf4bffaa9f03371500ffafbb237a520d5e0c7e4552a616ba18b320fbf6b8a
+  data.tar.gz: a108dbed5dd145646f649807a953693963d6da9c4eb2ec64eca666301b5dd6e569a1699d71c4000dc879348242dbe547eb17da87558b9bd6deea2e34461ebaca

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0 (2026-08-13)
+
+- `consently_embed` for videos and maps: a YouTube or Vimeo iframe, or a
+  Google map, waits behind a placeholder until its category is granted and
+  then appears without a reload.
+- `consently_ecommerce` builds GA4 ecommerce events from your own line items
+  or products, clearing the previous `ecommerce` object the way Google asks.
+- `google_consent_mode` now takes `:basic` (the previous behaviour) or
+  `:advanced`, which lets Google's own tags load denied so Ads can model the
+  conversions of visitors who refused.
+- `cookie_domain`, so one consent covers every subdomain.
+- `consent_max_age`, to ask again after a year without bumping the policy
+  version.
+
 ## 0.1.0 (2026-08-12)
 
 First release.

data/README.md

@@ -1,5 +1,10 @@
 # Consently
 
+[![Gem](https://img.shields.io/gem/v/consently?color=%23e9573f)](https://rubygems.org/gems/consently)
+[![Downloads](https://img.shields.io/gem/dt/consently)](https://rubygems.org/gems/consently)
+[![CI](https://github.com/Xeross99/consently/actions/workflows/ci.yml/badge.svg)](https://github.com/Xeross99/consently/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/licence-MIT-blue)](MIT-LICENSE)
+
 **GDPR cookie consent for Rails that actually blocks your tags.**
 
 Most banners ask for consent and load Google Analytics anyway. Consently is
@@ -12,12 +17,24 @@ pageview.
 | --- | --- |
 | **Blocks** | GA4, Google Tag Manager, Google Ads, Microsoft Clarity, Meta Pixel, Hotjar, Plausible, anything custom |
 | **Google Consent Mode v2** | denied by default before any Google tag, updated on the click |
-| **Banner** | plain CSS, no Tailwind, no build step, one Stimulus controller, ten languages |
+| **Banner** | plain CSS, no Tailwind, no build step, ten languages |
+| **Embeds** | YouTube, Vimeo and Google Maps iframes wait behind a placeholder too |
+| **Ecommerce** | GA4 `purchase`, `add_to_cart` and friends, built from your own line items |
 | **Cookie policy** | generated from the same config - every vendor, every cookie, every duration |
 | **Multi-tenant** | different tags per domain or shop from one initializer |
 | **Proof of consent** | optional log in your own database; no third-party service, nothing leaves your servers |
 | **Install** | one initializer, three helpers in your layout |
 
+Before the click, and right after it - same page, no reload in between:
+
+| Blocked | Running |
+| --- | --- |
+| ![The banner, with every optional tag blocked](docs/banner.png) | ![The same page a click later, every tag running](docs/running.png) |
+
+The preferences panel, one category at a time:
+
+![The preferences panel with a checkbox per category](docs/preferences.png)
+
 ```ruby
 # config/initializers/consently.rb
 Consently.configure do |c|
@@ -52,10 +69,12 @@ bundle install
 rails g consently:install
 ```
 
-The generator writes the initializer and registers the Stimulus controller in
-`app/javascript/controllers/index.js`. Nothing else to set up: the banner
-brings its own plain CSS, so there is no Tailwind, no build step and no
-config file to keep in sync.
+On RubyGems: <https://rubygems.org/gems/consently>
+
+The generator writes the initializer and registers the two Stimulus controllers
+in `app/javascript/controllers/index.js`. Nothing else to set up: the banner
+brings its own plain CSS, so there is no Tailwind, no build step and no config
+file to keep in sync.
 
 ## What is a tag
 
@@ -91,7 +110,19 @@ c.category :personalization
 visitor agrees, and the choice is kept in a `consently` cookie for six months.
 
 Change your policy? Bump `c.consent_version` and every older consent stops
-counting; the banner asks again.
+counting; the banner asks again. To ask again on a schedule as well - the
+guidance across the EU converges on about a year - set an age:
+
+```ruby
+c.consent_max_age = 12.months
+```
+
+Spanning subdomains? Say so, or a consent given on `www` will not count on
+`shop`:
+
+```ruby
+c.cookie_domain = ".example.com"
+```
 
 ## Per-domain, per-tenant
 
@@ -100,12 +131,12 @@ One initializer, different tags per host or shop:
 ```ruby
 c.scope_resolver = -> (request) { request.host }
 
-c.scope "trixbrix.eu" do |s|
-  s.tag :google_analytics, id: "G-TRIX"
+c.scope "shop.example.com" do |s|
+  s.tag :google_analytics, id: "G-SHOP00001"
 end
 
-c.scope "pixelpicture.eu" do |s|
-  s.tag :google_analytics, id: "G-PIXEL"
+c.scope "blog.example.com" do |s|
+  s.tag :google_analytics, id: "G-BLOG00001"
 end
 ```
 
@@ -113,6 +144,22 @@ Scopes inherit the tags declared outside them and override by declaring the
 same provider again. The resolver can return anything - `Current.shop&.name`
 works just as well as a host.
 
+## The cookie policy writes itself
+
+```erb
+<h1>Cookie policy</h1>
+<p>Your own legal text.</p>
+
+<%= consently_policy %>
+```
+
+Every category, the vendors in it, the cookies each one sets and how long they
+last - rendered from the configuration your tags come from, so it cannot drift
+out of date. Add a tag to the initializer and it appears here, in the right
+category, with its cookies.
+
+![The generated cookie policy: categories, vendors, cookies and durations](docs/policy.png)
+
 ## Proof of consent
 
 ```bash
@@ -187,13 +234,88 @@ button carries `aria-expanded` and `aria-controls`, reopening the panel moves
 focus into it, and the animation gives way to `prefers-reduced-motion`. Nobody
 is trapped in a focus cycle they did not ask for.
 
-## Events
+## Ecommerce events
+
+GA4 wants a particular shape, and your models are not it. Hand the helper
+whatever you have:
+
+```erb
+<%= consently_ecommerce "purchase", items: @order.line_items,
+      value: @order.total, currency: "EUR", transaction_id: @order.number %>
+```
+
+Items may be hashes already in GA4 shape, or any object answering to
+`sku`/`id`, `name`, `price`, `quantity`, `category`, `brand`, `variant` - a
+line item or a product usually does. The previous `ecommerce` object is
+cleared first, as Google asks, so two events on one page cannot bleed into
+each other.
+
+Anything else:
 
 ```erb
-<%= consently_data_layer_push("purchase", value: 120, currency: "EUR") %>
+<%= consently_data_layer_push "newsletter_signup", source: "footer" %>
 ```
 
-Renders nothing when analytics consent is missing.
+Both render nothing at all when analytics consent is missing.
+
+## Embedded videos and maps
+
+Blocking scripts is half the job: a YouTube iframe sets cookies on its own.
+
+```erb
+<%= consently_embed :youtube, "dQw4w9WgXcQ" %>
+<%= consently_embed :vimeo, "76979871", category: :analytics %>
+<%= consently_embed :google_maps, "Bahnhofstrasse 12, Berlin" %>
+<%= consently_embed :custom, "https://example.com/widget", title: "Widget", ratio: "4 / 3" %>
+```
+
+Until the category is granted the visitor gets a placeholder the same size as
+the embed - so nothing jumps - with a button that opens the preferences panel.
+The iframe appears the moment they agree, without a reload.
+
+| Waiting for consent | After the click |
+| --- | --- |
+| ![A placeholder where the video will be](docs/embed-blocked.png) | ![The same box, now playing the video](docs/embed-released.png) |
+
+What the page holds until then is only the address:
+
+```html
+<div class="consently-embed"
+     data-controller="consently-embed"
+     data-consently-embed-category-value="marketing"
+     data-consently-embed-src-value="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ">
+```
+
+No iframe, no request to YouTube, no cookie - and `youtube-nocookie.com` is
+what gets embedded once there is consent. `ratio:` sets the box (`16 / 9` by
+default), `category:` decides which consent releases it, and any other option
+is passed straight to the iframe:
+
+```erb
+<%= consently_embed :youtube, "dQw4w9WgXcQ", ratio: "21 / 9", allow: "autoplay; picture-in-picture" %>
+```
+
+Your own markup can do the same thing without the helper: anything carrying
+`data-consently-open` opens the preferences panel, and the `consently:change`
+event tells you what was granted.
+
+## Google consent mode: basic or advanced
+
+```ruby
+c.google_consent_mode = :basic    # default
+c.google_consent_mode = :advanced
+```
+
+**Basic** keeps Google's tags off the page until consent: nothing about the
+visitor reaches Google before they agree.
+
+**Advanced** loads them right away with everything denied, so they send
+cookieless pings and Google Ads can model the conversions of visitors who said
+no. More data for you, a request to Google either way. Which one is defensible
+is a legal call, not a technical one - the gem simply does what you set.
+
+Either way the defaults are emitted before any Google tag and updated the
+moment the visitor chooses.
 
 ## Styling
 
@@ -251,7 +373,9 @@ Helpers:
 | `consently_banner` | the banner, the panel, and the JavaScript that releases blocked tags |
 | `consently_policy` | the generated cookie policy: categories, vendors, cookies, durations |
 | `consently_preferences_link` | "Cookie settings" link; anything with `data-consently-open` reopens the panel |
-| `consently_data_layer_push(event, **payload)` | a dataLayer event, rendered only with analytics consent |
+| `consently_ecommerce(event, items:, **params)` | a GA4 ecommerce event, items mapped from your own objects |
+| `consently_data_layer_push(event, **payload)` | any other dataLayer event, rendered only with analytics consent |
+| `consently_embed(kind, id, category:, ratio:)` | a video or map that waits for consent |
 | `consently_consent` | the current `Consently::Consent`; `granted?(:analytics)` in your own views |
 
 Configuration:
@@ -264,10 +388,11 @@ Configuration:
 | `c.consent_version` | bump it and every older consent stops counting |
 | `c.enabled` | `true`, `false`, or a callable taking the request |
 | `c.reload_after_choice` | reload once a choice is made; off by default |
-| `c.google_consent_mode` | consent mode v2 defaults and updates; on by default |
+| `c.google_consent_mode` | `:basic` (default), `:advanced`, or `false` |
 | `c.log_consents`, `c.consent_subject` | store proof of each decision, optionally naming who |
 | `c.stylesheet` | link the banner's CSS; off if you style it yourself |
-| `c.cookie_name`, `c.cookie_max_age`, `c.cookie_path` | where the choice is kept |
+| `c.cookie_name`, `c.cookie_max_age`, `c.cookie_path`, `c.cookie_domain` | where the choice is kept |
+| `c.consent_max_age` | ask again after this long, whatever the cookie says |
 | `c.respect_do_not_track`, `c.respect_global_privacy_control` | treat an opt-out signal as a rejection |
 | `c.consent_required` | who has to be asked at all; false means no banner and everything granted |
 

data/app/assets/stylesheets/consently.css

@@ -146,6 +146,44 @@
   display: none !important;
 }
 
+/* Embedded videos and maps. The placeholder keeps the same box as the iframe
+   it replaces, so nothing on the page jumps when consent arrives. */
+.consently-embed {
+  position: relative;
+  aspect-ratio: var(--consently-embed-ratio, 16 / 9);
+  width: 100%;
+  border-radius: 0.5rem;
+  overflow: hidden;
+  background: #f3f4f6;
+}
+
+.consently-embed__frame {
+  width: 100%;
+  height: 100%;
+  border: 0;
+  display: block;
+}
+
+.consently-embed__placeholder {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  padding: 1.5rem;
+  text-align: center;
+}
+
+.consently-embed__text {
+  margin: 0;
+  max-width: 28rem;
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+  color: #4b5563;
+}
+
 /* The generated cookie policy. Deliberately quiet: it lands inside someone
    else's page and should inherit its typography. */
 .consently-policy {

data/app/helpers/consently/tags_helper.rb

@@ -13,8 +13,7 @@ module Consently
       parts << consently_stylesheet_tag if Consently.config.stylesheet
       parts << consently_consent_mode_tag if Consently.config.google_consent_mode
       Consently.tags_for(request).each do |provider|
-        granted = consently_consent.granted?(provider.category)
-        provider.scripts.each { |script| parts << consently_script_tag(script, provider, granted) }
+        provider.scripts.each { |script| parts << consently_script_tag(script, provider, consently_release?(provider)) }
       end
 
       safe_join(parts, "\n")
@@ -65,7 +64,11 @@ module Consently
 
     def consently_consent
       @consently_consent ||= if Consently.consent_required?(request)
-        Consent.from_cookie(cookies[Consently.config.cookie_name], version: Consently.config.consent_version)
+        Consent.from_cookie(
+          cookies[Consently.config.cookie_name],
+          version: Consently.config.consent_version,
+          max_age: Consently.config.consent_max_age
+        )
       else
         # Nobody to ask, so nothing is held back.
         Consent.new(categories: Consently.config.categories, version: Consently.config.consent_version)
@@ -75,7 +78,7 @@ module Consently
     # Push an event onto the dataLayer from a view, respecting consent: with
     # no analytics consent the event is simply not emitted.
     #
-    #   <%= consently_data_layer_push("purchase", value: 120, currency: "EUR") %>
+    #   <%= consently_data_layer_push("newsletter_signup", source: "footer") %>
     def consently_data_layer_push(event, category: :analytics, **payload)
       return "".html_safe unless consently_enabled? && consently_consent.granted?(category)
 
@@ -83,6 +86,31 @@ module Consently
       consently_inline_script "window.dataLayer = window.dataLayer || []; window.dataLayer.push(#{payload.to_json});"
     end
 
+    # A GA4 ecommerce event in the shape Google expects, from whatever your
+    # models happen to look like:
+    #
+    #   <%= consently_ecommerce("purchase", items: @order.line_items,
+    #         value: @order.total, currency: "EUR", transaction_id: @order.number) %>
+    #
+    # Items may be hashes already in GA4 shape, or any object answering to a
+    # few obvious names (id/sku, name, price, quantity, category, brand,
+    # variant) - a LineItem or a Product usually does.
+    #
+    # The previous ecommerce object is cleared first, as Google asks, so two
+    # events on one page cannot bleed into each other.
+    def consently_ecommerce(event, items: [], category: :analytics, **params)
+      return "".html_safe unless consently_enabled? && consently_consent.granted?(category)
+
+      ecommerce = params.merge(items: Array(items).map { |item| consently_ecommerce_item(item) })
+      payload = { event: event, ecommerce: ecommerce.compact }
+
+      consently_inline_script <<~JS.strip
+        window.dataLayer = window.dataLayer || [];
+        window.dataLayer.push({ ecommerce: null });
+        window.dataLayer.push(#{payload.to_json});
+      JS
+    end
+
     # A complete cookie policy for the tags this request would load: every
     # category, every vendor, every cookie it sets and for how long, plus
     # whether the visitor has agreed to it right now.
@@ -92,6 +120,30 @@ module Consently
       render "consently/policy", tags: Consently.tags_for(request), consent: consently_consent
     end
 
+    # An embedded video or map that waits for consent. Blocking scripts is
+    # only half the job: a YouTube iframe sets cookies all by itself.
+    #
+    #   <%= consently_embed :youtube, "dQw4w9WgXcQ" %>
+    #   <%= consently_embed :vimeo, "76979871", category: :analytics %>
+    #   <%= consently_embed :google_maps, "Bahnhofstrasse 12, Berlin" %>
+    #   <%= consently_embed :custom, "https://example.com/widget", title: "Widget" %>
+    #
+    # Until the category is granted the visitor sees a placeholder with a
+    # button that opens the preferences panel; the iframe appears the moment
+    # they agree, without a reload.
+    def consently_embed(kind, identifier, category: :marketing, title: nil, ratio: "16 / 9", **iframe_options)
+      src = consently_embed_src(kind, identifier)
+      return "".html_safe if src.blank?
+
+      render "consently/embed",
+        src: src,
+        title: title || t("consently.embed.title_#{kind}", default: t("consently.embed.title_default")),
+        category: category.to_sym,
+        ratio: ratio,
+        granted: consently_consent.granted?(category),
+        iframe_options: iframe_options
+    end
+
     # The banner brings its own plain CSS - no framework, no build step. The
     # look is driven by custom properties, so overriding a few variables is
     # usually enough; `rails g consently:views` is there for the rest.
@@ -115,6 +167,15 @@ module Consently
       Consently.enabled?(request)
     end
 
+    # Whether this tag may run now. Normally that means consent; under
+    # advanced consent mode Google's own tags also load before it, having
+    # been told to store nothing until it arrives.
+    def consently_release?(provider)
+      return true if consently_consent.granted?(provider.category)
+
+      Consently.config.advanced_google_consent_mode? && provider.google?
+    end
+
     # Google's consent mode v2 defaults. This one is never blocked: its whole
     # job is to tell Google's tags that they may not store anything yet, and
     # it has to be on the page before them.
@@ -138,6 +199,47 @@ module Consently
       JS
     end
 
+    # A bare id is enough for the vendors people embed most; anything else
+    # takes a full URL.
+    def consently_embed_src(kind, identifier)
+      identifier = identifier.to_s
+      return identifier if identifier.start_with?("http")
+
+      case kind.to_sym
+      when :youtube then "https://www.youtube-nocookie.com/embed/#{u(identifier)}"
+      when :vimeo then "https://player.vimeo.com/video/#{u(identifier)}"
+      when :google_maps then "https://www.google.com/maps?q=#{u(identifier)}&output=embed"
+      end
+    end
+
+    # Whatever the application handed us, in the shape GA4 reads. Hashes pass
+    # through (with symbol keys stringified by to_json anyway); objects are
+    # asked for the handful of names that carry the same meaning everywhere.
+    def consently_ecommerce_item(item)
+      return item.compact if item.is_a?(Hash)
+
+      {
+        item_id: consently_first_value(item, :item_id, :sku, :id),
+        item_name: consently_first_value(item, :item_name, :name, :title),
+        price: consently_first_value(item, :price, :unit_price, :price_eur),
+        quantity: consently_first_value(item, :quantity, :qty),
+        item_category: consently_first_value(item, :item_category, :category),
+        item_brand: consently_first_value(item, :item_brand, :brand),
+        item_variant: consently_first_value(item, :item_variant, :variant)
+      }.compact
+    end
+
+    def consently_first_value(item, *names)
+      names.each do |name|
+        next unless item.respond_to?(name)
+
+        value = item.public_send(name)
+        return value.respond_to?(:name) ? value.name : value if value.present?
+      end
+
+      nil
+    end
+
     # A plain <script> with the JS as written. javascript_tag would wrap it in
     # a CDATA comment nobody has needed since XHTML.
     def consently_inline_script(javascript)

data/app/javascript/consently/banner_controller.js

@@ -16,6 +16,7 @@ export default class extends Controller {
     version: { type: String, default: "1" },
     maxAge: { type: Number, default: 60 * 60 * 24 * 180 },
     path: { type: String, default: "/" },
+    domain: String,
     categories: Array,
     googleConsentMode: { type: Boolean, default: true },
     respectDoNotTrack: { type: Boolean, default: false },
@@ -105,8 +106,10 @@ export default class extends Controller {
   #writeCookie(categories) {
     const value = JSON.stringify({ v: this.versionValue, c: categories, t: new Date().toISOString() })
     const secure = window.location.protocol === "https:" ? "; Secure" : ""
+    // A domain of ".example.com" is what carries the choice across subdomains.
+    const domain = this.domainValue ? `; domain=${this.domainValue}` : ""
 
-    document.cookie = `${this.cookieValue}=${encodeURIComponent(value)}; path=${this.pathValue}; max-age=${this.maxAgeValue}; SameSite=Lax${secure}`
+    document.cookie = `${this.cookieValue}=${encodeURIComponent(value)}; path=${this.pathValue}${domain}; max-age=${this.maxAgeValue}; SameSite=Lax${secure}`
   }
 
   #activateScripts(categories) {

data/app/javascript/consently/embed_controller.js

@@ -0,0 +1,40 @@
+import { Controller } from "@hotwired/stimulus"
+
+// A video or map that appears the moment its category is granted. The banner
+// announces every decision on `document`, so this controller only has to
+// listen and build the iframe the server did not render.
+export default class extends Controller {
+  static targets = ["placeholder"]
+  static classes = ["hidden"]
+
+  static values = {
+    category: String,
+    src: String,
+    title: String,
+    attributes: { type: Object, default: {} }
+  }
+
+  // The event carries the categories, so no cookie parsing here.
+  granted({ detail }) {
+    if (!detail.categories.includes(this.categoryValue)) return
+
+    this.#insertFrame()
+  }
+
+  #insertFrame() {
+    if (this.element.querySelector("iframe")) return
+
+    const frame = document.createElement("iframe")
+    frame.src = this.srcValue
+    frame.title = this.titleValue
+    frame.loading = "lazy"
+    frame.allowFullscreen = true
+    frame.className = "consently-embed__frame"
+    for (const [name, value] of Object.entries(this.attributesValue)) {
+      frame.setAttribute(name, value)
+    }
+
+    this.element.prepend(frame)
+    this.placeholderTarget.classList.add(...this.hiddenClasses)
+  }
+}

data/app/views/consently/_banner.html.erb

@@ -13,6 +13,7 @@
      data-consently-banner-version-value="<%= Consently.config.consent_version %>"
      data-consently-banner-max-age-value="<%= Consently.config.cookie_max_age %>"
      data-consently-banner-path-value="<%= Consently.config.cookie_path %>"
+     data-consently-banner-domain-value="<%= Consently.config.cookie_domain %>"
      data-consently-banner-categories-value="<%= categories.map(&:to_s).to_json %>"
      data-consently-banner-google-consent-mode-value="<%= Consently.config.google_consent_mode %>"
      data-consently-banner-respect-do-not-track-value="<%= Consently.config.respect_do_not_track %>"

data/app/views/consently/_embed.html.erb

@@ -0,0 +1,24 @@
+<%# An iframe that waits for consent. The src lives in a data attribute until
+    then, so nothing is requested from the vendor and no cookie is set. %>
+<div class="consently-embed"
+     style="--consently-embed-ratio: <%= ratio %>"
+     data-controller="consently-embed"
+     data-consently-embed-category-value="<%= category %>"
+     data-consently-embed-src-value="<%= src %>"
+     data-consently-embed-title-value="<%= title %>"
+     data-consently-embed-attributes-value="<%= iframe_options.to_json %>"
+     data-consently-embed-hidden-class="consently-hidden"
+     data-action="consently:change@document->consently-embed#granted">
+  <% if granted %>
+    <%= tag.iframe src: src, title: title, loading: "lazy", allowfullscreen: true,
+          class: "consently-embed__frame", **iframe_options %>
+  <% end %>
+
+  <div class="consently-embed__placeholder <%= "consently-hidden" if granted %>"
+       data-consently-embed-target="placeholder">
+    <p class="consently-embed__text"><%= t("consently.embed.blocked", category: t("consently.categories.#{category}.name", default: category.to_s.humanize)) %></p>
+    <button type="button" data-consently-open class="consently__button consently__button--primary">
+      <%= t("consently.embed.allow") %>
+    </button>
+  </div>
+</div>

data/config/importmap.rb

@@ -1,3 +1,4 @@
 # Pinned for the host application, so `import "consently/banner_controller"`
-# resolves without anyone editing their own importmap.
+# resolves without anyone editing config/importmap.rb.
 pin "consently/banner_controller", to: "consently/banner_controller.js", preload: true
+pin "consently/embed_controller", to: "consently/embed_controller.js", preload: true

data/config/locales/cs.yml

@@ -9,6 +9,13 @@ cs:
       save: "Uložit volbu"
       cancel: "Zrušit"
     preferences_link: "Nastavení cookies"
+    embed:
+      blocked: "Tento obsah se načítá z jiného webu a vyžaduje váš souhlas pro kategorii %{category}."
+      allow: "Povolit a zobrazit"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Mapa"
+      title_default: "Vložený obsah"
     policy:
       granted: "souhlas udělen"
       denied: "bez souhlasu"

data/config/locales/de.yml

@@ -9,6 +9,13 @@ de:
       save: "Auswahl speichern"
       cancel: "Abbrechen"
     preferences_link: "Cookie-Einstellungen"
+    embed:
+      blocked: "Dieser Inhalt wird von einer anderen Website geladen und braucht Ihre Einwilligung für %{category}."
+      allow: "Erlauben und anzeigen"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Karte"
+      title_default: "Eingebetteter Inhalt"
     policy:
       granted: "eingewilligt"
       denied: "nicht eingewilligt"

data/config/locales/en.yml

@@ -9,6 +9,13 @@ en:
       save: "Save choices"
       cancel: "Cancel"
     preferences_link: "Cookie settings"
+    embed:
+      blocked: "This content is loaded from another site and needs your %{category} consent."
+      allow: "Allow and show"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Map"
+      title_default: "Embedded content"
     policy:
       granted: "you agreed"
       denied: "not agreed"

data/config/locales/es.yml

@@ -9,6 +9,13 @@ es:
       save: "Guardar selección"
       cancel: "Cancelar"
     preferences_link: "Ajustes de cookies"
+    embed:
+      blocked: "Este contenido se carga desde otro sitio y necesita tu consentimiento de %{category}."
+      allow: "Permitir y mostrar"
+      title_youtube: "Vídeo"
+      title_vimeo: "Vídeo"
+      title_google_maps: "Mapa"
+      title_default: "Contenido incrustado"
     policy:
       granted: "consentido"
       denied: "sin consentimiento"

data/config/locales/fr.yml

@@ -9,6 +9,13 @@ fr:
       save: "Enregistrer mes choix"
       cancel: "Annuler"
     preferences_link: "Paramètres des cookies"
+    embed:
+      blocked: "Ce contenu provient d'un autre site et nécessite votre accord pour %{category}."
+      allow: "Autoriser et afficher"
+      title_youtube: "Vidéo"
+      title_vimeo: "Vidéo"
+      title_google_maps: "Carte"
+      title_default: "Contenu intégré"
     policy:
       granted: "accepté"
       denied: "non accepté"

data/config/locales/hu.yml

@@ -9,6 +9,13 @@ hu:
       save: "Választás mentése"
       cancel: "Mégse"
     preferences_link: "Süti beállítások"
+    embed:
+      blocked: "Ez a tartalom másik oldalról töltődik be, és a(z) %{category} kategóriához adott hozzájárulásod kell hozzá."
+      allow: "Engedélyezés és megjelenítés"
+      title_youtube: "Videó"
+      title_vimeo: "Videó"
+      title_google_maps: "Térkép"
+      title_default: "Beágyazott tartalom"
     policy:
       granted: "hozzájárultál"
       denied: "nincs hozzájárulás"

data/config/locales/it.yml

@@ -9,6 +9,13 @@ it:
       save: "Salva le scelte"
       cancel: "Annulla"
     preferences_link: "Impostazioni cookie"
+    embed:
+      blocked: "Questo contenuto viene caricato da un altro sito e richiede il tuo consenso per %{category}."
+      allow: "Consenti e mostra"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Mappa"
+      title_default: "Contenuto incorporato"
     policy:
       granted: "consenso dato"
       denied: "nessun consenso"

data/config/locales/nl.yml

@@ -9,6 +9,13 @@ nl:
       save: "Keuze opslaan"
       cancel: "Annuleren"
     preferences_link: "Cookie-instellingen"
+    embed:
+      blocked: "Deze inhoud komt van een andere site en heeft je toestemming voor %{category} nodig."
+      allow: "Toestaan en tonen"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Kaart"
+      title_default: "Ingesloten inhoud"
     policy:
       granted: "toegestaan"
       denied: "niet toegestaan"

data/config/locales/pl.yml

@@ -9,6 +9,13 @@ pl:
       save: "Zapisz wybór"
       cancel: "Anuluj"
     preferences_link: "Ustawienia cookies"
+    embed:
+      blocked: "Ta treść ładuje się z innej strony i wymaga Twojej zgody na kategorię %{category}."
+      allow: "Zezwól i pokaż"
+      title_youtube: "Wideo"
+      title_vimeo: "Wideo"
+      title_google_maps: "Mapa"
+      title_default: "Osadzona treść"
     policy:
       granted: "zgoda udzielona"
       denied: "brak zgody"

data/config/locales/sk.yml

@@ -9,6 +9,13 @@ sk:
       save: "Uložiť voľbu"
       cancel: "Zrušiť"
     preferences_link: "Nastavenia cookies"
+    embed:
+      blocked: "Tento obsah sa načítava z inej stránky a vyžaduje váš súhlas pre kategóriu %{category}."
+      allow: "Povoliť a zobraziť"
+      title_youtube: "Video"
+      title_vimeo: "Video"
+      title_google_maps: "Mapa"
+      title_default: "Vložený obsah"
     policy:
       granted: "súhlas udelený"
       denied: "bez súhlasu"

data/lib/consently/configuration.rb

@@ -5,7 +5,15 @@ module Consently
 
     # Where the visitor's choice is kept. It is read by JavaScript, so it is a
     # plain cookie rather than a signed one.
-    attr_accessor :cookie_name, :cookie_max_age, :cookie_path
+    #
+    # Set cookie_domain to ".example.com" when the site spans subdomains -
+    # without it a consent given on www does not count on shop.
+    attr_accessor :cookie_name, :cookie_max_age, :cookie_path, :cookie_domain
+
+    # How long a consent stays valid, regardless of the cookie's own lifetime.
+    # Guidance across the EU converges on asking again about once a year; nil
+    # leaves the cookie to expire on its own.
+    attr_accessor :consent_max_age
 
     # Bump this whenever the policy changes: an older consent stops counting
     # and the banner asks again.
@@ -15,10 +23,32 @@ module Consently
     #   c.enabled = ->(request) { Rails.env.production? }
     attr_accessor :enabled
 
-    # Emits Google's consent mode v2 defaults (everything denied) before any
-    # Google tag, and updates them when the visitor chooses. Leave it on if
-    # you use any Google product.
-    attr_accessor :google_consent_mode
+    # Google's consent mode v2. Three settings:
+    #
+    #   :basic     - defaults denied, and Google's own tags stay blocked until
+    #                the visitor agrees. Nothing about them reaches Google
+    #                before consent. The default, and the strict reading.
+    #   :advanced  - defaults denied, but Google's tags load right away and
+    #                send cookieless pings, which is what lets Google Ads
+    #                model the conversions of visitors who said no. More data,
+    #                and a request to Google either way - ask your lawyer.
+    #   false      - no consent mode at all.
+    #
+    # `true` is read as :basic.
+    attr_reader :google_consent_mode
+
+    def google_consent_mode=(mode)
+      @google_consent_mode = case mode
+      when true, :basic then :basic
+      when :advanced then :advanced
+      when false, nil then false
+      else raise ArgumentError, "google_consent_mode must be :basic, :advanced or false"
+      end
+    end
+
+    def advanced_google_consent_mode?
+      google_consent_mode == :advanced
+    end
 
     # Store a row per decision, as proof of consent. Needs the engine mounted
     # and the migration from `rails g consently:consent_log`.
@@ -74,9 +104,11 @@ module Consently
       @cookie_name = "consently"
       @cookie_max_age = 60 * 60 * 24 * 180 # six months, the usual guidance
       @cookie_path = "/"
+      @cookie_domain = nil
+      @consent_max_age = nil
       @consent_version = 1
       @enabled = true
-      @google_consent_mode = true
+      @google_consent_mode = :basic
       @stylesheet = true
       @log_consents = false
       @respect_do_not_track = false
@@ -111,8 +143,8 @@ module Consently
     # back to the tags declared outside any scope, and may override them by
     # declaring the same provider again.
     #
-    #   c.scope "trixbrix" do |s|
-    #     s.tag :google_analytics, id: "G-TRIX"
+    #   c.scope "shop.example.com" do |s|
+    #     s.tag :google_analytics, id: "G-SHOP00001"
     #   end
     def scope(name)
       scope = (@scopes[name.to_s] ||= Scope.new)

data/lib/consently/consent.rb

@@ -17,7 +17,7 @@ module Consently
 
     # Never raises: a cookie can be truncated, hand-edited or left over from an
     # older format, and none of that should take a page down.
-    def self.from_cookie(raw, version:)
+    def self.from_cookie(raw, version:, max_age: nil)
       return none if raw.blank?
 
       data = begin
@@ -30,6 +30,7 @@ module Consently
       # A consent given against an older policy version counts as no consent:
       # the banner asks again and nothing runs in the meantime.
       return none unless data["v"].to_s == version.to_s
+      return none if expired?(data["t"], max_age)
 
       new(
         categories: Array(data["c"]).map { |category| category.to_s.to_sym },
@@ -38,6 +39,18 @@ module Consently
       )
     end
 
+    # A consent older than max_age is asked for again, whatever the cookie's
+    # own expiry says. An unreadable timestamp is treated as too old: the only
+    # safe reading when we cannot tell when it was given.
+    def self.expired?(recorded_at, max_age)
+      return false if max_age.nil?
+      return true if recorded_at.blank?
+
+      Time.parse(recorded_at.to_s) < Time.now.utc - max_age.to_i
+    rescue ArgumentError
+      true
+    end
+
     def initialize(categories: [], version: nil, recorded_at: nil, given: true)
       @categories = Array(categories).map(&:to_sym).freeze
       @version = version

data/lib/consently/engine.rb

@@ -14,7 +14,7 @@ module Consently
       if app.config.respond_to?(:assets)
         app.config.assets.paths << root.join("app/javascript")
         if app.config.assets.respond_to?(:precompile)
-          app.config.assets.precompile += %w[consently.css consently/banner_controller.js]
+          app.config.assets.precompile += %w[consently.css consently/banner_controller.js consently/embed_controller.js]
         end
       end
     end

data/lib/consently/providers/base.rb

@@ -22,6 +22,15 @@ module Consently
           klass.new(**options)
         end
 
+# Whether this vendor is one of Google's, which is what advanced
+# consent mode is about: those tags may load before consent because
+# they respect the denied defaults themselves.
+attr_writer :google
+
+def google?
+  !!@google
+end
+
         # Set by each subclass; where a vendor is unambiguous (Plausible does
         # not touch cookies) it can say :necessary and load right away.
         attr_accessor :default_category
@@ -60,6 +69,10 @@ module Consently
         []
       end
 
+      def google?
+        self.class.google?
+      end
+
       # Array<Consently::Cookie> - what this tag leaves in the browser.
       def cookies
         self.class.cookie_manifest.map { |attributes| Cookie.new(**attributes, provider: key) }

data/lib/consently/providers/google_ads.rb

@@ -3,6 +3,7 @@ module Consently
     class GoogleAds < Base
       self.provider_key = :google_ads
       self.default_category = :marketing
+      self.google = true
 
       cookie "_gcl_au", days: 90
 

data/lib/consently/providers/google_analytics.rb

@@ -5,6 +5,7 @@ module Consently
     class GoogleAnalytics < Base
       self.provider_key = :google_analytics
       self.default_category = :analytics
+      self.google = true
 
       # What GA4 leaves behind. The container-scoped one is written per
       # measurement id, hence the wildcard.

data/lib/consently/providers/google_tag_manager.rb

@@ -3,6 +3,7 @@ module Consently
     class GoogleTagManager < Base
       self.provider_key = :google_tag_manager
       self.default_category = :analytics
+      self.google = true
 
       # None of its own: whatever it loads brings its own cookies, so list
       # those tags here as well if you manage them through the container.

data/lib/consently/version.rb

@@ -1,3 +1,3 @@
 module Consently
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/consently.rb

@@ -1,4 +1,5 @@
 require "json"
+require "time"
 require "active_support"
 require "active_support/core_ext/object/blank"
 

data/lib/generators/consently/install/install_generator.rb

@@ -21,7 +21,9 @@ module Consently
         append_to_file index, <<~JS
 
           import ConsentlyBannerController from "consently/banner_controller"
+          import ConsentlyEmbedController from "consently/embed_controller"
           application.register("consently-banner", ConsentlyBannerController)
+          application.register("consently-embed", ConsentlyEmbedController)
         JS
       end
 

data/lib/generators/consently/install/templates/consently.rb

@@ -25,9 +25,16 @@ Consently.configure do |c|
   # not - switch it on if you want it treated the same way.
   # c.respect_do_not_track = true
 
-  # Google consent mode v2: defaults denied before any Google tag, updated
-  # when the visitor chooses. Leave on if you use anything Google.
-  c.google_consent_mode = true
+# Google consent mode v2. :basic keeps Google's tags off the page until the
+# visitor agrees; :advanced loads them denied, so Ads can model refused
+# conversions - more data, and a request to Google either way.
+c.google_consent_mode = :basic
+
+# One consent across subdomains needs the domain spelled out.
+# c.cookie_domain = ".example.com"
+
+# Ask again after a while, whatever the cookie's own lifetime says.
+# c.consent_max_age = 12.months
 
   # Store a row per decision as proof of consent. Needs the migration from
   # `rails g consently:consent_log` and the engine mounted in routes.rb:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: consently
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michał Krzysteczko
@@ -28,15 +28,19 @@ description: 'Most Rails cookie banners ask for consent and then load Google Ana
   Google Ads, Microsoft Clarity, Meta Pixel, Hotjar, Plausible or anything custom
   - and it renders every non-essential one as an inert script the browser will not
   even fetch, then turns them into live scripts the instant the visitor agrees, with
-  no page reload. Google Consent Mode v2 defaults are emitted before any Google tag
-  and updated on the click. The banner and its preferences panel ship translated into
-  ten European languages, styled in plain CSS with no Tailwind and no build step,
-  and driven by one Stimulus controller. Your cookie policy page is generated from
-  the same configuration - every vendor, every cookie it sets and for how long - so
-  it cannot drift out of date. Multi-tenant applications get per-domain or per-shop
-  tag sets from a single initializer, and an optional consent log stores proof of
-  each decision in your own database, with no third-party service and nothing leaving
-  your infrastructure.'
+  no page reload. Embedded YouTube, Vimeo and Google Maps iframes wait behind a placeholder
+  of the same size and appear on consent too, because an iframe sets cookies with
+  no script of yours. Google Consent Mode v2 defaults are emitted before any Google
+  tag and updated on the click, in basic mode or in advanced mode where Google''s
+  own tags load denied so Ads can model refused conversions. GA4 ecommerce events
+  are built from your own line items rather than by hand. The banner and its preferences
+  panel ship translated into ten European languages, styled in plain CSS with no Tailwind
+  and no build step. Your cookie policy page is generated from the same configuration
+  - every vendor, every cookie it sets and for how long - so it cannot drift out of
+  date. Multi-tenant applications get per-domain or per-shop tag sets from a single
+  initializer, one consent can span subdomains, and an optional consent log stores
+  proof of each decision in your own database, with no third-party service and nothing
+  leaving your infrastructure.'
 email:
 - m.krzysteczko@icloud.com
 executables: []
@@ -53,9 +57,11 @@ files:
 - app/helpers/consently/application_helper.rb
 - app/helpers/consently/tags_helper.rb
 - app/javascript/consently/banner_controller.js
+- app/javascript/consently/embed_controller.js
 - app/models/consently/application_record.rb
 - app/models/consently/consent_record.rb
 - app/views/consently/_banner.html.erb
+- app/views/consently/_embed.html.erb
 - app/views/consently/_policy.html.erb
 - config/importmap.rb
 - config/locales/cs.yml