intercom-connector

This connector provides an integration with the Intercom Javascript API. It runs a saga listening to relevant redux actions and notifies Intercom about the changes.

The Intercom Javascript API tracks our users and provides an on-site messenger:

Installation

Add the private registry:

echo "@doodle:registry=https://npm.fury.io/tmf/" >> .npmrc

Add the package to your package.json:

yarn add --exact @doodle/intercom-connector

Initial setup

1. Include the EJS snippet before </body>

   <%- include(`${nodeModulesPath}/@doodle/intercom-connector/views/init.ejs`); %>
   

   In your view rendering, provide intercomAppId:

   res.render('index', {
     intercomAppId: process.env.INTERCOM_APP_ID,
     env: {
         // ... other env vars
         INTERCOM_APP_ID: process.env.INTERCOM_APP_ID,
     },
   

   In your webpack config:

   new webpack.DefinePlugin({
     'process.env': {
        // ... other env vars
        INTERCOM_APP_ID: 'window.__env__.INTERCOM_APP_ID',
     },
   }),
   

2. Call the saga: client.js:

   store.runRootSaga({
     // ... other saga settings
     intercom: {
       intercomAppId: process.env.INTERCOM_APP_ID,
     },
   });
   

   In your root reducer:

   import { createReducer as createIntercomReducer } from '@doodle/intercom-connector';
   
   export default function createReducer(injectedReducers = {}) {
     return combineReducers({
       // other reducers
       ...createIntercomReducer(),
     });
   }
   

   In your root saga:

   import { loadIntercomSaga } from '@doodle/intercom-connector';
   
   export default function* rootSaga(options = {}, history) {
     yield all([
       // ... other sagas
       call(loadIntercomSaga, options.intercom),
     ]);
   }
   

   Note

   This saga will wait for the user to be loaded, if it hasn't yet, through users api connector effects. Commonly, that happens by a call to the action loadUser provided by that connector as early as an authenticated user has opened the Frontend that is using this library.

   This library does not call loadUser.

3. Add the Intercom App ID to the environment .env:

   INTERCOM_APP_ID=abcdef
   

   Also update this in the configmap in web-charts.

Communicate with Intercom

Track events

import { trackEvent } from '@doodle/intercom-connector';
// Or: import { trackEvent } from '@doodle/intercom/state/actions';

// in your saga:
export function* onMyTrackedAction(options) {
  ...
  yield put(
    trackEvent('event.name', {
      metadata_key: 'some value'
    })
  );
}

Update user attributes

When loaded the Intercom Connector saga updates the following user attributes for tracking:

{
  user_id: '',
  user_hash: '',
  email: '',
  name: '',
  language: '',
  avatar: {
    type: '',
    image_url: '',
  },
}

To update any of those or track custom user ones always include both user_id and email fields in the call to the update action creator:

import { update as intercomUpdate } from '@doodle/intercom-connector';
// Or: import { update as intercomUpdate } from '@doodle/intercom-connector/state/actions';

// in your saga:
export function* onMyTrackedAction(options) {
  ...
  yield put(
    intercomUpdate({
      user_id: yield select(getUserId),
      email: yield select(getUserEmail),
      customAttr: yield select(getCustomAttr),
    })
  );
}

Publishing this package

1. Login to private npm registry:

npm login
#Username: tmf
#Password:
#Email: (this IS public) tmf@doodle.com

1. After bumping version in package.json, build the distributed version of the package:

yarn build

1. Finally, publish the new built version:

npm publish dist