togglehq
Installation
Add this line to your application's Gemfile:
gem 'togglehq'
And then execute:
$ bundle
Or install it yourself as:
$ gem install togglehq
Configuration
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
end
Usage
Users
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.
ToggleHQ Notify Usage
Preferences
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.
User Preferences
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.
Notifications
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.
Gotchas
If you encounter SSL errors while using the togglehq-gem similar to the following:
Faraday::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
ToggleHQ's SSL certificate is issued by Comodo. Comodo recently added a new certificate root, which may not be in your Ruby/OpenSSL trusted root certificates file. To find the location of your root file:
require 'openssl'
puts OpenSSL::X509::DEFAULT_CERT_FILE
This will output something like /usr/local/etc/openssl/cert.pem
. Open this file, and add the "Comodo RSA Certification Authority (SHA-2)"" root cert PEM found here to this file.
For more gory details, see this excellent blog post and this StackOverflow question.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/togglehq/togglehq-gem.
License
The gem is available as open source under the terms of the MIT License.