consently 0.1.0

data/lib/consently/providers/custom.rb

@@ -0,0 +1,34 @@
+module Consently
+  module Providers
+    # The escape hatch for a vendor Consently does not know about yet. Blocked
+    # and released exactly like a built-in one.
+    #
+    #   c.tag :custom, as: :piwik, category: :analytics,
+    #         src: "https://cdn.example.com/piwik.js"
+    #
+    #   c.tag :custom, as: :whatever, category: :marketing, inline: <<~JS
+    #     console.log("hello");
+    #   JS
+    class Custom < Base
+      self.provider_key = :custom
+      self.default_category = :marketing
+
+      def scripts
+        [ Script.new(src: options[:src], inline: options[:inline], async: options.fetch(:async, true), data: options[:data]) ]
+      end
+
+      def noscript
+        options[:noscript]
+      end
+
+      private
+
+      def validate!
+        if options[:src].blank? && options[:inline].blank?
+          raise MissingOption, "Consently: a :custom tag needs src: or inline:"
+        end
+        raise MissingOption, "Consently: a :custom tag needs as: to name it" if options[:as].blank?
+      end
+    end
+  end
+end

data/lib/consently/providers/google_ads.rb

@@ -0,0 +1,32 @@
+module Consently
+  module Providers
+    class GoogleAds < Base
+      self.provider_key = :google_ads
+      self.default_category = :marketing
+
+      cookie "_gcl_au", days: 90
+
+      def scripts
+        [
+          Script.new(src: "https://www.googletagmanager.com/gtag/js?id=#{id}", async: true),
+          Script.new(inline: <<~JS.strip)
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', '#{id}');
+          JS
+        ]
+      end
+
+      private
+
+      def id
+        @id ||= require_option(:id)
+      end
+
+      def validate!
+        id
+      end
+    end
+  end
+end

data/lib/consently/providers/google_analytics.rb

@@ -0,0 +1,45 @@
+module Consently
+  module Providers
+    # GA4. Pass `anonymize: false` to leave IP anonymisation off; it is on by
+    # default because most European deployments want it.
+    class GoogleAnalytics < Base
+      self.provider_key = :google_analytics
+      self.default_category = :analytics
+
+      # What GA4 leaves behind. The container-scoped one is written per
+      # measurement id, hence the wildcard.
+      cookie "_ga", days: 730
+      cookie "_ga_*", days: 730
+      cookie "_gid", days: 1
+      cookie "_gat", days: nil
+
+      def scripts
+        [
+          Script.new(src: "https://www.googletagmanager.com/gtag/js?id=#{id}", async: true),
+          Script.new(inline: <<~JS.strip)
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', '#{id}'#{config_options});
+          JS
+        ]
+      end
+
+      private
+
+      def id
+        @id ||= require_option(:id)
+      end
+
+      def config_options
+        return "" unless options.fetch(:anonymize, true)
+
+        ", { 'anonymize_ip': true }"
+      end
+
+      def validate!
+        id
+      end
+    end
+  end
+end

data/lib/consently/providers/google_tag_manager.rb

@@ -0,0 +1,34 @@
+module Consently
+  module Providers
+    class GoogleTagManager < Base
+      self.provider_key = :google_tag_manager
+      self.default_category = :analytics
+
+      # 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.
+
+      def scripts
+        [ Script.new(inline: <<~JS.strip) ]
+          (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
+          var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';
+          j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+          })(window,document,'script','dataLayer','#{id}');
+        JS
+      end
+
+      def noscript
+        %(<iframe src="https://www.googletagmanager.com/ns.html?id=#{id}" height="0" width="0" style="display:none;visibility:hidden"></iframe>)
+      end
+
+      private
+
+      def id
+        @id ||= require_option(:id)
+      end
+
+      def validate!
+        id
+      end
+    end
+  end
+end

data/lib/consently/providers/hotjar.rb

