omnitrack-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3159ca70c1926bd7576f69daa82b043b7712219c920ad13c956560294b52940c
+  data.tar.gz: 8f86771d6bba1b2c6531b1076c369eb464faa40406d111aacebe0610273f83df
+SHA512:
+  metadata.gz: d49fed2d40c06182c33922feafdf8fb7969480c3468d03b95248594fb16517ce0e6f8cc3171c002bd3d8b83ce9fa097d0f61bb88bdf7156015cfa10ea50d16de
+  data.tar.gz: d95277587d7eab7b07e4cebbad26e593d96ee00dafff1ebcbcc45953d073db1255c6b27585011e61b006131078c93814d6e530e4986660a6d0c7cd692efef4db

data/.env.example

@@ -0,0 +1,43 @@
+# OmniTrack (omnitrack-rb) — copy to .env in your Rails app and fill real values.
+# Never commit .env. Use "cp .env.example .env" and enable only what you need.
+#
+# Enable flags: set to the string "true" to turn an adapter on (see config/initializers/omnitrack.rb).
+
+# ---------------------------------------------------------------------------
+# Google Ads (server: Click Conversion Upload API)
+# ---------------------------------------------------------------------------
+GOOGLE_ADS_ENABLED=false
+GOOGLE_ADS_CUSTOMER_ID=
+GOOGLE_ADS_DEVELOPER_TOKEN=
+GOOGLE_ADS_ACCESS_TOKEN=
+GOOGLE_ADS_CONVERSION_ACTION_ID=
+# GOOGLE_ADS_LOGIN_CUSTOMER_ID=          # MCC / manager account only
+
+# ---------------------------------------------------------------------------
+# Google Analytics 4 (server: Measurement Protocol; browser: gtag in layout)
+# ---------------------------------------------------------------------------
+GA4_ENABLED=false
+GA4_MEASUREMENT_ID=
+GA4_API_SECRET=
+
+# ---------------------------------------------------------------------------
+# Meta (Facebook / Instagram) Conversions API + pixel
+# ---------------------------------------------------------------------------
+META_ENABLED=false
+META_PIXEL_ID=
+META_ACCESS_TOKEN=
+# META_TEST_EVENT_CODE=                  # optional: Events Manager test tool
+
+# ---------------------------------------------------------------------------
+# TikTok Ads
+# ---------------------------------------------------------------------------
+TIKTOK_ENABLED=false
+TIKTOK_PIXEL_ID=
+TIKTOK_ACCESS_TOKEN=
+
+# ---------------------------------------------------------------------------
+# Snapchat Ads
+# ---------------------------------------------------------------------------
+SNAPCHAT_ENABLED=false
+SNAPCHAT_PIXEL_ID=
+SNAPCHAT_ACCESS_TOKEN=

data/AI_GEM_SETUP.md

