# 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: ```ruby gem "intercom-rails" ``` Then run: ``` bundle install ``` Take note of your `app_id` from [here](https://www.intercom.io/apps/api_keys) 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. To disable automatic insertion for a particular controller or action you can: ```ruby skip_after_filter IntercomRails::AutoIncludeFilter ``` ### 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`: ```ruby config.user.current = Proc.new { current_user_object } ``` Feel free to mail us: team@intercom.io, 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`: ```ruby 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: ```ruby 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: ```ruby 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 ``` ### 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: ```ruby config.inbox.style = :default ``` If you want to customize the style of the link that opens the inbox: ```ruby 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: ```html <a id="#Intercom">Support</a> ``` You can read more about configuring the Inbox within Intercom (Config menu -> Inbox Link). ### 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: ```erb <%= 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: ```erb <% 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: ```erb <% 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 %> ``` The `intercom:install` rails generator will add the `intercom_script_tag` to your application layout: ``` rails g intercom:install YOUR-APP-ID ``` ## 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.