@segment/analytics-browser-actions-intercom 1.0.0

package/src/identifyUser/index.ts

@@ -0,0 +1,237 @@
+import { InputField } from '@segment/actions-core'
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import { Intercom } from '../api'
+import type { Settings } from '../generated-types'
+import { getCompanyProperties } from '../sharedCompanyProperties'
+import { convertDateToUnix, filterCustomTraits, getWidgetOptions, isEmpty } from '../utils'
+import type { Payload } from './generated-types'
+
+const companyProperties: Record<string, InputField> = getCompanyProperties()
+
+const action: BrowserActionDefinition<Settings, Intercom, Payload> = {
+  title: 'Identify User',
+  description: 'Create or update a user in Intercom.',
+  defaultSubscription: 'type = "identify" or type = "page"',
+  platform: 'web',
+  fields: {
+    user_id: {
+      description: 'A unique identifier for the user.',
+      label: 'User ID',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    custom_traits: {
+      description: "The user's custom attributes.",
+      label: 'Custom Attributes',
+      type: 'object',
+      required: false,
+      defaultObjectUI: 'keyvalue'
+    },
+    name: {
+      description: "The user's name.",
+      label: 'Name',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.name'
+      }
+    },
+    phone: {
+      description: "The user's phone number.",
+      label: 'Phone Number',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.phone'
+      }
+    },
+    unsubscribed_from_emails: {
+      description: "The user's email unsubscribe status.",
+      label: 'Unsubscribed From Emails',
+      type: 'boolean',
+      required: false
+    },
+    language_override: {
+      description: "The user's messenger language (instead of relying on browser language settings).",
+      label: 'Language Override',
+      type: 'string',
+      required: false
+    },
+    email: {
+      description: "The user's email address.",
+      label: 'Email Address',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.email'
+      }
+    },
+    created_at: {
+      description: 'The time the user was created in your system.',
+      label: 'User Creation Time',
+      type: 'datetime',
+      required: false,
+      default: {
+        '@if': {
+          exists: { '@path': '$.traits.createdAt' },
+          then: { '@path': '$.traits.createdAt' },
+          else: { '@path': '$.traits.created_at' }
+        }
+      }
+    },
+    avatar_image_url: {
+      description: "The URL for the user's avatar/profile image.",
+      label: 'Avatar',
+      type: 'string',
+      required: false,
+      default: { '@path': '$.traits.avatar' }
+    },
+    user_hash: {
+      description:
+        'The user hash used for identity verification. See [Intercom docs](https://www.intercom.com/help/en/articles/183-enable-identity-verification-for-web-and-mobile) for more information on how to set this field.',
+      label: 'User Hash',
+      type: 'string',
+      required: false,
+      default: {
+        '@if': {
+          exists: { '@path': '$.context.Intercom.user_hash' },
+          then: { '@path': '$.context.Intercom.user_hash' },
+          else: { '@path': '$.context.Intercom.userHash' }
+        }
+      }
+    },
+    company: {
+      description: "The user's company.",
+      label: 'Company',
+      type: 'object',
+      required: false,
+      properties: companyProperties,
+      default: {
+        company_id: { '@path': '$.traits.company.id' },
+        name: { '@path': '$.traits.company.name' },
+        created_at: {
+          '@if': {
+            exists: { '@path': '$.traits.company.createdAt' },
+            then: { '@path': '$.traits.company.createdAt' },
+            else: { '@path': '$.traits.company.created_at' }
+          }
+        },
+        plan: { '@path': '$.traits.company.plan' },
+        size: { '@path': '$.traits.company.size' },
+        website: { '@path': '$.traits.company.website' },
+        industry: { '@path': '$.traits.company.industry' },
+        monthly_spend: { '@path': '$.traits.company.monthly_spend' }
+      }
+    },
+    companies: {
+      description: 'The array of companies the user is associated to.',
+      label: 'Companies',
+      type: 'object',
+      multiple: true,
+      required: false,
+      properties: companyProperties,
+      default: {
+        '@arrayPath': [
+          '$.traits.companies',
+          {
+            company_id: { '@path': '$.id' },
+            name: { '@path': '$.name' },
+            created_at: {
+              '@if': {
+                exists: { '@path': '$.createdAt' },
+                then: { '@path': '$.createdAt' },
+                else: { '@path': '$.created_at' }
+              }
+            },
+            plan: { '@path': '$.plan' },
+            size: { '@path': '$.size' },
+            website: { '@path': '$.website' },
+            industry: { '@path': '$.industry' },
+            monthly_spend: { '@path': '$.monthly_spend' }
+          }
+        ]
+      }
+    },
+    hide_default_launcher: {
+      description:
+        'Selectively show the chat widget. As per [Intercom docs](https://www.intercom.com/help/en/articles/189-turn-off-show-or-hide-the-intercom-messenger), you want to first hide the Messenger for all users inside the Intercom UI using Messenger settings. Then think about how you want to programmatically decide which users you would like to show the widget to.',
+      label: 'Hide Default Launcher',
+      type: 'boolean',
+      required: false,
+      default: {
+        '@if': {
+          exists: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          then: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          else: { '@path': '$.context.Intercom.hide_default_launcher' }
+        }
+      }
+    }
+  },
+  perform: (Intercom, event) => {
+    // remove properties that require extra handling
+    const { custom_traits, avatar_image_url, ...rest } = event.payload
+    const payload = { ...rest }
+
+    // remove company if it is empty
+    if (isEmpty(payload.company?.company_custom_traits)) {
+      delete payload.company?.company_custom_traits
+    }
+    if (isEmpty(payload.company)) {
+      delete payload.company
+    }
+
+    // convert 'created_at' date properties from ISO-8601 to UNIX
+    const companies = Array.isArray(payload.companies) ? [...payload.companies] : []
+    const datesToConvert = [payload, payload.company, ...companies]
+    for (const objectWithDateProp of datesToConvert) {
+      if (objectWithDateProp && objectWithDateProp?.created_at) {
+        objectWithDateProp.created_at = convertDateToUnix(objectWithDateProp.created_at)
+      }
+    }
+
+    // drop custom objects & arrays
+    const filteredCustomTraits = filterCustomTraits(custom_traits)
+
+    // drop custom objects & arrays
+    if (payload.company) {
+      const { company_custom_traits, ...rest } = payload.company
+      const companyFilteredCustomTraits = filterCustomTraits(company_custom_traits)
+      payload.company = { ...rest, ...companyFilteredCustomTraits }
+    }
+
+    // drop custom objects & arrays
+    if (payload.companies) {
+      payload.companies = payload.companies.map((company) => {
+        const { company_custom_traits, ...rest } = company
+        const companyFilteredCustomTraits = filterCustomTraits(company_custom_traits)
+        company = { ...rest, ...companyFilteredCustomTraits }
+        return company
+      })
+    }
+
+    // get user's widget options
+    const widgetOptions = getWidgetOptions(payload.hide_default_launcher, Intercom.activator)
+
+    // create the avatar object
+    let avatar = {}
+    if (avatar_image_url) {
+      avatar = {
+        image_url: avatar_image_url,
+        type: 'avatar'
+      }
+    }
+
+    // API call
+    Intercom('update', {
+      ...payload,
+      ...filteredCustomTraits,
+      ...widgetOptions,
+      ...(!isEmpty(avatar) && { avatar })
+    })
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,109 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { initialBoot, initScript } from './init-script'
+
+import { Intercom } from './api'
+import trackEvent from './trackEvent'
+import identifyUser from './identifyUser'
+import identifyCompany from './identifyCompany'
+import { defaultValues } from '@segment/actions-core'
+
+declare global {
+  interface Window {
+    Intercom: Intercom
+  }
+}
+
+export const destination: BrowserDestinationDefinition<Settings, Intercom> = {
+  name: 'Intercom Web (Actions)',
+  slug: 'actions-intercom-web',
+  mode: 'device',
+  presets: [
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields)
+    },
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify" or type = "page"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields)
+    },
+    {
+      name: 'Identify Company',
+      subscribe: 'type = "group"',
+      partnerAction: 'identifyCompany',
+      mapping: defaultValues(identifyCompany.fields)
+    }
+  ],
+  settings: {
+    appId: {
+      description: 'The app_id of your Intercom app which will indicate where to store any data.',
+      label: 'App ID',
+      type: 'string',
+      required: true
+    },
+    activator: {
+      description:
+        'By default, Intercom will inject their own inbox button onto the page, but you can choose to use your own custom button instead by providing a CSS selector, e.g. #my-button. You must have the "Show the Intercom Inbox" setting enabled for this to work. The default value is #IntercomDefaultWidget.',
+      label: 'Custom Inbox Button Selector',
+      type: 'string',
+      required: false,
+      default: '#IntercomDefaultWidget'
+    },
+    richLinkProperties: {
+      description: 'A list of rich link property keys.',
+      label: 'Rich Link Properties',
+      type: 'string',
+      multiple: true,
+      required: false
+    },
+    apiBase: {
+      description: 'The regional API to use for processing the data',
+      label: 'Regional Data Hosting',
+      type: 'string',
+      choices: [
+        {
+          label: 'US',
+          value: 'https://api-iam.intercom.io'
+        },
+        {
+          label: 'EU',
+          value: 'https://api-iam.eu.intercom.io'
+        },
+        {
+          label: 'Australia',
+          value: 'https://api-iam.au.intercom.io'
+        }
+      ],
+      default: 'https://api-iam.intercom.io',
+      required: false
+    }
+  },
+
+  initialize: async ({ settings }, deps) => {
+    //initialize Intercom
+    initScript({ appId: settings.appId })
+    const preloadedIntercom = window.Intercom
+    initialBoot(settings.appId, { api_base: settings.apiBase })
+
+    await deps.resolveWhen(() => window.Intercom !== preloadedIntercom, 100)
+
+    window.Intercom.richLinkProperties = settings.richLinkProperties
+    window.Intercom.appId = settings.appId
+    window.Intercom.activator = settings.activator
+
+    return window.Intercom
+  },
+
+  actions: {
+    trackEvent,
+    identifyUser,
+    identifyCompany
+  }
+}
+
+export default browserDestination(destination)

