analytics-ruby

repository·master·Indexed 18 days ago

https://github.com/segmentio/analytics-ruby

A Ruby client for Segment that allows developers to instrument applications with a single API to send data to downstream analytics tools. It provides the Segment::Analytics client for tracking events (track, identify, page, screen, alias, group) and includes a test queue for verification, a stubbing mode to prevent network calls, and an e2e-cli tool for end-to-end testing of event sequences.

Tokens: 4.8K
Snippets: 21
Records: 25
Agent score: 64%

What's inside analytics-ruby

Use the Test Queue for testing
master
When initializing Segment::Analytics, you can pass test: true to capture all requests in a local test_queue instead of sending them to Segment. This allows you to inspect sent events during automated tests.
To prevent real network calls during specs, combine test: true with stub: true.
Key Test Queue methods:
- client.test_queue.all: Returns all messages in the queue.
- client.test_queue.track: Returns only track events.
- client.test_queue.alias: Returns only alias events.
- client.test_queue.group: Returns only group events.
- client.test_queue.identify: Returns only identify events.
- client.test_queue.page: Returns only page events.
- client.test_queue.screen: Returns only screen events.
- client.test_queue.reset!: Clears the queue.
```
client = Segment::Analytics.new(write_key: 'YOUR_WRITE_KEY', test: true)

client.track(user_id: 'foo', event: 'bar')

# Inspect the captured event
client.test_queue.all
# [
#     {
#          :context => { :library => { :name => "analytics-ruby", :version => "2.2.8.pre" } },
#          :messageId => "e9754cc0-1c5e-47e4-832a-203589d279e4",
#          :timestamp => "2021-02-19T13:32:39.547+01:00",
#            :userId => "foo",
#              :type => "track",
#               :event => "bar",
#          :properties => {}
#     }
# ]

# Clear the queue for the next test
client.test_queue.reset!
```
https://github.com/segmentio/analytics-ruby/blob/master/README.md
Use the analytics-ruby e2e-cli for end-to-end testing
master
The analytics-ruby e2e-cli is a tool for testing the analytics-ruby SDK by sending event sequences through the real SDK and reporting the outcome as JSON. It accepts a JSON description of event sequences and SDK configuration via the --input flag.
Requirements
- Ruby 2.6+
- The analytics-ruby SDK must be present in the parent directory (the script adds ../lib to $LOAD_PATH automatically).
Usage
Run the script using ruby main.rb and provide a JSON string to the --input argument.
```
ruby main.rb --input '<json>'
```
https://github.com/segmentio/analytics-ruby/blob/master/e2e-cli/README.md
Install analytics-ruby
master
You can install the library using either a Gemfile or by installing the gem directly into your environment via rubygems.org.
```
### Into Gemfile
```ruby
gem 'analytics-ruby'
```
Into environment gems
```
gem install 'analytics-ruby'
```
https://github.com/segmentio/analytics-ruby/blob/master/README.md
Run the full E2E test suite
master
To run the full end-to-end test suite, use the ./run-e2e.sh script.
Note: This requires the sdk-e2e-tests repository to be checked out alongside the SDK root (at ../../sdk-e2e-tests relative to this directory).
Commands
- Standard run: ./run-e2e.sh
- With custom tests directory: E2E_TESTS_DIR=/path/to/sdk-e2e-tests ./run-e2e.sh
- Run specific suite: ./run-e2e.sh --suite basic (arguments are forwarded to run-tests.sh)
```
./run-e2e.sh
```
https://github.com/segmentio/analytics-ruby/blob/master/e2e-cli/README.md

Configure the e2e-cli input JSON

master

The input to the CLI is a JSON object that configures the SDK and defines event sequences.

Top-level Fields

Field	Type	Description
`writeKey`	string	Segment write key
`apiHost`	string	Full API base URL (e.g. `https://api.segment.io`)
`sequences`	array	List of event sequences (processed in order)
`config`	object	SDK configuration settings

Sequence Fields

Each object in the sequences array contains:

delayMs (number): Milliseconds to sleep before processing this sequence.
events (array): A list of event objects to send.

Configuration (`config`) Fields

Field	Type	Description
`flushAt`	number	Max events per batch (`batch_size`)
`flushInterval`	number	Flush interval in ms (informational, not applied)
`maxRetries`	number	Number of HTTP retries on failure
`timeout`	number	HTTP timeout in seconds (informational, not applied)

