Intercom App

Intercom Application Rails engine and generator

Description

This gem includes a Rails Engine and generators for writing Rails applications using the Intercom API. The Engine provides a SessionsController and all the required code for authenticating with an app via Oauth.

Apply to become an Intercom Developer

To create an Intercom application and get your app_key and app_secret you will need to create an Intercom application first. Once your application is created you can apply for an oauth application in the "App Settings >> Oauth" section.

Installation

To get started create a new rails app :

# Create a new rails app
$ rails new my_intercom_app
$ cd my_intercom_app

Then add intercom-app to your Gemfile and bundle install : gem 'intercom-app' and run :

$ bundle install

Now we are ready to run any of the intercom_app generators. The following section explains the generators and what they can do.

Generators

Default Generator

The default generator will run the install, app_model, and home_controller generators. This is the recommended way to start your app.

$ rails generate intercom_app --app_key <your_app_key> --app_secret <your_app_secret> --oauth_modal true

oauth_modal:

• If true you can authenticate with Intercom using a modal
• If false you can authenticate with Intercom directly from the current tab

Install Generator

$ rails generate intercom_app:install

# or optionally with arguments:

$ rails generate intercom_app:install --app_key <your_app_key> --secret <your_app_secret> --oauth_modal true

You can update any of these settings later on easily, the arguments are simply for convenience.

The generator adds IntercomApp and the required initializers to the host Rails application.

After running the install generator, you can start your app with bundle exec rails server and install your app by visiting localhost.

App Model Generator

$ rails generate intercom_app:app_model

The install generator doesn't create any database models for you and if you are starting a new app its quite likely that you will want one (most of our internally developed apps do!). This generator creates a simple app model and a migration. It also creates a model called SessionStorage which interacts with IntercomApp::SessionRepository. Check out the later section to learn more about IntercomApp::SessionRepository

Note that you will need to run rake db:migrate after this generator

Home Controller Generator

$ rails generate intercom_app:home_controller

This generator creates an example home controller that is retrieving your user list and displays your users names.

Controllers, Routes and Views

The last group of generators are for your convenience if you want to start overriding code included as part of the Rails engine. For example by default the engine provides a simple SessionController, if you run the rails generate intercom_app:controllers generator then this code gets copied out into your app so you can start adding to it. Routes and views follow the exact same pattern.

Managing App Keys and Secrets

The install generator places your App credentials directly into the intercom_app initializer which is convenient and fine for development but once your app goes into production your api credentials should not be in source control. When we develop apps we keep our keys in environment variables so a production intercom_app initializer would look like this:

IntercomApp.configure do |config|
  config.api_key = ENV['INTERCOM_CLIENT_APP_KEY']
  config.secret = ENV['INTERCOM_CLIENT_APP_SECRET']
  config.oauth_modal = false
end

Connect to the Intercom API

This gem includes the following libraries :

http://github.com/intercom/omniauth-intercom <= Simple rake middleware to authenticate your customers with Intercom http://github.com/intercom/intercom-ruby <= Intercom Ruby API wrapper