package/src/init-script.ts

@@ -0,0 +1,49 @@
+/* eslint-disable */
+// @ts-nocheck
+
+export function initScript({ appId }) {
+  //Set your APP_ID
+  var APP_ID = appId
+  ;(function () {
+    var w = window
+    var ic = w.Intercom
+    if (typeof ic === 'function') {
+      ic('reattach_activator')
+      ic('update', w.intercomSettings)
+    } else {
+      var d = document
+      var i = function () {
+        i.c(arguments)
+      }
+      i.q = []
+      i.c = function (args) {
+        i.q.push(args)
+      }
+      w.Intercom = i
+      var l = function () {
+        var s = d.createElement('script')
+        s.type = 'text/javascript'
+        s.async = true
+        s.src = 'https://widget.intercom.io/widget/' + APP_ID
+        var x = d.getElementsByTagName('script')[0]
+        x.parentNode.insertBefore(s, x)
+      }
+      if (document.readyState === 'complete') {
+        l()
+      } else if (w.attachEvent) {
+        w.attachEvent('onload', l)
+      } else {
+        w.addEventListener('load', l, false)
+      }
+    }
+  })()
+}
+
+export function initialBoot(appId: string, options = {}) {
+  window &&
+    window.Intercom &&
+    window.Intercom('boot', {
+      app_id: appId,
+      ...options
+    })
+}

