# 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. 

### Disabling automatic insertion

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

```ruby
  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`:

```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 %>
```
## 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.