The Ruby SDK
Important
This article relates to both journy.io's SDKs and Twilio Segment SDKs.
Check out also our journy.io developers documentation -- https://developers.journy.io/
Topics
journy.io’s Ruby library lets you record data from your platform, from your Ruby code.
All of journy.io’s server-side libraries are built for high-performance, so you can use them in your web server controller code. This library uses an internal queue to make identify
and track
calls non-blocking and fast. It also batches messages and flushes asynchronously to journy.io’s servers.
Getting started
Make sure you’re using a version of Ruby that’s 14 or higher.
Run the relevant command to add journy.io’s Ruby library module to your
package.json
.gem install analytics-ruby
Initialize the
Analytics
constructor the module exposes with your journy.io SDK connector Write Key, like so:require 'segment/analytics' Analytics = Segment::Analytics.new({ write_key: 'YOUR_WRITE_KEY', host: 'analyze.journy.io', path: '/backend/v1/batch' })
Be sure to replace YOUR_WRITE_KEY
with your actual Write Key which you can find in journy.io by navigating to: Connections > API/SDK Connector and selecting the source tab and going to the Ruby tab.
This creates an instance of Analytics
that you can use to send data to journy.io for your project. The default initialization settings are production-ready and queue 20 messages before sending any requests.
There is an option in journy.io to set a proxy ("Use proxy domain") so traffic flows through your own domain. In that case, host
will have another value, pointing to your own domain.
Basic tracking methods
The basic tracking methods below serve as the building blocks of your journy.io tracking. They include Identify, Group, Track, and Page.
These methods correspond with those used in the journy.io Spec. The documentation on this page explains how to use these methods in Ruby.
Identify
For any of the different methods described on this page, you can replace the properties and traits in the code samples with variables that represent the data collected.
identify
lets you tie a user to their actions and record traits about them. It includes a unique User ID and/or anonymous ID, and any optional traits you know about them.
journy.io recommends that you make an identify
call:
After a user first registers
After a user logs in
When a user updates their info (for example, they change or add a new address)
Example of an identify
call for an identified user Elon Musk:
Analytics.identify({
user_id: 'abc123', # Elon Musk — unique Id from database
traits: {
firstname: 'Elon',
lastname: 'Musk'
email: 'elon.musk@tesla.com',
friends: 24 }
})
The call above identifies Elon by his unique User ID (the one you know him by in your database), and labels him with the firstname
, lastname
, email
, and friends
traits.
The identify
call has the following fields:
Field | Type | Description |
| String | ID for this user in your database. Optional if |
| String | The ID associated with the user when you don’t know who they are. Optional if |
| Hash | A |
| Hash | A |
| Hash | Specifies which destinations this should be sent to. |
| Time | Represents the time when the action took place. This is most useful if you’re importing historical data. If the |
| String | Unique identifier for each message that lets you find an individual message across the API. |
Identifying users happen incremental: You can identify users with a subset of traits
; and later make another identify call with another subset of traits
. The result of both identify calls will be the union of all traits
.
To delete a traits
, you have to add them to the identify
call with value null:
Find details on the identify method payload in journy.io’s Identify Spec.
Group
group
lets you associate an identified user with a group. A group could be a company, organization, account, project or team! It also lets you record custom traits about the group, like industry or number of employees.
journy.io recommends that you make a group
call:
After a user first registers, entering its company details.
After a user logs in. Make a group call for each account the user is part of.
When a user updates their info, make a group call for each account the user is part of.
Example group
call, adding user Elon Musk to account Tesla, as an 'admin':
The group
call has the following fields:
FIELDS | TYPE | DESCRIPTION |
| String | ID for this user in your database. Optional if |
| String | The ID associated with the user when you don’t know who they are. Optional if |
| String | The ID of the group. |
| Hash | A hash of traits you know about the group. For a company, they might be things like |
| Hash | A |
| Hash | Specifies which destinations this should be sent to. |
| Time | Represents the time when the action took place. This is most useful if you’re importing historical data. If the |
| String | Unique identifier for each message that lets you find an individual message across the API. |
To identify a group, without adding a user, you can use anonymousId
with the same value of the groupId
. It goes like this:
Group-calling accounts happen incremental: You can identify users with a subset of traits
; and later make another identify call with another subset of traits
. The result of both identify calls will be the union of all traits
.
To delete a traits
, you have to add them to the group
call with a null reference:
Find more details about group
, including the group
payload, in the journy.io Spec.
Track
track
lets you record the actions your users perform, optionally within the context of an account. Every action triggers what we call an “event”, which can also have associated event metadata.
You’ll want to track events that are indicators of success for your site, like Signed Up, Item Purchased or Article Bookmarked.
To get started, we recommend tracking just a few important events. You can always add more later!
Example identified track
call by a user Elon Musk:
B2B example identified track
call by a user Elon Musk in the context of account Tesla, back on Dec 12th 2015:
This example track
call tells us that Elon Musk triggered the Car Sold event with a revenue of $39999.99 and chose your hypothetical ‘200-day’ shipping, back on Dec 12th 2015.
track
event metadata ( properties
) can be anything you want to record. In this case, revenue and shipping method.
The track
call has the following fields:
Field | Type | Description |
| String | ID for this user in your database. Optional if |
| String | The ID associated with the user when you don’t know who they are. Optional if |
| String | The name of the event you’re tracking. We recommend human-readable names like Song Played or Status Updated. |
| Hash | A |
| Hash | A |
| Hash | Specifies which destinations this should be sent to. |
| Time | Represents the time when the action took place. This is most useful if you’re importing historical data. If the |
| String | Unique identifier for each message that lets you find an individual message across the API. |
Find details on best practices in event naming as well as the track
method payload in the journy.io Spec.
Page
The page
method lets you record page views on your website, along with optional extra information about the page being viewed. It is also user to record screen views in your app/on your platform.
If you’re using our client-side set up in combination with the Ruby library, page calls are already tracked for you by default. However, if you want to record your own page views manually and aren’t using our client-side library, read on!
Example page
call, where a user Elon Musk visits the pricing page:
B2B example page
call, where a user Elon Musk visits the pricing page, when being in account Tesla, back on Dec 12th 2015:
The page
call has the following fields:
Field | Type | Description |
| String | ID for this user in your database. Optional if |
| String | The ID associated with the user when you don’t know who they are. Optional if |
| String | The name of the page, for example Signup or Home. |
| String | The category of the page. Useful for things like ecommerce where many pages might live under a larger category. Note: if you only pass one string to |
| Hash | A |
| Hash | A |
| Hash | Specifies which destinations this should be sent to. |
| Time | Represents the time when the action took place. This is most useful if you’re importing historical data. If the |
| String | Unique identifier for each message that lets you find an individual message across the API. |
Find details on the page
payload in the journy.io Spec.
Configuration
The second argument to the new
function is an optional list of settings to configure the module.
FIELD | TYPE | DESCRIPTION |
| Proc | A handler which is called whenever errors are returned from the API. Useful for debugging and first time destinations. |
| FixNum | The max number of messages to put in the queue before refusing to queue more (defaults to |
| FixNum | The max number of events/identifies to send in a single batch (defaults to |
| TrueClass|FalseClass | If true, the requests don’t hit the server and are stubbed to be successful (defaults to |