Ruby library

You can use the Outbound Ruby library with your application to send user and event data to Outbound. You can also use it to manage device tokens if you have a mobile app and want to use push notifications.

This document covers the following topics:

You can also examine the library's source code on Github.

Install the Outbound library

$ gem install outbound

If you prefer using bundler, specify the following dependencies in a Gemfile in your project's root:

gem 'outbound', '~> 1.2.0', :require => 'outbound'

Then run bundle to install the gem:

$ bundle install

Include the library in your project

require 'outbound'
require 'logger'

Outbound.init("PRIVATE KEY", Logger::ERROR)

For more information on the private key, see Authentication in the introduction.

Identify a user

Use the Outbound.identify() method to send user data to Outbound. The method takes the following positional arguments:

  • a string containing the user id
  • a hash containing the user attributes. Only the keys in the example below are supported. All are optional

The method returns an Outbound::Result instance. See Get a request's result.

Example
userAttributes = {
  first_name: "Jane",
  last_name: "Doe",
  email: "jdoe@example.com",
  phone_number: "+1 555-123-4567",
  apnsTokens: ["ios device token"],
  gcmTokens: ["android device token"],
  previous_id="anonymous_user_123",
  attributes: {
    :membership_level => "Gold"
  },
  group_id: "group_identifier",
  group_attributes: {
    :some_group_attribute_name => "Loren Ipsum"
  }
}
Outbound.identify("4512345", userAttributes)

For more information about the user attributes, see Users.

Track an event

Use the Outbound.track() method to send event data to Outbound. The method takes the following positional arguments:

  • a string containing the user id
  • a string containing the event name
  • (optional) a hash containing custom event properties. See Properties attribute in the Events documentation

The method returns an Outbound::Result instance. See Get a request's result.

Example
event_properties = {
  :membership_valid => true,
  :membership_renewalDate => "2018-06-12"
}
Outbound.track("4512345", "renewMembership", event_properties)

For more information about the arguments, see Events.

The track() method sends the data to Outbound as soon as it runs, so make sure it has access to the user and event data.

Provide a device token

If you have a mobile app and want to use push notifications in your Outbound campaigns, you must provide the user's APNs (iOS) or GCM (Android) token to Outbound. You can provide the token in one of two ways:

  • Send the user's token when you identify the user, using the apnsTokens or gcmTokens properties in the user hash you pass to the identify() method. See Identify a user above.

  • Use the Outbound.register() method, which takes the following positional arguments:

    • either Outbound.APNS or Outbound.GCM
    • a string containing the user id
    • a string containing the device token
Example
Outbound.register(Outbound.APNS, "4512345", "HjkCGFJA6z...")

The first argument must be either Outbound.APNS or Outbound.GCM.

Disable a device token

Use the Outbound.disable() method if you no longer want to send notifications to the user's device. The method takes the following positional arguments: * either Outbound.APNS or Outbound.GCM * a string containing the user id * a string containing the device token

To enable the token again, specify it again in the identify() or register() method.

If you use register() and disable(), Outbound recommendeds not sending any tokens in identify(). This lets you more easily control the state of your tokens.

Example
Outbound.disable(Outbound.GCM, "4512345", "8LAm9ZCAmC...")

The first argument must be either Outbound.APNS or Outbound.GCM.

Get a request's result

Both the identify() and track() methods return an Outbound::Result instance that has the following attributes:

  • error - either nil or a string error message
  • received_call - a boolean indicating whether or not Outbound received the HTTP request
  • success? - a method that returns true if the request was received by Outbound and did not have any errors
  • ? - a method available for each different error type