package/src/sharedCompanyProperties.ts

@@ -0,0 +1,59 @@
+import { InputField } from '@segment/actions-core'
+
+export const getCompanyProperties = (): Record<string, InputField> => ({
+  company_id: {
+    description: 'The unique identifier of the company.',
+    label: 'Company ID',
+    type: 'string',
+    required: true
+  },
+  name: {
+    description: 'The name of the company.',
+    label: 'Company Name',
+    type: 'string',
+    required: true
+  },
+  created_at: {
+    description: 'The time the company was created in your system.',
+    label: 'Company Creation Time',
+    type: 'datetime',
+    required: false
+  },
+  plan: {
+    description: 'The name of the plan you have associated with the company.',
+    label: 'Company Plan',
+    type: 'string',
+    required: false
+  },
+  monthly_spend: {
+    description: 'The monthly spend of the company, e.g. how much revenue the company generates for your business.',
+    label: 'Monthly Spend',
+    type: 'integer',
+    required: false
+  },
+  size: {
+    description: 'The number of employees in the company.',
+    label: 'Company Size',
+    type: 'integer',
+    required: false
+  },
+  website: {
+    description: 'The URL for the company website.',
+    label: 'Company Website',
+    type: 'string',
+    required: false
+  },
+  industry: {
+    description: 'The industry that the company operates in.',
+    label: 'Industry',
+    type: 'string',
+    required: false
+  },
+  company_custom_traits: {
+    description: 'The custom attributes for the company object.',
+    label: 'Company Custom Attributes',
+    type: 'object',
+    required: false,
+    defaultObjectUI: 'keyvalue'
+  }
+})