@@ -0,0 +1,39 @@
+module Consently
+  module Providers
+    class Hotjar < Base
+      self.provider_key = :hotjar
+      self.default_category = :analytics
+
+      cookie "_hjSessionUser_*", days: 365
+      cookie "_hjSession_*", days: nil
+
+      def scripts
+        [ Script.new(inline: <<~JS.strip) ]
+          (function(h,o,t,j,a,r){h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
+          h._hjSettings={hjid:#{id},hjsv:#{version}};a=o.getElementsByTagName('head')[0];
+          r=o.createElement('script');r.async=1;r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
+          a.appendChild(r);})(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
+        JS
+      end
+
+      private
+
+      # Numeric on purpose: the snippet uses the id unquoted.
+      def id
+        @id ||= Integer(require_option(:id))
+      rescue ArgumentError
+        raise MissingOption, "Consently: hotjar id: must be a number"
+      end
+
+      # Hotjar's snippet version, not the site id; it has been 6 for years.
+      def version
+        Integer(options.fetch(:snippet_version, 6))
+      end
+
+      def validate!
+        id
+        version
+      end
+    end
+  end
+end

data/lib/consently/providers/meta_pixel.rb

@@ -0,0 +1,37 @@
+module Consently
+  module Providers
+    class MetaPixel < Base
+      self.provider_key = :meta_pixel
+      self.default_category = :marketing
+
+      cookie "_fbp", days: 90
+      cookie "fr", days: 90
+
+      def scripts
+        [ Script.new(inline: <<~JS.strip) ]
+          !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+          n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
+          n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
+          t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
+          document,'script','https://connect.facebook.net/en_US/fbevents.js');
+          fbq('init', '#{id}');
+          fbq('track', 'PageView');
+        JS
+      end
+
+      def noscript
+        %(<img height="1" width="1" style="display:none" alt="" src="https://www.facebook.com/tr?id=#{id}&ev=PageView&noscript=1">)
+      end
+
+      private
+
+      def id
+        @id ||= require_option(:id)
+      end
+
+      def validate!
+        id
+      end
+    end
+  end
+end

data/lib/consently/providers/plausible.rb

@@ -0,0 +1,30 @@
+module Consently
+  module Providers
+    # Cookieless, and often run without a banner at all - but whether that is
+    # allowed is a legal call, not ours, so it waits for consent like any
+    # other analytics tag. Move it with category: :necessary if your legal
+    # advice says it may run right away.
+    class Plausible < Base
+      self.provider_key = :plausible
+      self.default_category = :analytics
+
+      def scripts
+        [ Script.new(src: "#{host}/js/script.js", defer: true, data: { "domain" => domain }) ]
+      end
+
+      private
+
+      def domain
+        @domain ||= require_option(:domain)
+      end
+
+      def host
+        @host ||= options.fetch(:host, "https://plausible.io").to_s.chomp("/")
+      end
+
+      def validate!
+        domain
+      end
+    end
+  end
+end

data/lib/consently/providers.rb

@@ -0,0 +1,9 @@
+require "consently/providers/base"
+require "consently/providers/google_tag_manager"
+require "consently/providers/google_analytics"
+require "consently/providers/google_ads"
+require "consently/providers/clarity"
+require "consently/providers/meta_pixel"
+require "consently/providers/hotjar"
+require "consently/providers/plausible"
+require "consently/providers/custom"

data/lib/consently/script.rb

@@ -0,0 +1,17 @@
+module Consently
+  # One <script> a provider wants on the page - either an external file or an
+  # inline body. Keeping it as data rather than as HTML is what lets the view
+  # render the very same script either live or blocked, without the provider
+  # knowing which of the two happened.
+  Script = Struct.new(:src, :inline, :async, :defer, :data, keyword_init: true) do
+    def external?
+      src.present?
+    end
+
+    # Extra data-* attributes some vendors configure the tag with, e.g.
+    # Plausible's data-domain.
+    def data_attributes
+      data || {}
+    end
+  end
+end

data/lib/consently/version.rb

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

data/lib/consently.rb

@@ -0,0 +1,74 @@
+require "json"
+require "active_support"
+require "active_support/core_ext/object/blank"
+
+require "consently/version"
+require "consently/script"
+require "consently/cookie"
+require "consently/consent"
+require "consently/providers/base"
+require "consently/providers"
+require "consently/configuration"
+require "consently/engine" if defined?(Rails::Engine)
+
+# Tag snippets and cookie consent in one place.
+#
+# Everything the host application needs goes through `Consently.configure`;
+# the views ask this module what to render for the current request.
+module Consently
+  class Error < StandardError; end
+
+  # A provider key that was never registered - almost always a typo in the
+  # initializer, so the message lists what is available.
+  class UnknownProvider < Error
+    def initialize(key)
+      super("Unknown Consently provider #{key.inspect}. Available: #{Providers::Base.registry.keys.sort.join(", ")}")
+    end
+  end
+
+  class MissingOption < Error; end
+
+  class << self
+    def configure
+      yield config
+      config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Mostly for tests and for reloading an initializer in development.
+    def reset!
+      @config = Configuration.new
+    end
+
+    # Tags configured for this request: the defaults, plus whatever the
+    # matching scope adds or overrides.
+    def tags_for(request = nil)
+      config.tags_for(scope_for(request))
+    end
+
+    def scope_for(request)
+      return nil unless config.scope_resolver && request
+
+      config.scope_resolver.call(request)
+    end
+
+    def enabled?(request = nil)
+      resolve(config.enabled, request)
+    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)
+      resolve(config.consent_required, request)
+    end
+
+    private
+
+    def resolve(setting, request)
+      setting.respond_to?(:call) ? !!setting.call(request) : !!setting
+    end
+  end
+end

