This documentation provides guidance on how to integrate the June SDK with your Ruby application. June SDK is a powerful library for tracking user interactions and events, offering similar functionality to the underlying Segment SDK.

To install the June SDK in your Ruby project:

1
gem install june-analytics-ruby

First, you'll need to import the SDK into your application. Next, instantiate the client using the write key you've received when you created your June account:

1
require 'june/analytics'
2

3
Analytics = June::Analytics.new({
4
  write_key: 'YOUR_WRITE_KEY'
5
})

If you're using Rails, you can create a config/initializers/analytics_ruby.rb file and add the following code:

1
require 'june/analytics'
2

3
Analytics = June::Analytics.new({
4
  write_key: 'YOUR_WRITE_KEY',
5
  on_error: proc { |_status, msg| print msg },
6
  test: !Rails.env.production?
7
})

Now you can use the analytics instance to track events, identify users, and more.

The June Ruby SDK configuration process involves setting various options when initializing the June::Analytics. These options allow you to fine-tune how the SDK interacts with the June Analytics service.

Here are the primary configuration options that you can set:

The options are provided as a hash to the initialize method of the Client class:

1
Analytics = June::Analytics.new({
2
  write_key: 'YOUR_WRITE_KEY',
3
  max_queue_size: 1000,
4
  on_error: proc { |status, error| puts "Error: #{status}, #{error.message}" },
5
  test: true
6
})

Remember to replace 'YOUR_WRITE_KEY' with your actual project's write key. The max_queue_size and on_error options are optional, and you can leave them out if you're happy with the default settings. If you're not testing, you should set the test option to false or just omit it entirely.

To track events, you can use the track method:

1
Analytics.track(
2
  user_id: 'USER_ID',
3
  event: 'Signed In',
4
  properties: {
5
    browser: 'chrome'
6
  }
7
)

Parameters:

To identify users, you can use the identify method:

1
Analytics.identify(
2
  user_id: 'USER_ID',
3
  traits: {
4
    email: "test@example.com"
5
    # Optional
6
    name: "Joe Bloggs",
7
    avatar: "https://avatar.com/d78979as8hlsa9088f.png"
8
    # Add anything else about the user here
9
  }
10
)

Parameters:

To group users by organization or company, use the group method:

1
Analytics.group(
2
  user_id: 'USER_ID',
3
  group_id: 'GROUP_ID',
4
  traits: {
5
    name: "Acme Inc",
6
    # Optional
7
    avatar: "https://avatar.com/d78979as8hlsa9088f.png"
8
    # Add anything else about the company here
9
  }
10
)

Parameters:

In serverless environemnts like AWS Lambda, your environment may finish the code execution before June SDK is able to send events to June API.

You can use the flush method to send all queued events to June or you can configure the SDK to flush events automatically.

1
Analytics.flush

If you set batch_size to 1, the SDK will flush events automatically after every event.

1
Analytics = June::Analytics.new({
2
  write_key: 'YOUR_WRITE_KEY',
3
  batch_size: 1,
4
  on_error: proc { |status, error| puts "Error: #{status}, #{error.message}" },
5
})

To test that your June integration is working as expected you can use the test option. When this option is set to true, events are not actually sent to the June Analytics API. Instead, they're added to a test queue. This is useful for debugging and testing.

Your initialization code should include the test option:

1
Analytics = June::Analytics.new({
2
  write_key: 'YOUR_WRITE_KEY',
3
  on_error: proc { |_status, msg| print msg },
4
  test: !Rails.env.production?
5
})

Then in your spec code you can check that the events are being sent to the test queue:

1
# frozen_string_literal: true
2

3
require 'rails_helper'
4

5
RSpec.describe ::YourClass do
6
  context 'When your code includes an Analytics.track()' do
7
		context 'when there is no error' do
8
			let(:subject) { described_class.run!() }
9

10
			it 'send event to analytics' do
11
				subject
12

13
				expect(Analytics.test_queue.messages[:all].length).to eq(1)
14
				expect(Analytics.test_queue.messages[:track].length).to eq(1)
15
				expect(Analytics.test_queue.messages[:track].first[:event]).to eq('your event name')
16
			end
17
		end
18
  end
19
end

Note: It is recommended to call reset! before each test to ensure your test queue is empty. For example, in rspec you may have the following:

1
RSpec.configure do |config|
2
  config.before do
3
    Analytics.test_queue.reset!
4
  end
5
end

If you want to see all the methods available in the test queue class check the June Ruby SDK source code