@@ -0,0 +1,164 @@
+# OmniTrack-rb — integration guide for tools and maintainers
+
+Use this document when **adding `omnitrack-rb` to an existing Rails 6+ app** so the project boots, initializers run, and ENV is wired with **no runtime errors** from the gem. Follow the steps in order.
+
+---
+
+## 1. Gemfile (required)
+
+In the **host** application `Gemfile`:
+
+```ruby
+gem "omnitrack-rb"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+**Do not** add a `require` in `config/application.rb` for this gem; the Railtie loads with Rails when Bundler requires the default group.
+
+---
+
+## 2. Install initializer (required)
+
+From the app root:
+
+```bash
+rails generate omnitrack:install
+```
+
+This creates:
+
+- `config/initializers/omnitrack.rb`
+
+**Boot check (must succeed):**
+
+```bash
+bin/rails runner "puts Omnitrack::VERSION"
+```
+
+If this fails, fix Bundler / Ruby version and ensure `bundle install` completed.
+
+---
+
+## 3. Environment variables (no secrets in git)
+
+The generated initializer uses `ENV[...]` for all credentials. **All adapters are off until you set each `*_ENABLED=true`.** That avoids accidental API calls with empty keys.
+
+### Option A — `.env` in development (recommended for local work)
+
+1. Add to **host** `Gemfile` (development and test; optional for other groups):
+
+   ```ruby
+   group :development, :test do
+     gem "dotenv-rails"
+   end
+   ```
+
+2. `bundle install`
+
+3. If the install generator did not create it, copy the example file in the app root:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   (Running `rails generate omnitrack:install` creates `.env.example` in the app root when it does not already exist. You can also copy from the gem: `bundle show omnitrack-rb` then open that directory’s `.env.example`.)
+
+4. Add **host** `.gitignore` line if missing:
+
+   ```
+   .env
+   .env.*.local
+   ```
+
+5. In `.env`, set only the platforms you use. Start with all `*_ENABLED=false` and flip one to `true` when credentials are real.
+
+6. **Load order:** `dotenv-rails` runs before `config/initializers/*`, so `ENV` is set when `omnitrack.rb` runs.
+
+### Option B — Production / staging (no .env file)
+
+Set the same variable names in your host (Kubernetes secrets, Heroku config, 1Password, Doppler, etc.). **Never** require `.env` in production; the app reads the real environment.
+
+### Option C — `Rails credentials` (optional)
+
+If you use encrypted credentials, read values in the initializer and assign them before `Omnitrack.configure`, or set `ENV` in `config/application.rb` from `Rails.application.credentials` — keep adapter keys out of version control.
+
+---
+
+## 4. ActiveJob and async (avoid confusion)
+
+`config/initializers/omnitrack.rb` (generated) may set `config.async = Rails.env.production?`.
+
+- If `async` is **true** in an environment, **ActiveJob** must be usable and a queue adapter (e.g. Sidekiq) should be set for production.
+- If you are not ready for jobs, set in the initializer:
+
+  ```ruby
+  config.async = false
+  ```
+
+Until `Omnitrack::Jobs::TrackingJob` and ActiveJob are loaded, the gem runs synchronously when `async` is false (safe default for first integration).
+
+---
+
+## 5. Full-stack: layout and controller (one-time)
+
+- **Layout head** — `app/views/layouts/application.html.erb` (or your main layout) inside `<head>`:
+
+  ```erb
+  <%= omnitrack_tags %>
+  ```
+
+- **Controller** — call tracking **after** a successful business outcome (e.g. order created). The Railtie already includes `Omnitrack::Controller` on `ActionController` — you can use `omnitrack_event` / `Omnitrack.track` in actions. See [USAGE.md](USAGE.md#8-concrete-examples-files-and-line-where-to-put-calls) for file-level examples.
+
+---
+
+## 6. API-only apps
+
+- No `omnitrack_tags` in layout (optional to omit).
+- Pass `gclid`, `fbclid`, `ttclid` from the client in params or body; the middleware and `Omnitrack::Context` still apply when the request includes them.
+- `config.mode` default `:auto` will treat `api_only` apps as **backend**-oriented (no browser pixels unless you set `:hybrid` / `:frontend` on purpose).
+
+---
+
+## 7. Common mistakes (avoid “mysterious” errors)
+
+| Symptom | What to do |
+|--------|------------|
+| `uninitialized constant Omnitrack` | Run `bundle install`; ensure `config/application.rb` loads Bundler default group; boot with `bin/rails c`. |
+| `ENV[...] is nil` in logs | Adapters with `enabled: true` but missing tokens may log or skip; set `*_ENABLED=false` until credentials exist. |
+| Job errors when `async: true` | Set `config.async = false` until ActiveJob and queue are configured, or add queue adapter. |
+| `.env` not applied | Add `dotenv-rails` in **development**; restart Spring/server; do not commit `.env`. |
+| Clicks not attributed | Pass click IDs in request params/headers; ensure `config.auto_capture = true` (default in template). |
+
+---
+
+## 8. Files the host app should have after a clean setup
+
+| Path | Purpose |
+|------|--------|
+| `Gemfile` | `gem "omnitrack-rb"` (and `dotenv-rails` if using `.env`) |
+| `config/initializers/omnitrack.rb` | `Omnitrack.configure` |
+| `.env.example` | Document variable names (no secrets) — optional if committed |
+| `.env` | Local secrets — **gitignored** |
+| `app/views/layouts/...` | `<%= omnitrack_tags %>` for full-stack |
+| `log/omnitrack.log` | Created at runtime when the logger writes (ensure `log/` is writable) |
+
+---
+
+## 9. Smoke test after install
+
+```bash
+bin/rails omnitrack:status
+```
+
+Enable one adapter in `.env` with valid test credentials, then (carefully) run:
+
+```bash
+bin/rails "omnitrack:test_event[purchase]"
+```
+
+For day-to-day **method placement** (which file, which line pattern), use [USAGE.md](USAGE.md).

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- `AI_GEM_SETUP.md` — step-by-step integration for host apps (Bundler, initializer, ENV, ActiveJob, pitfalls)
+- `.env.example` — variable names matching the install template; install generator copies `env.example` → `.env.example` when missing
+- `USAGE.md` — concrete ERB/Ruby examples for layout, HTML/API controllers, and a service object
+
+### Fixed
+- Conventional `lib/omnitrack` gem layout, loadable `require "omnitrack"`
+- `rails generate omnitrack:install` generator at `lib/generators/omnitrack/install/`
+- `Omnitrack::Controller` as an alias of `Omnitrack::Concerns::Controller`
+- Default `adapter_name` for adapters uses `underscore` (snake_case) so config keys (e.g. `google_ads`) match the registry; `Omnitrack.reset!` re-registers first-party adapters in tests
+- `activesupport` as a direct runtime dependency; explicit requires for `ActiveSupport` extensions used at load time
+
+## [0.1.0] - 2024-01-15
+
+### Added
+- Initial release
+- Adapter-based architecture with `Omnitrack::Adapters::Base`
+- Google Ads adapter (Click Conversion Upload API)
+- Google Analytics 4 adapter (Measurement Protocol)
+- Meta adapter (Conversions API)
+- TikTok adapter (Events API)
+- Snapchat adapter (Conversions API)
+- Rack middleware for automatic click ID / UTM capture
+- Thread-local `Omnitrack::Context` for request data
+- Structured JSON logging to `log/omnitrack.log`
+- `Omnitrack::Result` and `Omnitrack::MultiResult` value objects
+- ActiveJob integration for async dispatch
+- Retry logic with exponential back-off
+- Rails view helpers: `omnitrack_tags`, `omnitrack_event_tag`
+- Controller concern: `Omnitrack::Controller` (alias of `Omnitrack::Concerns::Controller`)
+- `rails generate omnitrack:install` generator
+- Rake tasks: `omnitrack:status`, `omnitrack:test_event`, `omnitrack:rotate_log`
+- Adapter-level error isolation (never raises into host app)
+- SHA-256 PII hashing for all platforms

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OmniTrack contributors
+
+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,364 @@
+# OmniTrack-rb 🎯
+
+[![Gem Version](https://img.shields.io/gem/v/omnitrack-rb)](https://rubygems.org/gems/omnitrack-rb)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-red)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red)](https://rubyonrails.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+**Production-grade, modular tracking and conversion system for Ruby on Rails.**
+
+OmniTrack dispatches events to multiple ad/analytics platforms through a clean adapter pattern — works identically in full-stack and API-only Rails apps, never crashes your main application, and emits structured JSON logs to a dedicated file.
+
+**Practical usage (file placement + method examples):** [USAGE.md](USAGE.md)  
+**Add the gem to any Rails app without boot errors (ENV, jobs, checklists):** [AI_GEM_SETUP.md](AI_GEM_SETUP.md)  
+**ENV variable names (copy into host `.env.example`):** [.env.example](.env.example)
+
+---
+
+## Supported Platforms
+
+| Platform | Adapter | Server-side API | JS Pixel |
+|---|---|---|---|
+| Google Ads | `:google_ads` | ✅ Click Conversion Upload | via `omnitrack_tags` |
+| Google Analytics 4 | `:google_analytics` | ✅ Measurement Protocol | via `omnitrack_tags` |
+| Meta (Facebook/Instagram) | `:meta` | ✅ Conversions API | via `omnitrack_tags` |
+| TikTok Ads | `:tiktok` | ✅ Events API | via `omnitrack_tags` |
+| Snapchat Ads | `:snapchat` | ✅ Conversions API | via `omnitrack_tags` |
+| Custom | Your class | ✅ Extend `Base` | — |
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "omnitrack-rb"
+```
+
+Run the installer:
+
+```bash
+bundle install
+rails generate omnitrack:install
+```
+
+This creates `config/initializers/omnitrack.rb` with a fully commented template.
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/omnitrack.rb
+
+Omnitrack.configure do |config|
+  # :auto     — detects api_only? at runtime (recommended)
+  # :frontend — inject JS tags + use cookies
+  # :backend  — server-side only (Conversions APIs)
+  # :hybrid   — both simultaneously
+  config.mode = :auto
+
+  config.adapters = {
+    google_ads: {
+      enabled:              ENV["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"]
+    },
+    google_analytics: {
+      enabled:        ENV["GA4_ENABLED"] == "true",
+      measurement_id: ENV["GA4_MEASUREMENT_ID"],
+      api_secret:     ENV["GA4_API_SECRET"]
+    },
+    meta: {
+      enabled:      ENV["META_ENABLED"] == "true",
+      pixel_id:     ENV["META_PIXEL_ID"],
+      access_token: ENV["META_ACCESS_TOKEN"]
+    },
+    tiktok: {
+      enabled:      ENV["TIKTOK_ENABLED"] == "true",
+      pixel_id:     ENV["TIKTOK_PIXEL_ID"],
+      access_token: ENV["TIKTOK_ACCESS_TOKEN"]
+    },
+    snapchat: {
+      enabled:      ENV["SNAPCHAT_ENABLED"] == "true",
+      pixel_id:     ENV["SNAPCHAT_PIXEL_ID"],
+      access_token: ENV["SNAPCHAT_ACCESS_TOKEN"]
+    }
+  }
+
+  config.auto_capture = true   # capture gclid, fbclid, ttclid, UTMs automatically
+  config.log_level    = :info
+  config.async        = Rails.env.production?  # use ActiveJob in production
+  config.timeout      = 5
+  config.max_retries  = 3
+
+  # Optional: error hook for Sentry / Honeybadger
+  config.on_error = ->(error, adapter) {
+    Sentry.capture_exception(error, tags: { adapter: adapter.name })
+  }
+end
+```
+
+---
+
+## Usage
+
+### Full-stack Rails (views + controllers)
+
+**Layout** — inject all platform pixels into `<head>`:
+
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+  <%= omnitrack_tags %>
+</head>
+```
+
+**Controller** — track events server-side (`Omnitrack::Controller` is auto-included via the Railtie; you can also `include Omnitrack::Controller` explicitly in `ApplicationController` if needed):
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    @order = Order.create!(order_params)
+
+    # Fires through all enabled server-side adapters
+    omnitrack_event("purchase",
+      value:    @order.total,
+      currency: "USD",
+      order_id: @order.id)
+
+    redirect_to @order
+  end
+end
+```
+
+**View** — emit a JS event tag on the confirmation page:
+
+```erb
+<%= omnitrack_event_tag("purchase", value: @order.total, currency: "USD") %>
+```
+
+### API-only Rails
+
+No JS involved — everything is server-side:
+
+```ruby
+class Api::V1::OrdersController < ApplicationController
+  def create
+    @order = Order.create!(order_params)
+
+    Omnitrack.track("purchase",
+      value:    @order.total,
+      currency: "USD",
+      order_id: @order.id,
+      # Pass click IDs from your mobile client via request body or headers:
+      fbclid:   params[:fbclid],
+      gclid:    params[:gclid])
+
+    render json: @order
+  end
+end
+```
+
+### Service objects / background jobs
+
+```ruby
+class PurchaseTracker
+  def call(order)
+    Omnitrack.track("purchase",
+      value:    order.total,
+      currency: order.currency,
+      order_id: order.id,
+      email:    order.user.email)
+  end
+end
+```
+
+### Identify a user
+
+```ruby
+Omnitrack.identify(
+  email:      current_user.email,
+  phone:      current_user.phone,
+  first_name: current_user.first_name,
+  last_name:  current_user.last_name,
+  external_id: current_user.id.to_s
+)
+```
+
+> PII (email, phone, name) is SHA-256 hashed before being sent to any platform.
+
+---
+
+## Working with Results
+
+Every call returns an `Omnitrack::MultiResult`:
+
+```ruby
+result = Omnitrack.track("purchase", value: 99.0)
+
+result.success?      # => true if ALL adapters succeeded
+result.any_failure?  # => true if at least one adapter failed
+result.failures      # => [Omnitrack::Result, ...]
+result.successes     # => [Omnitrack::Result, ...]
+
+result.each do |r|
+  puts "#{r.adapter}: #{r.status}"  # => google_ads: success
+end
+```
+
+---
+
+## Building a Custom Adapter
+
+```ruby
+# app/tracking/my_platform_adapter.rb
+
+class MyPlatformAdapter < Omnitrack::Adapters::Base
+  self.adapter_name = :my_platform
+
+  def track_event(event_name, payload = {})
+    safe_execute(event_name) do
+      response = http_post(
+        "https://api.myplatform.com/events",
+        body: {
+          event:   event_name,
+          data:    payload,
+          api_key: config[:api_key]
+        }
+      )
+      Omnitrack::Result.success(adapter: name, data: JSON.parse(response.body))
+    end
+  end
+
+  def track_conversion(data = {})
+    track_event("conversion", data)
+  end
+
+  def identify_user(user_data = {})
+    # store or send user data
+    Omnitrack::Result.success(adapter: name)
+  end
+
+  private
+
+  def validate_config
+    require_config!(:api_key, hint: "MyPlatform API key")
+  end
+end
+```
+
+Register in config:
+
+```ruby
+Omnitrack.configure do |config|
+  config.adapters[:my_platform] = {
+    enabled: true,
+    api_key: ENV["MY_PLATFORM_API_KEY"]
+  }
+end
+
+# Register the class
+Omnitrack::Registry.register(MyPlatformAdapter)
+```
+
+---
+
+## Logging
+
+OmniTrack writes structured JSON to `log/omnitrack.log` (separate from Rails' main log):
+
+```json
+{"timestamp":"2024-01-15T10:23:45.123Z","message":"adapter.request","adapter":"meta","event":"purchase","payload":{"value":99.0}}
+{"timestamp":"2024-01-15T10:23:45.891Z","message":"adapter.response","adapter":"meta","event":"purchase","status":"success","duration_ms":768.4}
+{"timestamp":"2024-01-15T10:23:46.002Z","message":"adapter.error","adapter":"google_ads","event":"purchase","error":"Omnitrack::AdapterError","message":"HTTP 401 from googleads.googleapis.com"}
+```
+
+Configure log level:
+
+```ruby
+config.log_level = :debug  # :debug | :info | :warn | :error | :none
+```
+
+Rotate logs:
+
+```bash
+rails omnitrack:rotate_log
+```
+
+---
+
+## Rake Tasks
+
+```bash
+rails omnitrack:status            # Show configured adapters and status
+rails omnitrack:test_event        # Send a test event through all enabled adapters
+rails omnitrack:test_event[purchase]  # Send a named test event
+rails omnitrack:rotate_log        # Rotate the log file
+```
+
+---
+
+## Async / Background Jobs
+
+When `config.async = true`, tracking calls are dispatched via `ActiveJob`:
+
+```ruby
+config.async      = true
+config.queue_name = :omnitrack
+```
+
+Ensure your queue adapter is configured in production:
+
+```ruby
+# config/environments/production.rb
+config.active_job.queue_adapter = :sidekiq
+```
+
+---
+
+## Middleware
+
+`Omnitrack::Middleware::RequestTracker` is automatically inserted into your Rack stack. It:
+
+1. Captures `gclid`, `fbclid`, `ttclid`, UTMs, IP, and User-Agent from every request
+2. Makes them available at `Omnitrack::Context.current` throughout the request
+3. Clears thread-local state after each response (no cross-request leakage)
+
+---
+
+## Thread Safety
+
+- All shared state uses `Mutex`-guarded access
+- Context is stored in `Thread.current` — safe under Puma/Sidekiq
+- Adapters are instantiated per-dispatch (stateless between requests)
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create your branch (`git checkout -b feature/my-adapter`)
+3. Write tests
+4. Run `bundle exec rspec` — all green
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).