Comufy is an add-on for providing a programmer friendly API for connecting Heroku applications with the Comufy Social Suite.
The Comufy Social Suite delivers direct, personalised notifications at scale, with relevant content, targeted by user profile and behaviour, with complete attribution of results.
By adding Comufy to your application you will have the Comufy Service Suite available and functional at almost no development costs. The Comufy addon provides the tools to push your collected data to Comufy's Service Suite, providing you with their excellent data analysis and targeted messaging to get the most out of your Facebook applications and users.
Comufy is accessible via an API and has supported client libraries for Ruby, Python and PHP.
Comufy can be attached to a Heroku application via the CLI:
:::term
$ heroku addons:add comufy
-----> Adding comufy to sharp-mountain-4005... done, v18 (free)
Once Comufy has been added a COMUFY_TOKEN setting will be available in the app configuration and will contain the
access token required to authenticate you with Comufy's Service Suite. This can be confirmed using the
heroku config:get command.
:::term
$ heroku config:get COMUFY_TOKEN
Xcs6CzHvoexzQuLT1BkTo81cq0ZKFMDwQEmP91gVUw
There are also a number of other settings provided, which can be shown with the same heroku config:get command.
:::term
$ heroku config | grep COMUFY_*
COMUFY_TOKEN: Xcs6CzHvoexzQuLT1BkTo81cq0ZKFMDwQEmP91gVUw
COMUFY_URL: https://comufy.herokuapp.com/xcoreweb/client
After installing Comufy the application should be configured to fully integrate with the add-on.
After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.
Use Foreman to reliably configure and run the process formation specified in your app’s
Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the
COMUFY_TOKEN values retrieved from heroku config to .env.
:::term
$ heroku config -s | grep COMUFY_TOKEN >> .env
$ heroku config -s | grep COMUFY_URL >> .env
$ more .env
Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: `echo .env >> .gitignore`.
The easiest way to add Comufy support is by importing the Comufy Javascript library. This can be done in 3 quick steps:
-
Get your Comufy domain name by opening the Comufy dashboard either through your applications control panel on heroku or by running this on the command line:
:::term $ heroku addons:open comufy Opening comufy for sharp-mountain-4005…
Once the dashboard is open, you will have your domain name listed after the @ sign on the top right of the dashboard (it will look something like this: app5433422
-
Register your facebook application with Comufy:
:::term $ gem 'comufyrails' $ rake comufy:app["MY_APPLICATION_NAME","APP_ID","APP_SECRET","Description of my application"]
Where MY_APPLICATION_NAME is a name you would like to your facebook application for use inside the comufy dashboard. The APP_ID and APP_SECRET are given to you by facebook in your facebook applications configuration screen.
-
Include the javascript library:
:::html
<script src="https://social.comufy.com/static/general/js/lib/tracker.js?domain=my_domain_name&appId=facebook_app_id&autostore=true" type="text/javascript"></script>
where my_domain_name is the domain name from step 1, and facebook_app_id is the app id you got from facebook.
Commit and push that code change, and you should start to see your users showing up in the Comufy dashboard!
Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Comufy client library.
:::ruby
gem 'comufyrails'
Update application dependencies with bundler.
:::term
$ bundle install
As this gem uses EventMachine to perform asynchronous methods you need to use a web server that supports EventMachine, such as thin.
The gem requires configuration before being used. To get these values you must create an account with Comufy through our Heroku service, or by yourself.
On Heroku you should add the Comufy add-on and follow the configuration steps it gives you. This will automatically set the environment variables for your Comufy account that this gem will use. If you are not using our Heroku service you will need to find another way to get these values, listed below.
If you are using this on your local development machine or elsewhere you have two ways to configure this gem. You can get these values by using this heroku command below and looking for all values starting with 'COMUFY_'.
:::term
$ heroku config | grep COMUFY
COMUFY_TOKEN: Your Access Token
COMUFY_URL: The URL you use to access Comufys API
COMUFY_APP_NAME: Your Facebook Application Name
Please note that COMUFY_APP_NAME will not be present when you first add Comufy, so you should follow the steps below to create and specify the application name.
If you do not already have a Comufy application setup you need to before you can start to use this gem.
First you should register your Facebook application and get the Facebook ID and Facebook secret of the application. You will use these in the rake method below to register the application with Comufy. On success of this you can write the name of your application in the manners shown further below.
:::term
rake comufy:app["MY_APPLICATION_NAME","APP_ID","APP_SECRET","Description of my application"]
You can set the values in your config/environments/*.rb in the same manner you set rails-specific values.
:::ruby
config.comufy_rails.app_name = 'YOUR_APPLICATION_NAME'
config.comufy_rails.access_token = 'YOUR_ACCESS_TOKEN'
config.comufy_rails.url = 'COMUFY'
Alternatively you can set these in your environment/path.
COMUFY_APP_NAME - Application name on Comufy, defaults to your Ruby on Rails application name.
COMUFY_TOKEN - Token given to you by our Comufy Heroku service or from Comufy directly.
COMUFY_URL - Full HTTP address to connect to, defaults to our service.
In its current iteration you can use this gem to send information to Comufy, allowing you to add users, update data on the users and send messages/notifications to your users via your own service.
If you have your own user database, and wish to keep the Comufy database in sync with it, you can use the observer behaviour for your model and asynchronously send the data to Comufy.
:::ruby
class UserObserver < ActiveRecord::Observer
def after_save(user)
data = { dob: user.dob.to_comufy_time, fact: user.fact }
Comufyrails::Connection.store_user(user.facebook_id, data)
end
end
Or you can place the code in your controllers. As this method is asynchronous it will not block and affect performance. It should be noted that these methods return their results to the logs.
:::ruby
# POST /users
# POST /users.json
def create
@user = User.new(params[:user])
respond_to do |format|
if @user.save
Comufyrails::Connection.store_user(user.facebook_id, { dob: user.dob.to_comufy_time, fact: user.fact })
format.html { redirect_to @user, notice: 'User was successfully created.' }
format.json { render json: @user, status: :created, location: @user }
else
format.html { render action: "new" }
format.json { render json: @user.errors, status: :unprocessable_entity }
end
end
end
There are also a number of methods that are added to your rake environment, for one-time actions. These include the ability to add/remove tags for users of your applications.
:::term
$ bundle exec rake comufy:tag["DOB","DATE"]
This will run a blocking call to register this tag with your application, informing you if it was successful or not. It will use the configuration exactly as your Rails application will, so if you need to run it as production, you merely have to add RAILS_ENV=production or -e production.
Ruby applications will need to add the following entry into their Gemfile specifying the Comufy client library.
:::ruby
gem 'comufy'
Update application dependencies with bundler.
:::term
$ bundle install
Or if they are not using bundler they should install the gem.
:::term
$ gem install comufy
###Usage
Comufy uses synchronous calls to connect and push data to Comufy's Service Suite. Below is an example of connecting to our servers and sending a Facebook user, along with a tags to set or update.
:::ruby
require 'comufy'
connect = Comufy.connect(access_token: ENV["COMUFY_ACCESS_TOKEN"], expiry_token: Time.now.to_i + 1000000)
# or use a yaml file
# connect = Comufy.connect(yaml: "path/to/yaml/file")
# lets add a user to our facebook application!
# http://graph.facebook.com/THEIR_NAME will get you back their id
# tags are the data fields to enter for this user.
app_name = "NAME_OF_YOUR_APPLICATION"
user_id = "THEIR_FACEBOOK_ID"
tags = { 'dob' => '1978-10-01 19:50:48' }
# will return true when successful, otherwise it'll return false along with a logger.warn message!
puts connect.store_user(app_name, user_id, tags)
The Python library is available from GitHub at python-comufy.
You can install it using pip.
:::term
$ pip install git+https://github.com/ddimmich/python-comufy.git
After installation you should add this line into your requirements.txt for heroku;
git+git://github.com/ddimmich/python-comufy.git.
Below is an example of how to import and use the library to get the current list of tags and add a user.
:::python
from comufy import Comufy
import os
import datetime
example = Comufy()
example.access_token = os.environ.get('COMUFY_TOKEN')
example.expiry_time = datetime.datetime.now() + datetime.timedelta(days=5)
example.base_api_url = os.environ.get('COMUFY_URL')
facebook_id = THEIR_FACEBOOK_ID # http://graph.facebook.com/THEIR_URL_NAME
print example.access_token
print example.expiry_time
print example.base_api_url
print example.get_application_tags('ComufyRailsTest')
print example.add_application_user('ComufyRailsTest', {'account': {'fbId': facebook_id},'tags': {'fact': "fun guy!"}})
The PHP library is available from GitHub at php-comufy
Full documentation is here
TODO: Provide examples of how to use this service with PHP
The Comufy dashboard allows you to see a limited subset of Comufy's Service Suite behaviour. It is often a good idea to use this for development, using a testing Facebook application and this dashboard to check everything is working properly.
The dashboard can be accessed via the CLI:
:::term
$ heroku addons:open comufy
Opening comufy for sharp-mountain-4005…
or by visiting the Heroku apps web interface and selecting the application in question. Select Comufy from the Add-ons menu.
TODO: Add in troubleshooting tips/tricks/suggestions/links
If [[feature X]] does not seem to be [[common issue Y]] then [[add specific commands to look for symptoms of common issue Y]].
Use the heroku addons:upgrade command to migrate to a new plan.
:::term
$ heroku addons:upgrade comufy:newplan
-----> Upgrading comufy:newplan to sharp-mountain-4005... done, v18 ($49/mo)
Your plan has been updated to: comufy:newplan
Comufy can be removed via the CLI.
:::term
$ heroku addons:remove comufy
-----> Removing comufy from sharp-mountain-4005... done, v20 (free)
TODO: create email address [email protected]
All Comufy support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at [email protected].