The Ruby SDK makes it easy to track events from Ruby applications.
Installation
The Ruby SDK can be installed via RubyGems.org. You may add the SDK to your Gemfile if you're using Bundler, or install it directly:
gem install events-sdk-ruby
To initialize the Ruby SDK in your application, create a new Analytics instance:
require 'hightouch'
analytics = Hightouch::Analytics.new(
write_key: WRITE_KEY,
host: 'us-east-1.hightouch-events.com'
)
API
Identify
The identify method sends an identify event.
Unlike the Browser SDK, it does not persist the user ID and traits locally, so user IDs must be explicitly added to other events. This is because server side events are usually servicing many different users at once.
Example usage:
analytics.identify(
user_id: "123",
traits: {
location: "San Francisco",
}
)
Method parameters:
| Parameter | Type | Description |
|---|---|---|
user_id | String | The user's persistent ID |
anonymous_id | String | The user's anonymous ID |
traits | Hash | Additional traits about the user, such as email and name. |
context | Hash | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Time | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Track
The track method sends a track event.
Example usage:
analytics.track(
user_id: "123",
event: "Order completed",
properties: {
total: 29.99,
}
)
Method parameters:
| Parameter | Type | Description |
|---|---|---|
user_id | String | The user's persistent ID |
anonymous_id | String | The user's anonymous ID |
event | String | The name of the event. |
properties | Hash | Additional properties about the event, such as product_id. |
context | Hash | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Time | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Page
The page method sends a page event.
Example usage:
analytics.page(
user_id: "123",
category: "Docs",
name: "Getting started",
)
Method parameters:
| Parameter | Type | Description |
|---|---|---|
user_id | String | The user's persistent ID |
anonymous_id | String | The user's anonymous ID |
name | String | The page's name. For example "Getting started" |
properties | Hash | Additional properties about the event, such as url. |
context | Hash | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Time | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Screen
The screen method sends a screen event.
Example usage:
analytics.screen(
user_id: "123",
category: "Docs",
name: "Getting started",
)
Method parameters:
| Parameter | Type | Description |
|---|---|---|
user_id | String | The user's persistent ID |
anonymous_id | String | The user's anonymous ID |
name | String | The screen's name. For example "Getting started" |
category | String | The screen's category. For example "Docs" |
properties | Hash | Additional properties about the event, such as url. |
context | Hash | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Time | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Group
The group method sends a group event.
Example usage:
analytics.group(
user_id: "123",
group_id: "456",
traits: {
company_location: "San Francisco",
},
)
Method parameters:
| Parameter | Type | Description |
|---|---|---|
user_id | String | The user's persistent ID |
anonymous_id | String | The user's anonymous ID |
groupId | String | The id for the group. |
traits | Object | Additional traits about the group, such as company_name. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Flush
The Ruby SDK buffers events locally before sending them to Hightouch's servers. This minimizes the number of requests made by the SDK and makes the tracking non-blocking.
To force the local buffer to be sent to Hightouch immediately call the flush
method. flush should be called when shutting down your Ruby app to
make sure no events are lost.
Example usage:
analytics.flush()