@segment/analytics-browser-actions-fullstory 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@segment/analytics-browser-actions-fullstory",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "./dist/cjs",
+  "module": "./dist/esm",
+  "scripts": {
+    "build": "yarn build:esm && yarn build:cjs",
+    "build:cjs": "tsc --module commonjs --outDir ./dist/cjs",
+    "build:esm": "tsc --outDir ./dist/esm"
+  },
+  "typings": "./dist/esm",
+  "dependencies": {
+    "@fullstory/browser": "^1.4.9",
+    "@segment/actions-core": "^3.71.0",
+    "@segment/browser-destination-runtime": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/fullstory.test.ts

@@ -0,0 +1,205 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import fullstory, { destination } from '..'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+const example: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  {
+    partnerAction: 'identifyUser',
+    name: 'Identify User',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      anonymousId: {
+        '@path': '$.anonymousId'
+      },
+      userId: {
+        '@path': '$.userId'
+      },
+      email: {
+        '@path': '$.traits.email'
+      },
+      traits: {
+        '@path': '$.traits'
+      },
+      displayName: {
+        '@path': '$.traits.name'
+      }
+    }
+  }
+]
+
+test('can load fullstory', async () => {
+  const [event] = await fullstory({
+    orgId: 'thefullstory.com',
+    subscriptions: example
+  })
+
+  jest.spyOn(destination.actions.trackEvent, 'perform')
+  jest.spyOn(destination, 'initialize')
+
+  await event.load(Context.system(), {} as Analytics)
+  expect(destination.initialize).toHaveBeenCalled()
+
+  const ctx = await event.track?.(
+    new Context({
+      type: 'track',
+      properties: {
+        banana: '📞'
+      }
+    })
+  )
+
+  expect(destination.actions.trackEvent.perform).toHaveBeenCalled()
+  expect(ctx).not.toBeUndefined()
+
+  const scripts = window.document.querySelectorAll('script')
+  expect(scripts).toMatchInlineSnapshot(`
+    NodeList [
+      <script
+        crossorigin="anonymous"
+        src="https://edge.fullstory.com/s/fs.js"
+      />,
+      <script>
+        // the emptiness
+      </script>,
+    ]
+  `)
+})
+
+describe('#track', () => {
+  it('sends record events to fullstory on "event"', async () => {
+    const [event] = await fullstory({
+      orgId: 'thefullstory.com',
+      subscriptions: example
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+    const fs = jest.spyOn(window.FS, 'event')
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!',
+        properties: {
+          banana: '📞'
+        }
+      })
+    )
+
+    expect(fs).toHaveBeenCalledWith(
+      'hello!',
+      {
+        banana: '📞'
+      },
+      'segment-browser-actions'
+    )
+  })
+})
+
+describe('#identify', () => {
+  it('should default to anonymousId', async () => {
+    const [_, identifyUser] = await fullstory({
+      orgId: 'thefullstory.com',
+      subscriptions: example
+    })
+
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const fs = jest.spyOn(window.FS, 'setUserVars')
+    const fsId = jest.spyOn(window.FS, 'identify')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        anonymousId: 'anon',
+        traits: {
+          testProp: false
+        }
+      })
+    )
+
+    expect(fs).toHaveBeenCalled()
+    expect(fsId).not.toHaveBeenCalled()
+    expect(fs).toHaveBeenCalledWith({ segmentAnonymousId_str: 'anon', testProp: false }, 'segment-browser-actions')
+  }),
+    it('should send an id', async () => {
+      const [_, identifyUser] = await fullstory({
+        orgId: 'thefullstory.com',
+        subscriptions: example
+      })
+      await identifyUser.load(Context.system(), {} as Analytics)
+      const fsId = jest.spyOn(window.FS, 'identify')
+
+      await identifyUser.identify?.(new Context({ type: 'identify', userId: 'id' }))
+      expect(fsId).toHaveBeenCalledWith('id', {}, 'segment-browser-actions')
+    }),
+    it('should camelCase custom traits', async () => {
+      const [_, identifyUser] = await fullstory({
+        orgId: 'thefullstory.com',
+        subscriptions: example
+      })
+      await identifyUser.load(Context.system(), {} as Analytics)
+      const fsId = jest.spyOn(window.FS, 'identify')
+
+      await identifyUser.identify?.(
+        new Context({
+          type: 'identify',
+          userId: 'id',
+          traits: {
+            'not-cameled': false,
+            'first name': 'John',
+            lastName: 'Doe'
+          }
+        })
+      )
+      expect(fsId).toHaveBeenCalledWith(
+        'id',
+        { notCameled: false, firstName: 'John', lastName: 'Doe' },
+        'segment-browser-actions'
+      )
+    })
+
+  it('can set user vars', async () => {
+    const [_, identifyUser] = await fullstory({
+      orgId: 'thefullstory.com',
+      subscriptions: example
+    })
+
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const fs = jest.spyOn(window.FS, 'setUserVars')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        traits: {
+          name: 'Hasbulla',
+          email: 'thegoat@world',
+          height: '50cm'
+        }
+      })
+    )
+
+    expect(fs).toHaveBeenCalledWith(
+      {
+        displayName: 'Hasbulla',
+        email: 'thegoat@world',
+        height: '50cm',
+        name: 'Hasbulla'
+      },
+      'segment-browser-actions'
+    )
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,16 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The organization ID for FullStory.
+   */
+  orgId: string
+  /**
+   * Enables FullStory debug mode.
+   */
+  debug?: boolean
+  /**
+   * Enables FullStory inside an iframe.
+   */
+  recordOnlyThisIFrame?: boolean
+}

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,26 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's id
+   */
+  userId?: string
+  /**
+   * The user's anonymous id
+   */
+  anonymousId?: string
+  /**
+   * The user's display name
+   */
+  displayName?: string
+  /**
+   * The user's email
+   */
+  email?: string
+  /**
+   * The Segment traits to be forwarded to FullStory
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,123 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { FS } from '../types'
+import camelCase from 'lodash/camelCase'
+import { segmentEventSource } from '..'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, FS, Payload> = {
+  title: 'Identify User',
+  description: 'Sets user identity variables',
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: false,
+      description: "The user's id",
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    anonymousId: {
+      type: 'string',
+      required: false,
+      description: "The user's anonymous id",
+      label: 'Anonymous ID',
+      default: {
+        '@path': '$.anonymousId'
+      }
+    },
+    displayName: {
+      type: 'string',
+      required: false,
+      description: "The user's display name",
+      label: 'Display Name',
+      default: {
+        '@path': '$.traits.name'
+      }
+    },
+    email: {
+      type: 'string',
+      required: false,
+      description: "The user's email",
+      label: 'Email',
+      default: {
+        '@path': '$.traits.email'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'The Segment traits to be forwarded to FullStory',
+      label: 'Traits',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (FS, event) => {
+    let newTraits: Record<string, unknown> = {}
+
+    if (event.payload.traits) {
+      newTraits = Object.entries(event.payload.traits).reduce(
+        (acc, [key, value]) => ({
+          ...acc,
+          [camelCaseField(key)]: value
+        }),
+        {}
+      )
+    }
+
+    if (event.payload.anonymousId) {
+      newTraits.segmentAnonymousId_str = event.payload.anonymousId
+    }
+
+    if (event.payload.userId) {
+      FS.identify(event.payload.userId, newTraits, segmentEventSource)
+    } else {
+      FS.setUserVars({
+        ...newTraits,
+        ...(event.payload.email !== undefined && { email: event.payload.email }),
+        ...(event.payload.displayName !== undefined && { displayName: event.payload.displayName })
+      }, segmentEventSource)
+    }
+  }
+}
+
+/**
+ * Camel cases `.`, `-`, `_`, and white space within fieldNames. Leaves type suffix alone.
+ *
+ * NOTE: Does not fix otherwise malformed fieldNames.
+ * FullStory will scrub characters from keys that do not conform to /^[a-zA-Z][a-zA-Z0-9_]*$/.
+ *
+ * @param {string} fieldName
+ */
+function camelCaseField(fieldName: string) {
+  // Do not camel case across type suffixes.
+  const parts = fieldName.split('_')
+  if (parts.length > 1) {
+    const typeSuffix = parts.pop()
+    switch (typeSuffix) {
+      case 'str':
+      case 'int':
+      case 'date':
+      case 'real':
+      case 'bool':
+      case 'strs':
+      case 'ints':
+      case 'dates':
+      case 'reals':
+      case 'bools':
+        return camelCase(parts.join('_')) + '_' + typeSuffix
+      default: // passthrough
+    }
+  }
+
+  // No type suffix found. Camel case the whole field name.
+  return camelCase(fieldName)
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,71 @@
+import type { FS } from './types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { FSPackage } from './types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import type { Settings } from './generated-types'
+import trackEvent from './trackEvent'
+import identifyUser from './identifyUser'
+import viewedPage from './viewedPage'
+import { defaultValues } from '@segment/actions-core'
+
+declare global {
+  interface Window {
+    FS: FS
+  }
+}
+
+export const segmentEventSource = 'segment-browser-actions'
+
+export const destination: BrowserDestinationDefinition<Settings, FS> = {
+  name: 'Fullstory (Actions)',
+  slug: 'actions-fullstory',
+  mode: 'device',
+  presets: [
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields)
+    },
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields)
+    }
+  ],
+  settings: {
+    orgId: {
+      description: 'The organization ID for FullStory.',
+      label: 'FS Org',
+      type: 'string',
+      required: true
+    },
+    debug: {
+      description: 'Enables FullStory debug mode.',
+      label: 'Debug mode',
+      type: 'boolean',
+      required: false,
+      default: false
+    },
+    recordOnlyThisIFrame: {
+      description: 'Enables FullStory inside an iframe.',
+      label: 'Capture only this iFrame',
+      type: 'boolean',
+      required: false,
+      default: false
+    }
+  },
+  actions: {
+    trackEvent,
+    identifyUser,
+    viewedPage
+  },
+  initialize: async ({ settings }, dependencies) => {
+    FSPackage.init(settings)
+    await dependencies.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'FS'), 100)
+    return window.FS
+  }
+}
+
+export default browserDestination(destination)

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event.
+   */
+  name: string
+  /**
+   * A JSON object containing additional information about the event that will be indexed by FullStory.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/trackEvent/index.ts

@@ -0,0 +1,37 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { FS } from '../types'
+import { segmentEventSource } from '..'
+
+const action: BrowserActionDefinition<Settings, FS, Payload> = {
+  title: 'Track Event',
+  description: 'Track events',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    name: {
+      description: 'The name of the event.',
+      label: 'Name',
+      required: true,
+      type: 'string',
+      default: {
+        '@path': '$.event'
+      }
+    },
+    properties: {
+      description: 'A JSON object containing additional information about the event that will be indexed by FullStory.',
+      label: 'Properties',
+      required: false,
+      type: 'object',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (FS, event) => {
+    FS.event(event.payload.name, event.payload.properties ?? {}, segmentEventSource)
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,10 @@
+import * as FullStory from '@fullstory/browser'
+
+export const FSPackage = FullStory
+export type FS = typeof FullStory & {
+  // setVars is not available on the FS client yet.
+  setVars: (eventName: string, eventProperties: object, source: string) => {}
+  setUserVars: (eventProperties: object, source: string) => void
+  event: (eventName: string, eventProperties: { [key: string]: unknown }, source: string) => void
+  identify: (uid: string, customVars: FullStory.UserVars, source: string) => void
+}

package/src/viewedPage/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the page that was viewed.
+   */
+  pageName?: string
+  /**
+   * The properties of the page that was viewed.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/viewedPage/index.ts

@@ -0,0 +1,45 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { FS } from '../types'
+import { segmentEventSource } from '..'
+
+const action: BrowserActionDefinition<Settings, FS, Payload> = {
+  title: 'Viewed Page',
+  description: 'Sets page properties events',
+  defaultSubscription: 'type = "page"',
+  platform: 'web',
+  fields: {
+    pageName: {
+      type: 'string',
+      required: false,
+      description: 'The name of the page that was viewed.',
+      label: 'Page Name',
+      default: {
+        '@if': {
+          exists: { '@path': '$.category' },
+          then: { '@path': '$.category' },
+          else: { '@path': '$.name' }
+        }
+      }
+    },
+    properties: {
+      type: 'object',
+      required: false,
+      description: 'The properties of the page that was viewed.',
+      label: 'Properties',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (FS, event) => {
+    if (event.payload.pageName) {
+      FS.setVars('page', { pageName: event.payload.pageName, ...event.payload.properties }, segmentEventSource)
+    } else if (event.payload.properties) {
+      FS.setVars('page', event.payload.properties, segmentEventSource)
+    }
+  }
+}
+
+export default action

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "baseUrl": "."
+  },
+  "include": ["src"],
+  "exclude": ["dist", "**/__tests__"]
+}