consently 0.1.0

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 (2026-08-12)
+
+First release.
+
+- Tag registry: Google Tag Manager, GA4, Google Ads, Microsoft Clarity, Meta
+  Pixel, Hotjar, Plausible, and `:custom` for anything else.
+- Non-essential tags render as inert `<script type="text/plain">` whose source
+  the browser never fetches, and become live scripts on consent without a
+  reload.
+- Google Consent Mode v2: denied by default before any Google tag, updated the
+  moment the visitor chooses.
+- Banner and preferences panel in plain CSS - no Tailwind, no build step -
+  themed through custom properties, driven by one Stimulus controller, and
+  translated into ten languages.
+- `consently_policy` generates the cookie policy from the same configuration:
+  categories, vendors, the cookies each one sets and how long they last.
+- Per-domain or per-tenant tag sets from a single initializer.
+- Optional consent log in your own database, anonymous unless you name the
+  subject yourself.
+- Global Privacy Control honoured by default, Do Not Track opt-in, and
+  `consent_required` for deciding who has to be asked at all.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,279 @@
+# Consently
+
+**GDPR cookie consent for Rails that actually blocks your tags.**
+
+Most banners ask for consent and load Google Analytics anyway. Consently is
+the other half. Declare your tags once; every non-essential one is rendered as
+an inert `<script type="text/plain">` the browser will not even fetch, and
+becomes a live script the instant the visitor agrees - no page reload, no lost
+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 |
+| **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 |
+
+```ruby
+# config/initializers/consently.rb
+Consently.configure do |c|
+  c.tag :google_tag_manager, id: "GTM-XXXXXXX"
+  c.tag :google_analytics,   id: "G-XXXXXXXXXX"
+  c.tag :clarity,            id: "abcd1234"
+  c.tag :meta_pixel,         id: "123456789012345"
+end
+```
+
+```erb
+<head>
+  <%= consently_tags %>
+</head>
+<body>
+  <%= consently_noscript_tags %>
+  ...
+  <%= consently_banner %>
+</body>
+```
+
+That is the whole integration.
+
+## Install
+
+```ruby
+gem "consently"
+```
+
+```bash
+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.
+
+## What is a tag
+
+| Provider | Key | Default category |
+| --- | --- | --- |
+| Google Tag Manager | `:google_tag_manager` | `analytics` |
+| Google Analytics 4 | `:google_analytics` | `analytics` |
+| Google Ads | `:google_ads` | `marketing` |
+| Microsoft Clarity | `:clarity` | `analytics` |
+| Meta Pixel | `:meta_pixel` | `marketing` |
+| Hotjar | `:hotjar` | `analytics` |
+| Plausible | `:plausible` | `analytics` (move to `necessary` if you run it without a banner) |
+| anything else | `:custom` | `marketing` |
+
+Every tag takes `category:` to move it, and `:custom` covers vendors Consently
+does not know yet:
+
+```ruby
+c.tag :custom, as: :piwik, category: :analytics, src: "https://cdn.example.com/piwik.js"
+c.tag :custom, as: :inline_thing, category: :marketing, inline: "console.log('hi')"
+```
+
+## Consent
+
+Three categories out of the box - `necessary`, `analytics`, `marketing` - and
+you can add your own:
+
+```ruby
+c.category :personalization
+```
+
+`necessary` never waits for a click. Everything else is blocked until the
+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.
+
+## Per-domain, per-tenant
+
+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"
+end
+
+c.scope "pixelpicture.eu" do |s|
+  s.tag :google_analytics, id: "G-PIXEL"
+end
+```
+
+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.
+
+## Proof of consent
+
+```bash
+rails g consently:consent_log
+rails db:migrate
+```
+
+```ruby
+# config/routes.rb
+mount Consently::Engine => "/consently"
+
+# config/initializers/consently.rb
+c.log_consents = true
+```
+
+Each decision is then stored as a `Consently::ConsentRecord`: the categories,
+the policy version, the scope, the user agent, and a salted digest of the IP -
+enough to show a decision was made, not enough to identify anyone.
+
+The cookie is still what decides which tags run; the table is only the proof,
+since a visitor can clear their cookies and a log that lives in their browser
+proves nothing. Nobody is named unless you say who they are:
+
+```ruby
+c.consent_subject = -> (request) { request.env["warden"]&.user&.id }
+```
+
+## After a choice
+
+Nothing reloads: the tags the visitor just agreed to start running in place,
+and the page keeps its scroll position and its state. If your page renders
+something the server decides from consent - an embedded map, a video, a
+status panel - ask for a reload instead:
+
+```ruby
+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:
+
+```js
+document.addEventListener("consently:change", ({ detail }) => {
+  console.log(detail.categories) // ["analytics"]
+})
+```
+
+## Who gets asked
+
+Everyone, by default. If your legal advice says visitors outside the EU do not
+need asking, say who does:
+
+```ruby
+c.consent_required = -> (request) { EU_COUNTRIES.include?(request.headers["CF-IPCountry"]) }
+```
+
+For anyone that returns false there is no banner, and every category counts as
+granted.
+
+Opt-out signals are answers, so those visitors are never asked either. Global
+Privacy Control - binding in California and Colorado - is honoured out of the
+box. Do Not Track is advisory, so it is opt-in:
+
+```ruby
+c.respect_do_not_track = true
+```
+
+## Accessibility
+
+The card is a non-modal `role="dialog"` labelled by its own text, the settings
+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
+
+```erb
+<%= consently_data_layer_push("purchase", value: 120, currency: "EUR") %>
+```
+
+Renders nothing when analytics consent is missing.
+
+## Styling
+
+The banner ships as plain CSS scoped under `.consently`, driven by custom
+properties. Most restyling is a few variables in your own stylesheet:
+
+```css
+.consently {
+  --consently-accent: #4f46e5;
+  --consently-accent-text: #ffffff;
+  --consently-radius: 0;
+  --consently-max-width: 28rem;
+}
+```
+
+Want the markup instead? Take the partial over, and turn the gem's stylesheet
+off so it stops loading:
+
+```bash
+rails g consently:views
+```
+
+```ruby
+c.stylesheet = false
+```
+
+Translations live under the `consently.*` keys; your own locale files win over
+the gem's, so overriding one string means writing that one key.
+
+## Turbo
+
+The banner is `data-turbo-permanent`, so it survives Turbo Drive navigation
+and morphed refreshes. Tags blocked at first render stay blocked across
+visits until consent is given, and are rendered live from the server on the
+next request after that.
+
+## Try it
+
+```bash
+bin/rails server
+```
+
+http://localhost:3000 runs the dummy application: four tags configured, a live
+list of what is blocked and what is running, the cookie as it stands, the
+logged decisions and every translation to click through.
+
+## Cheat sheet
+
+Helpers:
+
+| | |
+| --- | --- |
+| `consently_tags` | `<head>`: the stylesheet, consent mode defaults, and every tag (blocked or live) |
+| `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_data_layer_push(event, **payload)` | a dataLayer event, rendered only with analytics consent |
+| `consently_consent` | the current `Consently::Consent`; `granted?(:analytics)` in your own views |
+
+Configuration:
+
+| | |
+| --- | --- |
+| `c.tag key, **options` | `id:`, `domain:`, `category:`, `as:` (name it, for two of a kind) |
+| `c.scope(name) { \|s\| ... }` | tags for one tenant; `c.scope_resolver` decides which one a request is |
+| `c.category :name` | a category of your own beside `necessary`, `analytics`, `marketing` |
+| `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.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.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.
+
+## Licence
+
+MIT.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/consently.css

