consently 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ae532d0c3dd92af70f6bd6bfae150b2d61889fbb7ecae3ea1edae521e33605a
-  data.tar.gz: f0bccd48aba2d92a00e1a1359580b5f051206de246aa205bb3a2a3323df516c9
+  metadata.gz: dab77a672e8b422500eceb9e90f0481fc4f7abb180e22ca7c12fadf98c4ef9ef
+  data.tar.gz: 802a3a6d8c5915acce9d6e843bb5fd8b10a28a7eafb4dd68d0af8bc8617ba43b
 SHA512:
-  metadata.gz: 8c2917ed994ffc2db028512616ef551d18471e2e68df786e150337fae51b14c8de902aabd209cf3d65a81b14fcd7aed13135e5b2a8a3f886a217a5e6b4abd348
-  data.tar.gz: bc74d85205720239b176d6caeab993e1bd08d9c49258f4fc6778dd17d763b808a4705155f32b8f7eec620102b1f4215469d3b523fe51b859c74a6961fafa763e
+  metadata.gz: 3097f21d9037f63e8d27a697e73c2fae5e54b246e1de83e6722a40b2915005400c45ede835a7d8b77aaf1c3da55b877ba6318e23617aad7b3d00de9d0b001e59
+  data.tar.gz: 4247ab6d468b280bc7b784c52401d1f4ee53d98e627f168206159bea2daebc08ff3c359124afd71849b7cf535de37f9b50b49795e020099c988db74dfd12fc67

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.0.0 (2026-09-04)
+
+- Events speak the language of the page's tags: `gtag('event', ...)` under
+  gtag.js, a `dataLayer` push under Google Tag Manager, decided per request
+  from the tags in scope or forced with `event_transport`. Before, every event
+  was a dataLayer push - which gtag.js ignores, so a shop without a container
+  lost its whole ecommerce funnel.
+- An event rendered without consent is held back as an inert script and
+  released with the tags when its category is granted, instead of being
+  dropped. The page a visitor accepts on now counts its `view_item`.
+- `consently_stream_event` sends an event from a Turbo Stream response - the
+  add-to-cart that never renders a page - through a stream action that ships
+  with the banner controller; it is sent at once with consent and queued
+  until then otherwise.
+- `Consently.track(event, payload, { category })` and `Consently.granted()`
+  in JavaScript, on the same queue.
+- `consently_event` is the new name of `consently_data_layer_push`; the old
+  one still works.
+
 ## 0.2.1 (2026-08-13)
 
 - The banner's custom properties moved from `.consently` to `:root`, so the

data/README.md

