togglehq

Add this line to your application's Gemfile:

gem 'togglehq'

And then execute:

$ bundle

Or install it yourself as:

$ gem install togglehq

require 'togglehq'

Togglehq.configure do |config|
  # These should be set to the "Master OAuth" client id and client secret
  # for your app from the ToggleHQ dashboard
  config.client_id = ENV['TOGGLEHQ_CLIENT_ID']
  config.client_secret = ENV['TOGGLEHQ_CLIENT_SECRET']

  # To log the HTTP requests/responses to and from the ToggleHQ API, set log_requests to true (defaults to false)
  config.log_requests = true

  # To modify the adapter used for network connections (defaults to :net_http_persistent)
  # Available: [:net_http, :net_http_persistent, :excon, :typhoeus, :patron, :em_http, :httpclient]
  config.adapter = :net_http
end

Create a user for your app

user = Togglehq::User.new(:identifier => "abcdef0123456789")
user.save

Find an existing user for your app

user = Togglehq::User.find_by_identifier("abcdef0123456789")

If a user with the given identifier cannot be found, nil will be returned.

Alternatively, you can call Togglehq::User.find_by_identifier!, which will raise a RuntimeError if the given user cannot be found.

Create a device (usually done via the ToggleHQ SDK)

device = Togglehq::Device.new(:os => "ios", :os_version => 10.0, :manufacturer => "Apple", :model => "iPhone")
device.save

If created successfully, device.uuid will return the unique device identifier.

Enable a device to receive notifications

device = Togglehq::Device.new(:uuid => "123456789")
device.enable!("2b6f0cc4...831186")

Assign a device to a specific user

device = Togglehq::Device.new(:uuid => "123456789")
device.assign!("abcdef0123456789")

Unassign a device from all users

device = Togglehq::Device.new(:uuid => "123456789")
device.unassign!

Get all preference categories and preferences for your app

preferences = Togglehq::Notify::Preferences.all

A Togglehq::Notify::Preferences object has a categories attribute which contains an array of all preference categories:

preferences.categories
 => [{"name"=>"Friends", "key"=>"friends", "preferences"=>[{"name"=>"Friend Request", "key"=>"friend_request", "default"=>true}]}]

Each preference category contains a name, a key, and an array of preferences, which also have a name, key, and default value.

Togglehq::Notify::UserPreferences enapsulates a specific user's notification preferences for your app. Create one by passing a Togglehq::User object:

user_preferences = Togglehq::Notify::UserPreferences.new(user)

Get the user's preferences by calling the categories method:

user_preferences.categories
 => [{"name"=>"Friends", "key"=>"friends", "preferences"=>[{"name"=>"Friend Request", "key"=>"friend_request", "default"=>true, "enabled"=>true}]}]

Like Togglehq::Notify::Preferences, a Togglehq::Notify::UserPreferences object has a categories attribute which contains an array of all preference categories. Each preference category contains a name, a key, and an array of preferences, which also have a name, key, and default value. In addition, each user preference contains an enabled flag, indicating whether the user has enabled that particular preference or not.

Please note that a Togglehq::Notify::UserPreferences object's categories property is memoized when fetched from the ToggleHQ API. To reload the preferences, call the reload! method on the Togglehq::Notify::UserPreferences object:

user_preferences.reload!

Enable a preference for a user

user_preferences.enable_preference!("category_key", "preference_key")

This will return true upon success, and raise a RuntimeError on failure.

Disable a preference for a user

user_preferences.disable_preference!("category_key", "preference_key")

This will return true upon success, and raise a RuntimeError on failure.

To send push notifications, first construct a Togglehq::Notify::Notification object specifying a preference category key, preference key, and message.

notification = Togglehq::Notify::Notification.new(:category_key => "friends", :preference_key => "friend_request", :message => "You have a new friend request!")

To send this notification to a single user:

user = Togglehq::User.find_by_identifier("abc123")
notification.send(user)

This will return true upon success, and raise a RuntimeError on failure.

To send this notification to a batch of users:

user1 = Togglehq::User.new(:identifier => "abc123")
user2 = Togglehq::User.new(:identifier => "def456")
...
userN = Togglehq::User.new(:identifier => "xyz890")

notification.batch_send([user1, user2, ..., user2])

This will return true upon success, and raise a RuntimeError on failure.

To send this notification as a global message to all of the users in your app:

notification.send_global

This will return true upon success, and raise a RuntimeError on failure.

Bug reports and pull requests are welcome on GitHub at https://github.com/togglehq/togglehq-gem.

The gem is available as open source under the terms of the MIT License.