IntercomRails

The easiest way to install Intercom in a rails app.

For interacting with the Intercom REST API, use the intercom gem (https://github.com/intercom/intercom-ruby)

Installation

Add this to your Gemfile:

gem "intercom-rails"

Then run:

bundle install

Take note of your app_id from here and generate a config file:

rails generate intercom:config YOUR-APP-ID

To make installing Intercom as easy as possible, where possible a <script> tag will be automatically inserted before the closing </body> tag. For most Rails apps, you won't need to do any extra config. Having trouble? Check out troubleshooting below.

Disabling automatic insertion

To disable automatic insertion for a particular controller or action you can:

  skip_after_filter :intercom_rails_auto_include

Troubleshooting

If it's not working make sure:

• You've generated a config file with your app_id as detailed above.
• Your user object responds to an id or email method.
• Your current user is accessible in your controllers as current_user or @user, if not in config/initializers/intercom.rb:

  config.user.current = Proc.new { current_user_object }

Feel free to mail us: [email protected], if you're still having trouble.

Configuration

API Secret

If you want to use secure mode, ensure you set your API secret in config/initializers/intercom.rb:

  config.api_secret = '123456'

Custom Data

Custom data lets you associate any data, specific to your app, with a user in Intercom. For custom data variables you want updated on every request set them in config/initializers/intercom.rb.

You can give either a:

• Proc which will be passed the current user object
• Or, a method which will be sent to the current user object

to generate the values of the custom data:

  config.user.custom_data = {
    :plan => Proc.new { |user| user.plan.name },
    :is_paid => Proc.new { |user| user.plan.present? },
    :email_verified => :email_verified?
  }

In some situations you'll want to set some custom data specific to a request. You can do this using the intercom_custom_data helper available in your controllers:

class AppsController < ActionController::Base
  def activate
    intercom_custom_data.user[:app_activated_at] = Time.now
    ...
  end

  def destroy
    intercom_custom_data.user[:app_deleted_at] = Time.now
    ...
  end
end

Attributes must be accessible in order to sync with intercom. Additionally, attributes ending in "_at" will be parsed as times.

Inbox

Intercom includes an inbox which allows a user to read their past conversations with your app, and start new conversations. It's hidden by default, you can include a link to open it by adding a line to config/initializers/intercom.rb:

To use the default link style, which requires no extra config and includes a small question mark icon in the bottom right corner of your app:

  config.inbox.style = :default

If you want to customize the style of the link that opens the inbox:

  config.inbox.style = :custom

This option attaches the inbox open event to the click event of an element with an id of Intercom. So the simplest option here would be to add something like the following to your layout:

  <a id="Intercom">Support</a>

You can read more about configuring the Inbox within Intercom (Config menu -> Inbox Link).

Environments

By default Intercom will be automatically inserted in all Rails environments. If you would like to specify the environments in which Intercom should be inserted, you can do so as follows:

  config.enabled_environments = ["production"]

Manually Inserting the Intercom Javascript

Some situations may require manually inserting the Intercom script tag. If you simply wish to place the Intercom javascript in a different place within the page or, on a page without a closing </body> tag:

  <%= intercom_script_tag %>

This will behave exactly the same as the default auto-install. If for whatever reason you can't use auto-install, you can also provide a hash of user data as the first argument:

<% if logged_in? %>
  <%= intercom_script_tag({
    :app_id => 'your-app-id',
    :user_id => current_user.id,
    :email => current_user.email,
    :name => current_user.name,
    :created_at => current_user.created_at,
    :custom_data => {
      'plan' => current_user.plan.name
    }
  }) %>
<% end %>

You can also override IntercomRails::Config options such as your api_secret, or widget configuration with a second hash:

<% if logged_in? %>
  <%= intercom_script_tag({
    :app_id => 'your-app-id',
    :user_id => current_user.id,
    :email => current_user.email,
    :name => current_user.name,
    :created_at => current_user.created_at
  }, {
    :secret => 'your-apps-api-secret',
    :widget => {:activator => '#Intercom'}
  }) %>
<% end %>

Importing your users

To get started faster with Intercom, IntercomRails includes a Rake task that will do an initial import of your users:

rake intercom:import

Any custom data defined in config/initializers/intercom.rb will also be sent.

Contributors

• Dr Nic Williams (@drnic) - provided a rails generator for adding the Intercom javascript tag into your layout.
• Alexander Chaychuk (@sashich) - fixed bug in user detection when users not persisted (e.g. new session view with devise).

License

Copyright (c) 2011-2012 Intercom, Inc. All rights reserved.