data/lib/generators/consently/consent_log/consent_log_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Consently
+  module Generators
+    class ConsentLogGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds the table behind Consently::ConsentRecord, for proof of consent."
+
+      def create_migration_file
+        migration_template "create_consently_consent_records.rb", "db/migrate/create_consently_consent_records.rb"
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          Next:
+            1. rails db:migrate
+            2. mount Consently::Engine => "/consently"   # config/routes.rb
+            3. c.log_consents = true                     # config/initializers/consently.rb
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/consently/consent_log/templates/create_consently_consent_records.rb

@@ -0,0 +1,19 @@
+class CreateConsentlyConsentRecords < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :consently_consent_records do |t|
+      t.string :categories, null: false, default: ""
+      t.string :consent_version, null: false
+      t.string :subject
+      t.string :scope
+      t.string :user_agent
+      # A salted digest rather than the address itself: enough to tell two
+      # decisions apart, not enough to identify anyone.
+      t.string :ip_hash
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :consently_consent_records, :created_at
+    add_index :consently_consent_records, :consent_version
+  end
+end

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

@@ -0,0 +1,44 @@
+require "rails/generators/base"
+
+module Consently
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the Consently initializer and wires the banner controller up."
+
+      def create_initializer
+        template "consently.rb", "config/initializers/consently.rb"
+      end
+
+      # Stimulus is how the banner releases the blocked tags, so registering
+      # the controller is part of installing, not a step in a README nobody
+      # reads.
+      def register_stimulus_controller
+        index = "app/javascript/controllers/index.js"
+        return say_status :skip, "#{index} not found - register consently-banner yourself", :yellow unless File.exist?(index)
+
+        append_to_file index, <<~JS
+
+          import ConsentlyBannerController from "consently/banner_controller"
+          application.register("consently-banner", ConsentlyBannerController)
+        JS
+      end
+
+      def show_readme
+        say <<~TEXT
+
+          Consently is installed. One thing left - put the helpers in your layout:
+
+            <head>  <%= consently_tags %>
+            <body>  <%= consently_noscript_tags %> ... <%= consently_banner %>
+
+          The banner brings its own CSS; restyle it with the custom properties
+          on .consently, or run `rails g consently:views` to take the markup over.
+
+          Consent logging (optional): rails g consently:consent_log
+        TEXT
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+Consently.configure do |c|
+  # Where the tags run. Anything callable gets the request.
+  c.enabled = ->(request) { Rails.env.production? }
+
+  # Bump when your cookie policy changes: older consents stop counting and
+  # the banner asks again.
+  c.consent_version = 1
+
+  # Link shown in the banner. A callable receives the view context, which is
+  # what you want when the URL is locale dependent.
+  # c.policy_url = -> (view) { view.main_app.cookie_policy_path }
+
+  # Reload the page once a choice is made. Off by default: the tags start
+  # running in place, so there is nothing to reload for. Turn it on if the
+  # page renders differently depending on consent.
+  # c.reload_after_choice = true
+
+  # Whether this visitor has to be asked at all. Return false and nothing is
+  # held back and no banner is shown - for traffic outside the EU, if your
+  # legal advice says so.
+  # c.consent_required = ->(request) { EU.include?(request.headers["CF-IPCountry"]) }
+
+  # Global Privacy Control (binding in California and Colorado) counts as a
+  # rejection and is honoured by default. Do Not Track is advisory, so it is
+  # 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
+
+  # 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:
+  #   mount Consently::Engine => "/consently"
+  # c.log_consents = true
+  #
+  # The log is anonymous unless you say who made the decision:
+  # c.consent_subject = ->(request) { request.env["warden"]&.user&.id }
+
+  # A category of your own, on top of :necessary, :analytics and :marketing.
+  # c.category :personalization
+
+  # Your tags. Each one waits for its category unless that category is
+  # :necessary.
+  # c.tag :google_tag_manager, id: "GTM-XXXXXXX"
+  # c.tag :google_analytics,   id: "G-XXXXXXXXXX"
+  # c.tag :clarity,            id: "xxxxxxxxxx"
+  # c.tag :meta_pixel,         id: "000000000000000"
+  # c.tag :hotjar,             id: 1234567
+  # c.tag :plausible,          domain: "example.com"
+  #
+  # Anything else:
+  # c.tag :custom, as: :piwik, category: :analytics, src: "https://cdn.example.com/piwik.js"
+
+  # Different tags per domain, tenant or shop. Whatever the resolver returns
+  # is matched against the scope names below; scopes inherit the tags above
+  # and may override them by declaring the same provider again.
+  # c.scope_resolver = ->(request) { request.host }
+  #
+  # c.scope "example.com" do |s|
+  #   s.tag :google_analytics, id: "G-EXAMPLE"
+  # end
+end