@@ -201,8 +201,9 @@ status panel - ask for a reload instead:
 c.reload_after_choice = true
 ```
 
-Either way a `consently:change` event fires on `document`, carrying the
-granted categories, so you can react to it yourself:
+Either way the events waiting on that consent go out too (see below), and a
+`consently:change` event fires on `document`, carrying the granted categories,
+so you can react to it yourself:
 
 ```js
 document.addEventListener("consently:change", ({ detail }) => {
@@ -237,7 +238,7 @@ 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.
 
-## Ecommerce events
+## Events
 
 GA4 wants a particular shape, and your models are not it. Hand the helper
 whatever you have:
@@ -249,17 +250,50 @@ whatever you have:
 
 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.
+line item or a product usually does. Anything else:
 
-Anything else:
+```erb
+<%= consently_event "newsletter_signup", source: "footer" %>
+```
+
+**Sent the way your tags listen.** A page running gtag.js gets
+`gtag('event', ...)` calls; a page running Google Tag Manager gets `dataLayer`
+pushes, the previous `ecommerce` object cleared first as Google asks. The gem
+decides per request from the tags in scope - a container means the dataLayer,
+any other Google tag means gtag - because a push meant for a container is
+something gtag.js silently ignores, and a whole checkout funnel can go missing
+that way. Force it if you must:
+
+```ruby
+c.event_transport = :data_layer   # or :gtag; :auto is the default
+```
+
+**Held back, not dropped.** Without consent an event is rendered the way a tag
+is - an inert `<script type="text/plain">` - and released together with the
+tags the moment its category is granted. The product page a visitor accepts
+on still counts its `view_item`.
+
+**From a Turbo Stream.** An add-to-cart that answers with a stream renders no
+page to put a script on. The stream carries the event instead, and the
+JavaScript side sends it at once if the category is granted, or keeps it until
+it is:
 
 ```erb
-<%= consently_data_layer_push "newsletter_signup", source: "footer" %>
+<%# line_items/create.turbo_stream.erb %>
+<%= turbo_stream.replace "cart", partial: "cart" %>
+<%= consently_stream_event "add_to_cart", items: [@line_item],
+      currency: "EUR", value: @line_item.price %>
 ```
 
-Both render nothing at all when analytics consent is missing.
+Nothing to register: the action arrives with the banner controller.
+
+**From your own JavaScript.** The same queue, the same rule:
+
+```js
+Consently.track("newsletter_signup", { source: "footer" })
+Consently.track("lead", { value: 1 }, { category: "marketing", ecommerce: false })
+Consently.granted("analytics") // true or false, right now
+```
 
 ## Embedded videos and maps
 
@@ -376,13 +410,14 @@ Helpers:
 
 | | |
 | --- | --- |
-| `consently_tags` | `<head>`: the stylesheet, consent mode defaults, and every tag (blocked or live) |
+| `consently_tags` | `<head>`: the stylesheet, consent mode defaults, every tag (blocked or live), and what the JavaScript side needs to know |
 | `consently_noscript_tags` | after `<body>`: GTM and Meta fallbacks, for granted categories only |
 | `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_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_ecommerce(event, items:, **params)` | a GA4 ecommerce event, items mapped from your own objects; held back until consent |
+| `consently_event(event, **payload)` | any other event, gtag or dataLayer as the page's tags expect; held back until consent |
+| `consently_stream_event(event, items:, **payload)` | the same from a Turbo Stream response, sent or queued in the browser |
 | `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 |
 
@@ -397,6 +432,7 @@ Configuration:
 | `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` | `:basic` (default), `:advanced`, or `false` |
+| `c.event_transport` | `:auto` (default: gtag under gtag.js, the dataLayer under a container), `:gtag`, `:data_layer` |
 | `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`, `c.cookie_domain` | where the choice is kept |
@@ -404,8 +440,9 @@ Configuration:
 | `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 |
 
-JavaScript: a `consently:change` event fires on `document` with the granted
-categories.
+JavaScript: `Consently.track(event, payload, { category })` sends or queues
+an event, `Consently.granted(category)` says where things stand, and a
+`consently:change` event fires on `document` with the granted categories.
 
 ## Licence
 

data/app/helpers/consently/tags_helper.rb

@@ -9,7 +9,7 @@ module Consently
     def consently_tags
       return "".html_safe unless consently_enabled?
 
-      parts = []
+      parts = [ consently_state_tags ]
       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|
@@ -75,17 +75,21 @@ module Consently
       end
     end
 
-    # Push an event onto the dataLayer from a view, respecting consent: with
-    # no analytics consent the event is simply not emitted.
+    # An analytics event from a view, sent the way this page's tags expect -
+    # gtag('event', ...) under gtag.js, a dataLayer push under Google Tag
+    # Manager (see Consently.event_transport_for) - and only with consent.
+    # Without it the event is held back the way a tag is: an inert script
+    # the banner releases the moment the category is granted, so the page a
+    # visitor accepts on still counts.
     #
-    #   <%= 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)
-
-      payload = payload.merge(event: event)
-      consently_inline_script "window.dataLayer = window.dataLayer || []; window.dataLayer.push(#{payload.to_json});"
+    #   <%= consently_event("newsletter_signup", source: "footer") %>
+    def consently_event(event, category: :analytics, **payload)
+      consently_event_tag(Event.new(event, payload), category)
     end
 
+    # The name this helper had before it learnt to speak gtag.
+    alias_method :consently_data_layer_push, :consently_event
+
     # A GA4 ecommerce event in the shape Google expects, from whatever your
     # models happen to look like:
     #
@@ -96,19 +100,32 @@ module Consently
     # 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.
+    # Under Google Tag Manager the previous ecommerce object is cleared
+    # first, as Google asks, so two events on one page cannot bleed into
+    # each other. Held back without consent, like consently_event.
     def consently_ecommerce(event, items: [], category: :analytics, **params)
-      return "".html_safe unless consently_enabled? && consently_consent.granted?(category)
+      consently_event_tag(Event.new(event, params.merge(items: consently_ecommerce_items(items)), ecommerce: true), category)
+    end
 
-      ecommerce = params.merge(items: Array(items).map { |item| consently_ecommerce_item(item) })
-      payload = { event: event, ecommerce: ecommerce.compact }
+    # The same event from a Turbo Stream response - an add-to-cart that
+    # never renders a page. Items make it an ecommerce event. The stream
+    # carries the event, not a script: the JavaScript side sends it at once
+    # if the category is granted and keeps it until then otherwise, so a
+    # cart filled before the click is counted after it.
+    #
+    #   <%= consently_stream_event("add_to_cart", items: [ @line_item ], currency: "EUR", value: 12.5) %>
+    def consently_stream_event(event, items: nil, category: :analytics, **payload)
+      return "".html_safe unless consently_enabled?
 
-      consently_inline_script <<~JS.strip
-        window.dataLayer = window.dataLayer || [];
-        window.dataLayer.push({ ecommerce: null });
-        window.dataLayer.push(#{payload.to_json});
-      JS
+      payload = payload.merge(items: consently_ecommerce_items(items)) unless items.nil?
+      event = Event.new(event, payload, ecommerce: !items.nil?)
+
+      content_tag("turbo-stream", "",
+        action: "consently_event",
+        event: event.name,
+        category: category,
+        ecommerce: event.ecommerce?,
+        payload: event.payload.to_json)
     end
 
     # A complete cookie policy for the tags this request would load: every
@@ -167,6 +184,40 @@ module Consently
       Consently.enabled?(request)
     end
 
+    # Two <meta> tags the JavaScript side reads: which categories this page
+    # was rendered with, and how events are to be sent. Provisional head
+    # elements, so Turbo Drive swaps them on every visit.
+    def consently_state_tags
+      granted = Consently.config.categories.select { |category| consently_consent.granted?(category) }
+
+      safe_join([
+        tag.meta(name: "consently-granted", content: granted.join(" ")),
+        tag.meta(name: "consently-transport", content: consently_event_transport)
+      ], "\n")
+    end
+
+    def consently_event_transport
+      @consently_event_transport ||= Consently.event_transport_for(request)
+    end
+
+    # Live when the category is granted; otherwise inert, and released by the
+    # banner together with the tags the moment it is.
+    def consently_event_tag(event, category)
+      return "".html_safe unless consently_enabled?
+
+      javascript = event.to_js(consently_event_transport)
+      return consently_inline_script(javascript) if consently_consent.granted?(category)
+
+      attributes = { type: "text/plain", data: { "consently-category" => category } }
+      attributes[:nonce] = content_security_policy_nonce if content_security_policy_nonce.present?
+
+      content_tag(:script, javascript.html_safe, attributes)
+    end
+
+    def consently_ecommerce_items(items)
+      Array(items).map { |item| consently_ecommerce_item(item) }
+    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.

data/app/javascript/consently/banner_controller.js

@@ -1,4 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
+// Loaded for its side effects: the event queue, the Turbo Stream action and
+// window.Consently.track come along with the banner.
+import "consently/events"
 
 // The banner, the preferences panel, and the part that actually matters:
 // turning the blocked <script type="text/plain"> tags into live ones the

data/app/javascript/consently/events.js

@@ -0,0 +1,78 @@
+// Analytics events that wait for consent.
+//
+// Three roads lead here. An event rendered into a page without consent is an
+// inert <script> the banner releases together with the tags - nothing to do
+// on this side. A <turbo-stream action="consently_event"> comes from a
+// response that renders no page, and window.Consently.track() from your own
+// code; those two are sent at once when their category is granted and kept
+// until it is otherwise, so an add-to-cart that happened before the click is
+// counted after it.
+//
+// The page says what is granted and how to send in two <meta> tags written by
+// consently_tags. The banner's consently:change event overrides the first the
+// moment a choice is made, and the next Turbo visit brings a fresh page whose
+// tags already know.
+
+const NECESSARY = "necessary"
+const waiting = []
+let decided = null
+
+export function track(name, payload = {}, { category = "analytics", ecommerce = false } = {}) {
+  const event = { name, payload, category, ecommerce }
+
+  if (granted(category)) send(event)
+  else waiting.push(event)
+}
+
+export function granted(category) {
+  if (category === NECESSARY) return true
+
+  return (decided ?? meta("consently-granted").split(" ")).includes(category)
+}
+
+function meta(name) {
+  return document.querySelector(`meta[name="${name}"]`)?.content ?? ""
+}
+
+function send({ name, payload, ecommerce }) {
+  window.dataLayer = window.dataLayer || []
+
+  if (meta("consently-transport") === "gtag") {
+    // gtag.js reads the queue, so this is safe before the tag has loaded.
+    window.gtag = window.gtag || function () { window.dataLayer.push(arguments) }
+    window.gtag("event", name, payload)
+  } else if (ecommerce) {
+    window.dataLayer.push({ ecommerce: null })
+    window.dataLayer.push({ event: name, ecommerce: payload })
+  } else {
+    window.dataLayer.push({ event: name, ...payload })
+  }
+}
+
+function release(categories) {
+  decided = [...categories, NECESSARY]
+
+  waiting.splice(0).forEach((event) => (granted(event.category) ? send(event) : waiting.push(event)))
+}
+
+document.addEventListener("consently:change", (event) => release(event.detail.categories))
+
+// A new page carries the server's reading of the cookie, which also knows
+// about policy versions and expiry; from here on it is the one to trust.
+document.addEventListener("turbo:load", () => { decided = null })
+
+// The Turbo Stream action. A listener rather than an entry in
+// Turbo.StreamActions, so the gem imports nothing from Turbo and the order
+// the modules load in does not matter.
+document.addEventListener("turbo:before-stream-render", (event) => {
+  const stream = event.target
+  if (stream.getAttribute("action") !== "consently_event") return
+
+  event.preventDefault()
+  track(stream.getAttribute("event"), JSON.parse(stream.getAttribute("payload") || "{}"), {
+    category: stream.getAttribute("category") || "analytics",
+    ecommerce: stream.getAttribute("ecommerce") === "true"
+  })
+})
+
+window.Consently = Object.assign(window.Consently || {}, { track, granted })

data/config/importmap.rb

@@ -2,3 +2,4 @@
 # 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
+pin "consently/events", to: "consently/events.js", preload: true

data/lib/consently/configuration.rb

@@ -50,6 +50,21 @@ module Consently
       google_consent_mode == :advanced
     end
 
+    # How events are sent: :gtag for a page running gtag.js, :data_layer for
+    # one running Google Tag Manager. The default, :auto, decides per request
+    # from the tags in its scope (see Consently.event_transport_for) and is
+    # right unless you push to a container the gem does not know about.
+    attr_reader :event_transport
+
+    def event_transport=(transport)
+      transport = transport&.to_sym
+      unless [ :auto, *Event::TRANSPORTS ].include?(transport)
+        raise ArgumentError, "event_transport must be :auto, :gtag or :data_layer"
+      end
+
+      @event_transport = transport
+    end
+
     # Store a row per decision, as proof of consent. Needs the engine mounted
     # and the migration from `rails g consently:consent_log`.
     attr_accessor :log_consents
@@ -109,6 +124,7 @@ module Consently
       @consent_version = 1
       @enabled = true
       @google_consent_mode = :basic
+      @event_transport = :auto
       @stylesheet = true
       @log_consents = false
       @respect_do_not_track = false

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 consently/embed_controller.js]
+          app.config.assets.precompile += %w[consently.css consently/banner_controller.js consently/embed_controller.js consently/events.js]
         end
       end
     end

data/lib/consently/event.rb

@@ -0,0 +1,54 @@
+require "active_support/core_ext/object/json"
+
+module Consently
+  # One analytics event on its way to the page: a name, a payload, and whether
+  # it is a GA4 ecommerce event. It is written as JavaScript for whichever
+  # transport the page runs on - gtag('event', ...) for gtag.js, a dataLayer
+  # push for Google Tag Manager - so the helpers never have to know which.
+  class Event
+    TRANSPORTS = %i[gtag data_layer].freeze
+
+    attr_reader :name, :payload
+
+    def initialize(name, payload = {}, ecommerce: false)
+      @name = name.to_s
+      @payload = payload.to_h.compact
+      @ecommerce = ecommerce
+    end
+
+    def ecommerce?
+      @ecommerce
+    end
+
+    def to_js(transport)
+      case transport.to_sym
+      when :gtag then gtag_js
+      when :data_layer then data_layer_js
+      else raise ArgumentError, "Consently: unknown event transport #{transport.inspect}, expected one of #{TRANSPORTS.join(", ")}"
+      end
+    end
+
+    private
+
+    # gtag.js reads the dataLayer as a queue, so an event pushed before the
+    # tag has loaded is not lost. That is what lets a released event fire the
+    # moment consent arrives, while gtag.js is still on its way.
+    def gtag_js
+      "window.dataLayer = window.dataLayer || []; " \
+        "window.gtag = window.gtag || function(){dataLayer.push(arguments);}; " \
+        "gtag('event', #{name.to_json}, #{payload.to_json});"
+    end
+
+    def data_layer_js
+      if ecommerce?
+        # Cleared first, as Google asks, so two events on one page cannot
+        # bleed into each other.
+        "window.dataLayer = window.dataLayer || []; " \
+          "window.dataLayer.push({ ecommerce: null }); " \
+          "window.dataLayer.push(#{{ event: name, ecommerce: payload }.to_json});"
+      else
+        "window.dataLayer = window.dataLayer || []; window.dataLayer.push(#{payload.merge(event: name).to_json});"
+      end
+    end
+  end
+end

data/lib/consently/version.rb

@@ -1,3 +1,3 @@
 module Consently
-  VERSION = "0.2.1"
+  VERSION = "1.0.0"
 end

data/lib/consently.rb

@@ -7,6 +7,7 @@ require "consently/version"
 require "consently/script"
 require "consently/cookie"
 require "consently/consent"
+require "consently/event"
 require "consently/providers/base"
 require "consently/providers"
 require "consently/configuration"
@@ -60,6 +61,20 @@ module Consently
       resolve(config.enabled, request)
     end
 
+    # How events reach Google for this request. Google Tag Manager reads
+    # dataLayer pushes; gtag.js only acts on gtag('event', ...) calls, and a
+    # push meant for a container it silently ignores. :auto looks at the tags
+    # in the request's scope: a container present means the dataLayer,
+    # otherwise any Google tag means gtag.
+    def event_transport_for(request = nil)
+      return config.event_transport unless config.event_transport == :auto
+
+      providers = tags_for(request)
+      return :data_layer if providers.any? { |provider| provider.is_a?(Providers::GoogleTagManager) }
+
+      providers.any?(&:google?) ? :gtag : :data_layer
+    end
+
     # Whether this visitor has to be asked. When they do not, every category
     # counts as granted and no banner is rendered - see config.consent_required.
     def consent_required?(request = nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: consently
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Michał Krzysteczko
@@ -58,6 +58,7 @@ files:
 - app/helpers/consently/tags_helper.rb
 - app/javascript/consently/banner_controller.js
 - app/javascript/consently/embed_controller.js
+- app/javascript/consently/events.js
 - app/models/consently/application_record.rb
 - app/models/consently/consent_record.rb
 - app/views/consently/_banner.html.erb
@@ -80,6 +81,7 @@ files:
 - lib/consently/consent.rb
 - lib/consently/cookie.rb
 - lib/consently/engine.rb
+- lib/consently/event.rb
 - lib/consently/providers.rb
 - lib/consently/providers/base.rb
 - lib/consently/providers/clarity.rb
@@ -121,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: GDPR cookie consent for Rails that actually blocks your analytics tags until
   the visitor agrees