@@ -0,0 +1,252 @@
+/*
+ * The banner's own styles. Plain CSS on purpose: a gem that only works if the
+ * host application runs Tailwind is half a gem.
+ *
+ * Everything is scoped under .consently and driven by custom properties, so
+ * restyling means overriding a handful of variables rather than forking the
+ * markup:
+ *
+ *   .consently { --consently-accent: #4f46e5; --consently-radius: 0; }
+ */
+
+.consently {
+  --consently-background: #ffffff;
+  --consently-text: #111827;
+  --consently-muted: #4b5563;
+  --consently-accent: #111827;
+  --consently-accent-text: #ffffff;
+  --consently-border: rgba(17, 24, 39, 0.1);
+  --consently-radius: 0.75rem;
+  --consently-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  --consently-max-width: 36rem;
+
+  position: fixed;
+  inset-inline: 0;
+  bottom: 0;
+  z-index: 50;
+  padding: 0 1.5rem 1.5rem;
+  /* The strip itself must not swallow clicks meant for the page behind it. */
+  pointer-events: none;
+}
+
+.consently__card {
+  pointer-events: auto;
+  box-sizing: border-box;
+  margin-inline-start: auto;
+  max-width: var(--consently-max-width);
+  padding: 1.5rem;
+  border-radius: var(--consently-radius);
+  background: var(--consently-background);
+  color: var(--consently-text);
+  box-shadow: var(--consently-shadow);
+  outline: 1px solid var(--consently-border);
+}
+
+.consently__text {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+}
+
+.consently__link {
+  color: inherit;
+  font-weight: 600;
+}
+
+/* Collapsed to a zero-height grid row rather than display:none, which cannot
+   be animated. The inner wrapper does the clipping. */
+.consently__panel {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 0.2s ease-out;
+}
+
+.consently__panel--open {
+  grid-template-rows: 1fr;
+}
+
+.consently__panel-inner {
+  overflow: hidden;
+}
+
+.consently__options {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding-top: 1rem;
+}
+
+.consently__option {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+}
+
+.consently__option input {
+  margin: 0.3rem 0 0;
+  width: 1rem;
+  height: 1rem;
+  accent-color: var(--consently-accent);
+}
+
+.consently__option-name {
+  display: block;
+  font-weight: 600;
+}
+
+.consently__option-description {
+  display: block;
+  color: var(--consently-muted);
+}
+
+.consently__actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem 1.25rem;
+  margin-top: 1rem;
+}
+
+.consently__button {
+  font: inherit;
+  font-size: 0.875rem;
+  font-weight: 600;
+  line-height: 1.5rem;
+  color: var(--consently-text);
+  background: none;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+}
+
+.consently__button:hover {
+  opacity: 0.75;
+}
+
+.consently__button--primary {
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.375rem;
+  color: var(--consently-accent-text);
+  background: var(--consently-accent);
+}
+
+.consently__button--quiet {
+  color: var(--consently-muted);
+}
+
+.consently__button:focus-visible,
+.consently__link:focus-visible {
+  outline: 2px solid var(--consently-accent);
+  outline-offset: 2px;
+}
+
+.consently-hidden {
+  display: none !important;
+}
+
+/* The generated cookie policy. Deliberately quiet: it lands inside someone
+   else's page and should inherit its typography. */
+.consently-policy {
+  --consently-policy-muted: #4b5563;
+  --consently-policy-border: rgba(17, 24, 39, 0.1);
+}
+
+.consently-policy__category {
+  margin-top: 2.5rem;
+}
+
+.consently-policy__heading {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.consently-policy__title {
+  margin: 0;
+  font-size: 1.125rem;
+  font-weight: 600;
+}
+
+.consently-policy__status {
+  flex: none;
+  padding: 0.125rem 0.5rem;
+  border-radius: 999px;
+  background: rgba(17, 24, 39, 0.06);
+  color: var(--consently-policy-muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.consently-policy__status--granted {
+  background: rgba(22, 163, 74, 0.12);
+  color: #15803d;
+}
+
+.consently-policy__description,
+.consently-policy__empty {
+  margin: 0.25rem 0 0;
+  color: var(--consently-policy-muted);
+  font-size: 0.875rem;
+}
+
+.consently-policy__vendor {
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--consently-policy-border);
+}
+
+.consently-policy__vendor-name {
+  margin: 0;
+  font-weight: 600;
+}
+
+.consently-policy__vendor-id {
+  margin-inline-start: 0.5rem;
+  color: var(--consently-policy-muted);
+  font-weight: 400;
+  font-size: 0.875rem;
+}
+
+.consently-policy__table {
+  width: 100%;
+  margin-top: 0.5rem;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+  text-align: start;
+}
+
+.consently-policy__table th {
+  padding: 0.25rem 0.75rem 0.25rem 0;
+  color: var(--consently-policy-muted);
+  font-weight: 500;
+  text-align: start;
+}
+
+.consently-policy__table td {
+  padding: 0.25rem 0.75rem 0.25rem 0;
+  vertical-align: top;
+}
+
+.consently-policy__footer {
+  margin-top: 2rem;
+  font-size: 0.875rem;
+}
+
+@media (max-width: 40rem) {
+  .consently {
+    padding: 0 1rem 1rem;
+  }
+
+  .consently__card {
+    max-width: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .consently__panel {
+    transition: none;
+  }
+}

data/app/controllers/consently/application_controller.rb

@@ -0,0 +1,4 @@
+module Consently
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/consently/consents_controller.rb

@@ -0,0 +1,44 @@
+require "digest"
+
+module Consently
+  # Records what the visitor agreed to, when, and against which policy
+  # version - the proof the GDPR asks for. The cookie remains the source of
+  # truth for what runs; this is bookkeeping.
+  class ConsentsController < ApplicationController
+    def create
+      ConsentRecord.create!(
+        categories: Array(params[:categories]).map(&:to_s).join(","),
+        consent_version: params[:version].to_s,
+        scope: Consently.scope_for(request).to_s.presence,
+        subject: consent_subject,
+        user_agent: request.user_agent.to_s.first(255),
+        ip_hash: hashed_ip
+      )
+
+      head :no_content
+    rescue ActiveRecord::StatementInvalid => error
+      # Almost always the migration from `rails g consently:consent_log` not
+      # having been run. The visitor's choice already took effect in their
+      # browser, so this stays quiet and only complains in the log.
+      Rails.logger.warn("[consently] could not record consent: #{error.message}")
+      head :no_content
+    end
+
+    private
+
+    # Nil unless the host application says who this is - a public site logs
+    # decisions, not people.
+    def consent_subject
+      resolver = Consently.config.consent_subject
+      return nil unless resolver
+
+      resolver.call(request).to_s.presence
+    end
+
+    # An IP address identifies a person; a salted digest of one still tells us
+    # two records came from the same visitor without storing who they are.
+    def hashed_ip
+      Digest::SHA256.hexdigest("consently-#{Rails.application.secret_key_base}-#{request.remote_ip}")
+    end
+  end
+end

data/app/helpers/consently/application_helper.rb

@@ -0,0 +1,4 @@
+module Consently
+  module ApplicationHelper
+  end
+end