Proxy methods to the Segment::Analytics::Client
master
The Segment::Analytics module serves as a high-level entry point that proxies all method calls to an internal Segment::Analytics::Client instance. This allows you to call tracking methods (like track, identify, page, etc.) directly on the Segment::Analytics object.
https://github.com/segmentio/analytics-ruby/blob/master/lib/segment/analytics.rb
Initialize Segment::Analytics with stubbing
master
You can initialize the Segment::Analytics module to create a client instance. This module acts as a proxy to Segment::Analytics::Client.
To prevent requests from hitting the actual Segment server during development or testing, you can pass the :stub option. When :stub is set to true, requests are stubbed to return a successful response without making network calls.
```
# To enable stubbing (no network requests)
analytics = Segment::Analytics.new(stub: true)

# Standard initialization
analytics = Segment::Analytics.new
```
https://github.com/segmentio/analytics-ruby/blob/master/lib/segment/analytics.rb

Example e2e-cli input JSON

master

This example demonstrates a complete configuration including SDK settings, a sequence of different event types, and batching configuration.

ruby main.rb --input '{
  "writeKey": "YOUR_WRITE_KEY",
  "apiHost": "https://api.segment.io",
  "sequences": [
    {
      "delayMs": 0,
      "events": [
        {"type": "track", "event": "Test Event", "userId": "user-1", "properties": {"foo": "bar"}},
        {"type": "identify", "userId": "user-1", "traits": {"name": "Alice"}},
        {"type": "page", "userId": "user-1", "name": "Home", "category": "Nav"},
        {"type": "screen", "userId": "user-1", "name": "Main"},
        {"type": "alias", "userId": "new-id", "previousId": "user-1"},
        {"type": "group", "userId": "user-1", "groupId": "group-1", "traits": {"plan": "pro"}}
      ]
    }
  ],
  "config": {
    "flushAt": 15,
    "flushInterval": 1000,
    "maxRetries": 3,
    "timeout": 10
  }
}'

Configure Test Queue in RSpec
master
To ensure a clean state for every test, call reset! on the test queue in an RSpec before block.
```
RSpec.configure do |config|
  config.before do
    Analytics.test_queue.reset!
  end
end
```
https://github.com/segmentio/analytics-ruby/blob/master/README.md
Initialize the Segment::Analytics client
master
To start sending data to Segment, create an instance of Segment::Analytics using your Segment write_key.
```
analytics = Segment::Analytics.new(write_key: 'YOUR_WRITE_KEY')
```
https://github.com/segmentio/analytics-ruby/blob/master/README.md
Configure the Segment::Analytics logger
master
The Segment::Analytics module provides a centralized logging mechanism. By default, it uses Rails.logger if the Rails framework is defined; otherwise, it initializes a new Logger instance pointing to STDOUT with the program name set to Segment::Analytics.
All log messages are wrapped by a PrefixedLogger which prepends the string [analytics-ruby] to every message. You can override the global logger by assigning a new logger instance to Segment::Analytics.logger.
```
# To use the default logger:
Segment::Analytics.logger.info("Message")

# To provide a custom logger:
custom_logger = Logger.new('segment.log')
Segment::Analytics.logger = custom_logger
```
https://github.com/segmentio/analytics-ruby/blob/master/lib/segment/analytics/logging.rb

Supported event types in e2e-cli

master

All event keys in the JSON input must use camelCase. The CLI converts them to snake_case before passing them to the SDK.

type	Required keys	Optional keys
`track`	`userId` or `anonymousId`, `event`	`properties`, `context`, `integrations`, `messageId`, `timestamp`
`identify`	`userId` or `anonymousId`	`traits`, `context`, `integrations`, `messageId`, `timestamp`
`page`	`userId` or `anonymousId`	`name`, `category`, `properties`, `context`, `integrations`, `messageId`, `timestamp`
`screen`	`userId` or `anonymousId`	`name`, `properties`, `context`, `integrations`, `messageId`, `timestamp`
`alias`	`userId`, `previousId`	`context`, `integrations`, `messageId`, `timestamp`
`group`	`userId` or `anonymousId`, `groupId`	`traits`, `context`, `integrations`, `messageId`, `timestamp`

analytics-ruby

What's inside analytics-ruby

Requirements

Usage

Into environment gems

Commands

Top-level Fields

Sequence Fields

Configuration (config) Fields

Configuration (`config`) Fields