package/src/trackEvent/__tests__/index.test.ts

@@ -0,0 +1,179 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import intercomDestination, { destination } from '../../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Show',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      event_name: {
+        '@path': '$.event'
+      },
+      event_metadata: {
+        '@path': '$.properties'
+      },
+      revenue: {
+        '@path': '$.properties.revenue'
+      },
+      currency: {
+        '@path': '$.properties.currency'
+      }
+    }
+  }
+]
+
+describe('Intercom.trackEvent', () => {
+  const settings = {
+    appId: 'superSecretAppID'
+  }
+
+  let mockIntercom: jest.Mock<any, any>
+  let trackEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await intercomDestination({
+      ...settings,
+      subscriptions
+    })
+    trackEvent = trackEventPlugin
+
+    mockIntercom = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithProps = Object.assign(mockIntercom as any, settings)
+      return Promise.resolve(mockedWithProps)
+    })
+    await trackEvent.load(Context.system(), {} as Analytics)
+  })
+
+  test('maps custom traits correctly', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'surfboard-bought',
+      properties: {
+        surfer: 'kelly slater'
+      }
+    })
+    await trackEvent.track?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('trackEvent', 'surfboard-bought', {
+      surfer: 'kelly slater'
+    })
+  })
+
+  test('maps price correctly', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'surfboard-bought',
+      properties: {
+        revenue: 100,
+        currency: 'USD'
+      }
+    })
+    await trackEvent.track?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('trackEvent', 'surfboard-bought', {
+      price: {
+        amount: 10000,
+        currency: 'USD'
+      }
+    })
+  })
+
+  test('currency defaults to USD if omitted', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'surfboard-bought',
+      properties: {
+        revenue: 100
+      }
+    })
+    await trackEvent.track?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('trackEvent', 'surfboard-bought', {
+      price: {
+        amount: 10000,
+        currency: 'USD'
+      }
+    })
+  })
+
+  test('drops arrays or objects in properties', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'surfboard-bought',
+      properties: {
+        surfer: 'kelly slater',
+        dropMe: {
+          foo: 'bar',
+          ahoy: {
+            okay: 'hello'
+          }
+        },
+        arr: ['hi', 'sup', 'yo']
+      }
+    })
+
+    await trackEvent.track?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('trackEvent', 'surfboard-bought', {
+      surfer: 'kelly slater'
+    })
+  })
+})
+
+describe('Intercom.trackEvent with rich link properties', () => {
+  const settings = {
+    appId: 'superSecretAppID',
+    richLinkProperties: ['article']
+  }
+
+  let mockIntercom: jest.Mock<any, any>
+  let trackEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await intercomDestination({
+      ...settings,
+      subscriptions
+    })
+    trackEvent = trackEventPlugin
+
+    mockIntercom = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithProps = Object.assign(mockIntercom as any, settings)
+      return Promise.resolve(mockedWithProps)
+    })
+    await trackEvent.load(Context.system(), {} as Analytics)
+  })
+
+  test('rich link properties are permitted', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'surfboard-bought',
+      properties: {
+        surfer: 'kelly slater',
+        dropMe: {
+          foo: 'bar'
+        },
+        article: {
+          url: 'im a link',
+          value: 'hi'
+        }
+      }
+    })
+
+    await trackEvent.track?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('trackEvent', 'surfboard-bought', {
+      surfer: 'kelly slater',
+      article: {
+        url: 'im a link',
+        value: 'hi'
+      }
+    })
+  })
+})

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,22 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event.
+   */
+  event_name: string
+  /**
+   * The amount associated with a purchase. Segment will multiply by 100 as Intercom requires the amount in cents.
+   */
+  revenue?: number
+  /**
+   * The currency of the purchase amount. Segment will default to USD if revenue is provided without a currency.
+   */
+  currency?: string
+  /**
+   * Optional metadata describing the event.
+   */
+  event_metadata?: {
+    [k: string]: unknown
+  }
+}