data/lib/generators/consently/views/views_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators/base"
+
+module Consently
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../app/views/consently", __dir__)
+
+      desc "Copies the banner markup into your app so you can restyle it."
+
+      def copy_views
+        directory ".", "app/views/consently"
+      end
+    end
+  end
+end

data/lib/tasks/consently_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :consently do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: consently
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michał Krzysteczko
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Most Rails cookie banners ask for consent and then load Google Analytics
+  anyway. Consently is the other half: declare your tags once - GA4, Google Tag Manager,
+  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.'
+email:
+- m.krzysteczko@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/consently.css
+- app/controllers/consently/application_controller.rb
+- app/controllers/consently/consents_controller.rb
+- app/helpers/consently/application_helper.rb
+- app/helpers/consently/tags_helper.rb
+- app/javascript/consently/banner_controller.js
+- app/models/consently/application_record.rb
+- app/models/consently/consent_record.rb
+- app/views/consently/_banner.html.erb
+- app/views/consently/_policy.html.erb
+- config/importmap.rb
+- config/locales/cs.yml
+- config/locales/de.yml
+- config/locales/en.yml
+- config/locales/es.yml
+- config/locales/fr.yml
+- config/locales/hu.yml
+- config/locales/it.yml
+- config/locales/nl.yml
+- config/locales/pl.yml
+- config/locales/sk.yml
+- config/routes.rb
+- lib/consently.rb
+- lib/consently/configuration.rb
+- lib/consently/consent.rb
+- lib/consently/cookie.rb
+- lib/consently/engine.rb
+- lib/consently/providers.rb
+- lib/consently/providers/base.rb
+- lib/consently/providers/clarity.rb
+- lib/consently/providers/custom.rb
+- lib/consently/providers/google_ads.rb
+- lib/consently/providers/google_analytics.rb
+- lib/consently/providers/google_tag_manager.rb
+- lib/consently/providers/hotjar.rb
+- lib/consently/providers/meta_pixel.rb
+- lib/consently/providers/plausible.rb
+- lib/consently/script.rb
+- lib/consently/version.rb
+- lib/generators/consently/consent_log/consent_log_generator.rb
+- lib/generators/consently/consent_log/templates/create_consently_consent_records.rb
+- lib/generators/consently/install/install_generator.rb
+- lib/generators/consently/install/templates/consently.rb
+- lib/generators/consently/views/views_generator.rb
+- lib/tasks/consently_tasks.rake
+homepage: https://github.com/Xeross99/consently
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Xeross99/consently
+  bug_tracker_uri: https://github.com/Xeross99/consently/issues
+  changelog_uri: https://github.com/Xeross99/consently/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: GDPR cookie consent for Rails that actually blocks your analytics tags until
+  the visitor agrees
+test_files: []