omnitrack-rb 0.1.0

data/lib/omnitrack/adapters/google_ads.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Adapters
+    # Google Ads Conversion Tracking via the Google Ads API (REST).
+    #
+    # Required config keys:
+    #   customer_id      — Google Ads customer ID (without dashes), e.g. "1234567890"
+    #   developer_token  — developer token from Google Ads API Center
+    #   access_token     — OAuth2 access token (refresh externally or via oauth2 gem)
+    #
+    # Optional config keys:
+    #   conversion_action_id — default conversion action ID
+    #   login_customer_id    — MCC (manager account) customer ID, if applicable
+    #   api_version          — default "v15"
+    #
+    # Example config:
+    #   google_ads: {
+    #     enabled:             true,
+    #     customer_id:         ENV["GOOGLE_ADS_CUSTOMER_ID"],
+    #     developer_token:     ENV["GOOGLE_ADS_DEVELOPER_TOKEN"],
+    #     access_token:        ENV["GOOGLE_ADS_ACCESS_TOKEN"],
+    #     conversion_action_id: ENV["GOOGLE_ADS_CONVERSION_ACTION_ID"]
+    #   }
+    #
+    class GoogleAds < Base
+      self.adapter_name = :google_ads
+
+      API_VERSION   = "v15"
+      API_BASE      = "https://googleads.googleapis.com"
+
+      # -------------------------------------------------------------------
+      # Interface implementation
+      # -------------------------------------------------------------------
+
+      # Track a named event.
+      # Maps to a Google Ads click conversion upload.
+      #
+      # @param event_name [String]  e.g. "purchase", "lead"
+      # @param payload    [Hash]
+      #   :gclid             — Google Click ID (required for click conversion)
+      #   :conversion_value  — monetary value
+      #   :currency_code     — ISO 4217, e.g. "USD"
+      #   :order_id          — deduplication key
+      #   :conversion_time   — ISO 8601 string (defaults to now)
+      #   :__context__       — injected by Controller concern
+      def track_event(event_name, payload = {})
+        safe_execute(event_name) do
+          gclid       = extract_gclid(payload)
+          action_id   = payload[:conversion_action_id] || config[:conversion_action_id]
+
+          body = build_conversion_body(
+            gclid:             gclid,
+            conversion_action: action_resource(action_id),
+            conversion_time:   payload[:conversion_time] || iso_now,
+            conversion_value:  payload[:conversion_value],
+            currency_code:     payload[:currency_code] || "USD",
+            order_id:          payload[:order_id]
+          )
+
+          response = http_post(upload_url, body: body, headers: auth_headers)
+          Omnitrack::Result.success(
+            adapter: name,
+            data:    parse_response(response)
+          )
+        end
+      end
+
+      # Track a conversion (alias with sensible defaults for purchase events)
+      def track_conversion(data = {})
+        track_event("conversion", data)
+      end
+
+      # Google Ads does not have a standalone identify endpoint;
+      # enhanced conversions use hashed PII attached to the conversion upload.
+      # This method stores user data on the context for later use.
+      def identify_user(user_data = {})
+        ctx = Omnitrack::Context.current
+        ctx&.merge!(omnitrack_user: normalize_user(user_data))
+
+        Omnitrack::Result.success(
+          adapter:  name,
+          metadata: { note: "User data stored in context for enhanced conversions" }
+        )
+      end
+
+      private
+
+      # -------------------------------------------------------------------
+      # Config validation
+      # -------------------------------------------------------------------
+
+      def validate_config
+        require_config!(:customer_id,     hint: "Your Google Ads account ID (no dashes)")
+        require_config!(:developer_token,  hint: "From the Google Ads API Center")
+        require_config!(:access_token,     hint: "OAuth2 access token")
+      end
+
+      # -------------------------------------------------------------------
+      # Request building
+      # -------------------------------------------------------------------
+
+      def upload_url
+        version = config[:api_version] || API_VERSION
+        cid     = config[:customer_id].to_s.tr("-", "")
+        "#{API_BASE}/#{version}/customers/#{cid}:uploadClickConversions"
+      end
+
+      def action_resource(action_id)
+        cid = config[:customer_id].to_s.tr("-", "")
+        "customers/#{cid}/conversionActions/#{action_id}"
+      end
+
+      def build_conversion_body(gclid:, conversion_action:, conversion_time:,
+                                conversion_value: nil, currency_code: "USD",
+                                order_id: nil)
+        click_conversion = {
+          gclid:             gclid,
+          conversion_action: conversion_action,
+          conversion_date_time: conversion_time
+        }
+        click_conversion[:conversion_value] = conversion_value.to_f if conversion_value
+        click_conversion[:currency_code]    = currency_code          if currency_code
+        click_conversion[:order_id]         = order_id.to_s          if order_id
+
+        { conversions: [click_conversion], partial_failure: true }
+      end
+
+      def auth_headers
+        headers = {
+          "Authorization"         => "Bearer #{config[:access_token]}",
+          "developer-token"       => config[:developer_token]
+        }
+        if config[:login_customer_id]
+          headers["login-customer-id"] = config[:login_customer_id].to_s
+        end
+        headers
+      end
+
+      # -------------------------------------------------------------------
+      # Helpers
+      # -------------------------------------------------------------------
+
+      def extract_gclid(payload)
+        payload[:gclid] ||
+          payload.dig(:__context__, :click_ids, :gclid) ||
+          Omnitrack::Context.current&.gclid
+      end
+
+      def normalize_user(user_data)
+        {
+          hashed_email:        sha256(user_data[:email]),
+          hashed_phone_number: sha256(user_data[:phone]),
+          address: {
+            hashed_first_name: sha256(user_data[:first_name]),
+            hashed_last_name:  sha256(user_data[:last_name])
+          }.compact
+        }.compact
+      end
+
+      def parse_response(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        { raw: response.body }
+      end
+
+      def iso_now
+        Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S%z")
+      end
+    end
+  end
+end

data/lib/omnitrack/adapters/google_analytics.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Adapters
+    # Google Analytics 4 — Measurement Protocol (server-side).
+    #
+    # Required config:
+    #   measurement_id   — e.g. "G-XXXXXXXXXX"
+    #   api_secret       — Measurement Protocol API secret (from GA4 admin)
+    #
+    # Optional config:
+    #   debug_mode       — when true, uses the /debug/mp/collect endpoint
+    #
+    class GoogleAnalytics < Base
+      self.adapter_name = :google_analytics
+
+      MP_ENDPOINT       = "https://www.google-analytics.com/mp/collect"
+      MP_DEBUG_ENDPOINT = "https://www.google-analytics.com/debug/mp/collect"
+
+      def track_event(event_name, payload = {})
+        safe_execute(event_name) do
+          body = build_event_body(event_name, payload)
+          response = http_post(endpoint_url, body: body)
+          Omnitrack::Result.success(adapter: name, data: { sent: body })
+        end
+      end
+
+      def track_conversion(data = {})
+        track_event(data.fetch(:event_name, "conversion"), data)
+      end
+
+      def identify_user(user_data = {})
+        # GA4 uses client_id / user_id rather than a separate identify call
+        ctx = Omnitrack::Context.current
+        ctx&.merge!(ga_user_id: user_data[:external_id] || user_data[:email])
+
+        Omnitrack::Result.success(
+          adapter:  name,
+          metadata: { note: "GA4 user_id stored in context" }
+        )
+      end
+
+      private
+
+      def validate_config
+        require_config!(:measurement_id, hint: "e.g. G-XXXXXXXXXX")
+        require_config!(:api_secret,     hint: "Measurement Protocol API secret from GA4 admin")
+      end
+
+      def endpoint_url
+        base = config[:debug_mode] ? MP_DEBUG_ENDPOINT : MP_ENDPOINT
+        "#{base}?measurement_id=#{config[:measurement_id]}&api_secret=#{config[:api_secret]}"
+      end
+
+      def build_event_body(event_name, payload)
+        ctx = Omnitrack::Context.current
+
+        # GA4 requires a client_id; fall back to a pseudo-anonymous one
+        client_id = payload[:client_id] ||
+                    ctx&.cookies&.dig("_ga")&.then { |ga| parse_ga_cookie(ga) } ||
+                    SecureRandom.uuid
+
+        event_params = payload
+                       .reject { |k, _| k.to_s.start_with?("__") }
+                       .transform_keys(&:to_s)
+
+        body = {
+          client_id: client_id,
+          events: [
+            {
+              name:   sanitize_event_name(event_name),
+              params: event_params
+            }
+          ]
+        }
+
+        # Attach user_id if present in context
+        if (uid = ctx&.custom_data&.dig(:ga_user_id))
+          body[:user_id] = uid.to_s
+        end
+
+        body
+      end
+
+      def sanitize_event_name(name)
+        # GA4 event names: alphanumeric + underscore, max 40 chars
+        name.to_s.downcase.gsub(/[^a-z0-9_]/, "_")[0, 40]
+      end
+
+      def parse_ga_cookie(cookie_value)
+        # _ga cookie format: GA1.2.XXXXXXXXXX.XXXXXXXXXX
+        parts = cookie_value.to_s.split(".")
+        parts.length >= 4 ? "#{parts[2]}.#{parts[3]}" : cookie_value
+      end
+    end
+  end
+end

data/lib/omnitrack/adapters/meta.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Adapters
+    # Meta Conversions API (server-side events).
+    # Docs: https://developers.facebook.com/docs/marketing-api/conversions-api
+    #
+    # Required config:
+    #   pixel_id      — Meta Pixel ID
+    #   access_token  — System User access token
+    #
+    # Optional config:
+    #   test_event_code — for use with the Test Events tool in Events Manager
+    #   api_version     — default "v18.0"
+    #
+    class Meta < Base
+      self.adapter_name = :meta
+
+      API_BASE    = "https://graph.facebook.com"
+      API_VERSION = "v18.0"
+
+      # Standard Meta event names — used for validation/mapping
+      STANDARD_EVENTS = %w[
+        Purchase Lead CompleteRegistration AddToCart ViewContent
+        Search InitiateCheckout AddPaymentInfo Subscribe
+        Contact CustomizeProduct Donate FindLocation Schedule
+        StartTrial SubmitApplication
+      ].freeze
+
+      def track_event(event_name, payload = {})
+        safe_execute(event_name) do
+          body     = build_event_body(event_name, payload)
+          response = http_post(endpoint_url, body: body)
+          result   = JSON.parse(response.body)
+
+          Omnitrack::Result.success(adapter: name, data: result)
+        end
+      end
+
+      def track_conversion(data = {})
+        # Map to "Purchase" standard event by default
+        track_event("Purchase", data)
+      end
+
+      def identify_user(user_data = {})
+        # Store normalised PII; will be sent with next track_event call
+        ctx = Omnitrack::Context.current
+        ctx&.merge!(meta_user_data: normalize_user(user_data))
+
+        Omnitrack::Result.success(
+          adapter:  name,
+          metadata: { note: "Meta user data stored in context" }
+        )
+      end
+
+      private
+
+      def validate_config
+        require_config!(:pixel_id,     hint: "Your Meta Pixel ID")
+        require_config!(:access_token, hint: "System User access token from Meta Business")
+      end
+
+      def endpoint_url
+        version = config[:api_version] || API_VERSION
+        "#{API_BASE}/#{version}/#{config[:pixel_id]}/events?access_token=#{config[:access_token]}"
+      end
+
+      def build_event_body(event_name, payload)
+        ctx      = Omnitrack::Context.current
+        clean    = payload.reject { |k, _| k.to_s.start_with?("__") }
+
+        event = {
+          event_name:       map_event_name(event_name),
+          event_time:       Time.now.to_i,
+          action_source:    "website",
+          event_source_url: payload[:event_source_url],
+          event_id:         payload[:event_id] || SecureRandom.uuid,
+          user_data:        build_user_data(ctx, payload),
+          custom_data:      build_custom_data(clean)
+        }.compact
+
+        body = { data: [event] }
+        body[:test_event_code] = config[:test_event_code] if config[:test_event_code]
+        body
+      end
+
+      def build_user_data(ctx, payload)
+        # Merge pre-identified user data + request context
+        pre_identified = ctx&.custom_data&.dig(:meta_user_data) || {}
+
+        data = {
+          client_ip_address: ctx&.ip,
+          client_user_agent: ctx&.user_agent,
+          fbc:               fbc_from_context(ctx, payload),
+          fbp:               ctx&.cookies&.dig("_fbp")
+        }.compact
+
+        data.merge!(pre_identified)
+
+        # Also accept direct PII in payload
+        if payload[:email]
+          data[:em] = sha256(payload[:email])
+        end
+        if payload[:phone]
+          data[:ph] = sha256(payload[:phone].to_s.gsub(/\D/, ""))
+        end
+
+        data
+      end
+
+      def build_custom_data(payload)
+        cd = {}
+        cd[:value]       = payload[:value].to_f        if payload[:value]
+        cd[:currency]    = payload[:currency] || "USD"
+        cd[:content_ids] = Array(payload[:content_ids]) if payload[:content_ids]
+        cd[:content_type]= payload[:content_type]       if payload[:content_type]
+        cd[:order_id]    = payload[:order_id].to_s      if payload[:order_id]
+        cd[:num_items]   = payload[:num_items].to_i     if payload[:num_items]
+        cd
+      end
+
+      def map_event_name(name)
+        # Attempt to find standard Meta event by case-insensitive match
+        standard = STANDARD_EVENTS.find { |e| e.downcase == name.to_s.downcase }
+        standard || name.to_s
+      end
+
+      def fbc_from_context(ctx, payload)
+        fbclid = payload[:fbclid] ||
+                 ctx&.click_ids&.dig(:fbclid)
+        return unless fbclid
+
+        ts = Time.now.to_i
+        "fb.1.#{ts}.#{fbclid}"
+      end
+
+      def normalize_user(user_data)
+        {
+          em: sha256(user_data[:email]),
+          ph: sha256(user_data[:phone].to_s.gsub(/\D/, "")),
+          fn: sha256(user_data[:first_name]),
+          ln: sha256(user_data[:last_name]),
+          ct: sha256(user_data[:city]),
+          st: sha256(user_data[:state]),
+          zp: sha256(user_data[:zip]),
+          country: sha256(user_data[:country])
+        }.compact.reject { |_, v| v == sha256("") }
+      end
+    end
+  end
+end

data/lib/omnitrack/adapters/snapchat.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Adapters
+    # Snapchat Conversions API (server-side).
+    # Docs: https://marketingapi.snapchat.com/docs/conversion.html
+    #
+    # Required config:
+    #   pixel_id      — Snap Pixel ID
+    #   access_token  — long-lived access token
+    #
+    class Snapchat < Base
+      self.adapter_name = :snapchat
+
+      API_ENDPOINT = "https://tr.snapchat.com/v2/conversion"
+
+      STANDARD_EVENTS = %w[
+        PURCHASE ADD_CART VIEW_CONTENT ADD_BILLING SIGN_UP LOGIN
+        START_CHECKOUT PAGE_VIEW SUBSCRIBE SEARCH CUSTOM_EVENT_1
+      ].freeze
+
+      def track_event(event_name, payload = {})
+        safe_execute(event_name) do
+          body     = build_event_body(event_name, payload)
+          response = http_post(API_ENDPOINT, body: body, headers: auth_headers)
+          result   = JSON.parse(response.body)
+
+          Omnitrack::Result.success(adapter: name, data: result)
+        end
+      end
+
+      def track_conversion(data = {})
+        track_event("PURCHASE", data)
+      end
+
+      def identify_user(user_data = {})
+        ctx = Omnitrack::Context.current
+        ctx&.merge!(snapchat_user_data: normalize_user(user_data))
+
+        Omnitrack::Result.success(
+          adapter:  name,
+          metadata: { note: "Snapchat user data stored in context" }
+        )
+      end
+
+      private
+
+      def validate_config
+        require_config!(:pixel_id,     hint: "Snap Pixel ID")
+        require_config!(:access_token, hint: "Long-lived access token")
+      end
+
+      def auth_headers
+        { "Authorization" => "Bearer #{config[:access_token]}" }
+      end
+
+      def build_event_body(event_name, payload)
+        ctx   = Omnitrack::Context.current
+        clean = payload.reject { |k, _| k.to_s.start_with?("__") }
+
+        {
+          pixel_id:   config[:pixel_id],
+          test_mode:  config[:test_mode] ? 1 : 0,
+          data: [
+            {
+              event_type:        map_event_name(event_name),
+              event_conversion_type: "WEB",
+              event_tag:         payload[:event_tag],
+              timestamp:         (Time.now.to_f * 1000).to_i,
+              hashed_email:      payload[:email] ? sha256(payload[:email]) : nil,
+              hashed_phone:      payload[:phone] ? sha256(payload[:phone].to_s.gsub(/\D/, "")) : nil,
+              hashed_ip_address: ctx&.ip ? sha256(ctx.ip) : nil,
+              user_agent:        ctx&.user_agent,
+              page_url:          payload[:page_url],
+              client_dedup_id:   payload[:event_id] || SecureRandom.uuid,
+              price:             clean[:value]&.to_f,
+              currency:          clean[:currency] || "USD",
+              item_ids:          Array(clean[:item_ids]).join(","),
+              number_items:      clean[:quantity]&.to_i,
+              order_id:          clean[:order_id]&.to_s,
+              click_id:          ctx&.click_ids&.dig(:sclid)
+            }.compact
+          ]
+        }
+      end
+
+      def map_event_name(name)
+        upper = name.to_s.upcase
+        STANDARD_EVENTS.include?(upper) ? upper : "CUSTOM_EVENT_1"
+      end
+
+      def normalize_user(user_data)
+        {
+          hashed_email: sha256(user_data[:email]),
+          hashed_phone: sha256(user_data[:phone].to_s.gsub(/\D/, ""))
+        }.compact
+      end
+    end
+  end
+end

data/lib/omnitrack/adapters/tiktok.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Adapters
+    # TikTok Events API (server-side).
+    # Docs: https://ads.tiktok.com/marketing_api/docs?id=1741601162187777
+    #
+    # Required config:
+    #   pixel_id      — TikTok Pixel ID
+    #   access_token  — Events API access token
+    #
+    class TikTok < Base
+      self.adapter_name = :tiktok
+
+      API_ENDPOINT = "https://business-api.tiktok.com/open_api/v1.3/pixel/track/"
+
+      STANDARD_EVENTS = %w[
+        ViewContent ClickButton Search AddToWishlist AddToCart
+        InitiateCheckout AddPaymentInfo PlaceAnOrder CompletePayment
+        Download Register Subscribe Contact Submit
+      ].freeze
+
+      def track_event(event_name, payload = {})
+        safe_execute(event_name) do
+          body     = build_event_body(event_name, payload)
+          response = http_post(API_ENDPOINT, body: body, headers: auth_headers)
+          result   = JSON.parse(response.body)
+
+          Omnitrack::Result.success(adapter: name, data: result)
+        end
+      end
+
+      def track_conversion(data = {})
+        track_event("CompletePayment", data)
+      end
+
+      def identify_user(user_data = {})
+        ctx = Omnitrack::Context.current
+        ctx&.merge!(tiktok_user_data: normalize_user(user_data))
+
+        Omnitrack::Result.success(
+          adapter:  name,
+          metadata: { note: "TikTok user data stored in context" }
+        )
+      end
+
+      private
+
+      def validate_config
+        require_config!(:pixel_id,     hint: "TikTok Pixel ID")
+        require_config!(:access_token, hint: "Events API access token")
+      end
+
+      def auth_headers
+        { "Access-Token" => config[:access_token] }
+      end
+
+      def build_event_body(event_name, payload)
+        ctx   = Omnitrack::Context.current
+        clean = payload.reject { |k, _| k.to_s.start_with?("__") }
+
+        {
+          pixel_code: config[:pixel_id],
+          event:      map_event_name(event_name),
+          event_id:   payload[:event_id] || SecureRandom.uuid,
+          timestamp:  Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          context: {
+            user_agent: ctx&.user_agent,
+            ip:         ctx&.ip,
+            user: build_user_data(ctx, payload),
+            ad: {
+              callback: payload[:ttclid] || ctx&.click_ids&.dig(:ttclid)
+            }.compact,
+            page: {
+              url:     payload[:page_url],
+              referrer: payload[:referrer]
+            }.compact
+          }.compact,
+          properties: build_properties(clean)
+        }
+      end
+
+      def build_user_data(ctx, payload)
+        pre = ctx&.custom_data&.dig(:tiktok_user_data) || {}
+        data = pre.dup
+        data[:email] = sha256(payload[:email]) if payload[:email]
+        data[:phone] = sha256(payload[:phone].to_s.gsub(/\D/, "")) if payload[:phone]
+        data
+      end
+
+      def build_properties(payload)
+        props = {}
+        props[:value]        = payload[:value].to_f        if payload[:value]
+        props[:currency]     = payload[:currency] || "USD"
+        props[:content_id]   = payload[:content_id]        if payload[:content_id]
+        props[:content_type] = payload[:content_type]      if payload[:content_type]
+        props[:quantity]     = payload[:quantity].to_i      if payload[:quantity]
+        props[:order_id]     = payload[:order_id].to_s      if payload[:order_id]
+        props
+      end
+
+      def map_event_name(name)
+        STANDARD_EVENTS.find { |e| e.downcase == name.to_s.downcase } || name.to_s
+      end
+
+      def normalize_user(user_data)
+        {
+          email: sha256(user_data[:email]),
+          phone: sha256(user_data[:phone].to_s.gsub(/\D/, ""))
+        }.compact
+      end
+    end
+  end
+end

data/lib/omnitrack/concerns/controller.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Concerns
+    # Include this concern in any controller to get convenient tracking helpers
+    # and automatic context enrichment.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include Omnitrack::Controller
+    #   end
+    #
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :omnitrack_context if respond_to?(:helper_method)
+      end
+
+      # Access the current request context (already built by middleware)
+      def omnitrack_context
+        Omnitrack::Context.current || Omnitrack::Context.from_request(request)
+      end
+
+      # Track an event from a controller action.
+      #
+      #   def create
+      #     @order = Order.create!(order_params)
+      #     omnitrack_event("purchase", value: @order.total, currency: "USD")
+      #   end
+      #
+      def omnitrack_event(event_name, payload = {})
+        enriched = merge_context(payload)
+        Omnitrack.track(event_name, enriched)
+      end
+
+      # Track a conversion from a controller action.
+      def omnitrack_conversion(data = {})
+        enriched = merge_context(data)
+        Omnitrack.track_conversion(enriched)
+      end
+
+      # Identify the current user.
+      def omnitrack_identify(user_data = {})
+        Omnitrack.identify(user_data)
+      end
+
+      # Attach extra data to the current context (persists for this request only).
+      def omnitrack_set(data = {})
+        omnitrack_context.merge!(data)
+      end
+
+      private
+
+      # Merge context data into payload so adapters have full picture
+      def merge_context(payload)
+        ctx = omnitrack_context
+        payload.merge(
+          __context__: ctx.to_h
+        )
+      end
+    end
+  end
+
+  # Shorthand for +Omnitrack::Concerns::Controller+
+  Controller = Concerns::Controller
+end