AI_Index

Ruby SDK Wiki — AI Agent Index

This index helps AI agents find the right documentation page without reading the entire wiki. Read this file first, then load only the specific pages relevant to your task.

Page Origin

This wiki contains two types of pages:

• Shared docs (lowercase-hyphenated filenames) — Cross-SDK concept docs whose canonical source is the backend repo at public/js/tracking/full-stack-docs/ (concepts/ and guides/ subdirs). They are identical in prose across the JavaScript, PHP, Android, and Ruby SDK wikis. Do not edit them here — they are owned by the canonical source.
• Ruby-specific docs (CamelCase filenames) — Written for this SDK only: quickstart, installation, initialization, configuration, return types, code examples, fork safety & runtime recipes, tracking control, and testing.

Getting Started

Page	When to read
How Convert Works	High-level overview of the Convert platform and SDKs
Architecture Overview	System architecture, module relationships, data flow
Data Model Reference	Entity relationships: Experience, Variation, Feature, Variable, Goal, Audience, Location
Quickstart Overview	Cross-SDK quickstart concepts before diving into Ruby-specific setup
Requirements & Constraints	SDK limitations, environment requirements, known constraints

Ruby SDK Reference

Page	When to read
Quickstart	Step-by-step Ruby setup and first experiment
Installation	Add the convert_sdk gem (Bundler / gem install), Ruby version floor, zero runtime deps
Initialization	ConvertSdk.create module factory, fetch vs direct-data mode, the ready event, optional sink
Configuration Options	Full config-option reference (tracking, batch size, flush/refresh intervals, timeouts, RedisStore, cache_level, debug_token)
Return Types & Sentinels	Frozen BucketedVariation/BucketedFeature, the sentinel contract (RuleError, BucketingError), FeatureStatus/GoalDataKey enums, case variation&.key
Code Examples	Complete Ruby examples for every SDK method
Fork Safety & Runtime Recipes	Zero-config fork survival; Puma cluster / Unicorn / Passenger / Sidekiq / AWS Lambda / plain CLI wiring; postfork, the fork/daemon matrix
Tracking Control	Consent: the global tracking switch, the per-call enable_tracking override, and preview's zero-trace suppression

Core Concepts (Shared)

Page	When to read
Experiences & Variations	A/B test structure, variation assignment, activation
Feature Flags	Feature flag evaluation, variable values, feature status
Bucketing Algorithm	Hash-based visitor assignment, traffic allocation, deterministic bucketing
Rule Evaluation & Targeting	Audience matching, location matching, scheduling rules
Segments	Visitor segmentation logic and custom segments
Data Management	Data access layer, project config, entity lookups
Event System	Event pub/sub, lifecycle hooks, custom events
API Communication & Tracking	HTTP communication, config fetching, event tracking, queue management

How-To Guides (Shared)

Page	When to read
Running Experiences	End-to-end guide: activate experiments, get variations for a visitor
Running Features	Feature flag usage: evaluate flags, get variable values
Tracking Conversions	Goal tracking, conversion events, revenue tracking
Visitor Context & Properties	Visitor identification, custom properties, cross-session persistence
Persistent DataStore	Custom data store integration for visitor state persistence
QA & Preview	Debug tokens (draft/paused config) and preview links — the workflow behind debug_token: and Context#set_preview
Mutually Exclusive Experiments	The bucketed_into_experience_key audience rule: excluding or layering experiments per visitor
Server-Side Experimentation	Deciding on the server: rendering, caching, and SSR concerns
From Tracking Script to SDK	Migrating a web tracking-script setup to a Full Stack SDK
Direct Tracking Endpoint	Posting events straight to the tracking endpoint without an SDK
Troubleshooting	Common issues, debugging techniques, diagnostic steps

Contributing

Page	When to read
Testing	RSpec unit + cross-SDK parity (hashing, rules, packed + anchored bucketing), RBS/Steep type checks, coverage gates, the fork-safety smoke
Changelog	Where releases live (GitHub Releases, no CHANGELOG.md), how semantic-release computes a version, pinning

Ruby-Specific Notes

Topic	Key difference from JS SDK
Initialization	ConvertSdk.create(sdk_key: "...") — module factory; synchronous config fetch + install; fires ready
Dependencies	Zero runtime deps (stdlib Net::HTTP/JSON/Mutex); optional redis gem lazily required for RedisStore
Concurrency / fork	Lazy-started threads; automatic Process._fork re-arm (ForkGuard); PID-guarded flush boundaries + at_exit; Client#postfork escape hatch
Return types	Frozen BucketedVariation/BucketedFeature; misses are sentinels (RuleError/BucketingError) with nil #key — never exceptions
Naming	snake_case public API; camelCase wire payload (translated only at Config inbound + ApiManager outbound)
QA / preview	Context#set_preview is synchronous — no async/await equivalent; the on-demand fetch for an experience missing from the installed config is memoized process-wide for 60s. ConvertSdk.parse_preview_param returns a 2-element String Array (not JS's {experienceId, variationId} object) or nil
Typing	RBS signatures + steep check; CRuby 3.1–3.4 + JRuby

Public API Surface (entry points)

ConvertSdk.create(sdk_key:, sdk_key_secret:, data:, store:, clock:, sink:, **options) -> Client
ConvertSdk.parse_preview_param(value) -> [experience_id, variation_id] | nil   (pure helper)
Client
  ├── create_context(visitor_id, attributes = nil) -> Context | nil
  ├── flush(reason = nil)   (alias: release_queues)
  ├── postfork
  └── on(event, &listener)
Context
  ├── set_preview(experience_id:, variation_id:)     -> self   (forces one variation; zero-trace)
  ├── run_experience(key, attributes = nil)          -> BucketedVariation | Sentinel
  ├── run_experiences(attributes = nil)              -> Array<BucketedVariation>
  ├── run_feature(key, attributes = nil)             -> BucketedFeature
  ├── run_features(attributes = nil)                 -> Array<BucketedFeature>
  ├── track_conversion(goal_key, goal_data: nil, force_multiple_transactions: false)
  ├── set_default_segments(segments)
  ├── run_custom_segments(segment_keys, attributes = nil)
  ├── update_visitor_properties(properties)
  ├── get_visitor_data
  └── get_config_entity(key, entity_type)