@segment/analytics-browser-appcues-web-actions 1.1.0

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

@@ -0,0 +1,119 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import AppcuesDestination, { destination } from '../../index'
+import { Appcues } from '../../types'
+
+describe('Appcues.identify', () => {
+  const settings = {
+    accountID: 'test-account-id',
+    region: 'US' as const,
+    enableURLDetection: true
+  }
+
+  let mockAppcues: Appcues
+  let event: any
+
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockAppcues = {
+        track: jest.fn(),
+        identify: jest.fn(),
+        group: jest.fn(),
+        page: jest.fn()
+      }
+      return Promise.resolve(mockAppcues)
+    })
+  })
+
+  test('identify() handled correctly', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'identify',
+        name: 'Identify',
+        enabled: true,
+        subscribe: 'type = "identify"',
+        mapping: {
+          userId: { '@path': '$.userId' },
+          traits: { '@path': '$.traits' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'identify',
+      anonymousId: 'anonymous-id-123',
+      userId: 'user-123',
+      traits: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        plan: 'premium',
+        age: 30
+      }
+    })
+
+    const [identifyEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = identifyEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.identify?.(context)
+
+    expect(mockAppcues.identify).toHaveBeenCalledWith('user-123', {
+      name: 'John Doe',
+      email: 'john@example.com',
+      plan: 'premium',
+      age: 30
+    })
+  })
+
+  test('identify() handles nested traits and arrays', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'identify',
+        name: 'Identify',
+        enabled: true,
+        subscribe: 'type = "identify"',
+        mapping: {
+          userId: { '@path': '$.userId' },
+          traits: { '@path': '$.traits' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'identify',
+      userId: 'user-123',
+      traits: {
+        name: 'John Doe',
+        address: {
+          city: 'San Francisco',
+          state: 'CA'
+        },
+        tags: ['vip', 'beta']
+      }
+    })
+
+    const [identifyEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = identifyEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.identify?.(context)
+
+    expect(mockAppcues.identify).toHaveBeenCalledWith('user-123', {
+      name: 'John Doe',
+      address: {
+        city: 'San Francisco',
+        state: 'CA'
+      },
+      tags: ['vip', 'beta']
+    })
+  })
+})

package/src/identify/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The ID of the user to identify in Appcues.
+   */
+  userId: string
+  /**
+   * Properties to associate with the user.
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identify/index.ts

@@ -0,0 +1,33 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Appcues } from '../types'
+
+const action: BrowserActionDefinition<Settings, Appcues, Payload> = {
+  title: 'Identify',
+  description: 'Send Segment identify events to Appcues.',
+  platform: 'web',
+  fields: {
+    userId: {
+      label: 'User ID',
+      description: 'The ID of the user to identify in Appcues.',
+      required: true,
+      type: 'string',
+      default: { '@path': '$.userId' }
+    },
+    traits: {
+      label: 'User traits',
+      description: 'Properties to associate with the user.',
+      required: false,
+      type: 'object',
+      default: { '@path': '$.traits' }
+    }
+  },
+  defaultSubscription: 'type = "identify"',
+  perform: (appcues, { payload }) => {
+    const { userId, traits } = payload
+    appcues.identify(userId, traits)
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,71 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import type { Appcues } from './types'
+import track from './track'
+import page from './page'
+import identify from './identify'
+import group from './group'
+import { URL } from './constants'
+import { defaultValues } from '@segment/actions-core'
+
+export const destination: BrowserDestinationDefinition<Settings, Appcues> = {
+  name: 'Appcues Web',
+  slug: 'appcues-web-actions',
+  mode: 'device',
+  settings: {
+    accountID: {
+      label: 'Appcues Account ID',
+      description: 'Your Appcues Account ID.',
+      type: 'password',
+      required: true
+    },
+    region: {
+      label: 'Region',
+      description: 'Select the Appcues region for your account.',
+      type: 'string',
+      required: true,
+      choices: [
+        { label: 'US', value: 'US' },
+        { label: 'EU', value: 'EU' }
+      ],
+      default: 'US'
+    },
+    enableURLDetection: {
+      label: 'Enable URL Detection',
+      description: 'Enable or disable URL detection in Appcues. If enabled, page events should not be triggered manually using the page action.',
+      type: 'boolean',
+      required: true,
+      default: false
+    }
+  },
+  initialize: async ({ settings }, deps) => {
+    const {
+      region,
+      accountID,
+      enableURLDetection
+    } = settings
+    const url = region === 'EU' ? URL.EU : URL.US
+    window.AppcuesSettings = { enableURLDetection }
+    await deps.loadScript(`//${url}/${accountID}.js`)
+    await deps.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'Appcues'), 100)
+    return window.Appcues
+  },
+  presets: [
+    {
+      name: 'Page',
+      subscribe: 'type = "page"',
+      partnerAction: 'page',
+      mapping: defaultValues(page.fields),
+      type: 'automatic'
+    }
+  ],
+  actions: {
+    track,
+    page,
+    identify,
+    group
+  }
+}
+
+export default browserDestination(destination)

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

@@ -0,0 +1,63 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import AppcuesDestination, { destination } from '../../index'
+import { Appcues } from '../../types'
+
+describe('Appcues.page', () => {
+  const settings = {
+    accountID: 'test-account-id',
+    region: 'US' as const,
+    enableURLDetection: true
+  }
+
+  let mockAppcues: Appcues
+  let event: any
+
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockAppcues = {
+        track: jest.fn(),
+        identify: jest.fn(),
+        group: jest.fn(),
+        page: jest.fn()
+      }
+      return Promise.resolve(mockAppcues)
+    })
+  })
+
+  test('page() handled correctly', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'page',
+        name: 'Page',
+        enabled: true,
+        subscribe: 'type = "page"',
+        mapping: {}
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'page',
+      anonymousId: 'anonymous-id-123',
+      userId: 'user-123',
+      properties: {
+        url: 'https://example.com/home',
+        path: '/home',
+        title: 'Home Page'
+      }
+    })
+
+    const [pageEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = pageEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.page?.(context)
+
+    expect(mockAppcues.page).toHaveBeenCalled()
+  })
+})

package/src/page/generated-types.ts

@@ -0,0 +1,3 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {}

package/src/page/index.ts

@@ -0,0 +1,17 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Appcues } from '../types'
+
+const action: BrowserActionDefinition<Settings, Appcues, Payload> = {
+  title: 'Page',
+  description: 'Send Segment page events to Appcues.',
+  platform: 'web',
+  fields: {},
+  defaultSubscription: 'type = "page"',
+  perform: (appcues) => {
+    appcues.page()
+  }
+}
+
+export default action

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

@@ -0,0 +1,125 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import AppcuesDestination, { destination } from '../../index'
+import { Appcues } from '../../types'
+
+describe('Appcues.track', () => {
+  const settings = {
+    accountID: 'test-account-id',
+    region: 'US' as const,
+    enableURLDetection: true
+  }
+
+  let mockAppcues: Appcues
+  let event: any
+
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockAppcues = {
+        track: jest.fn(),
+        identify: jest.fn(),
+        group: jest.fn(),
+        page: jest.fn()
+      }
+      return Promise.resolve(mockAppcues)
+    })
+  })
+
+  test('track() handled correctly', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'track',
+        name: 'Track',
+        enabled: true,
+        subscribe: 'type = "track"',
+        mapping: {
+          event: { '@path': '$.event' },
+          properties: { '@path': '$.properties' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'track',
+      event: 'Button Clicked',
+      anonymousId: 'anonymous-id-123',
+      userId: 'user-123',
+      properties: {
+        buttonName: 'Sign Up',
+        color: 'blue',
+        position: 'header'
+      }
+    })
+
+    const [trackEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = trackEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.track?.(context)
+
+    expect(mockAppcues.track).toHaveBeenCalledWith('Button Clicked', {
+      buttonName: 'Sign Up',
+      color: 'blue',
+      position: 'header'
+    })
+  })
+
+  test('track() handles nested properties and arrays', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'track',
+        name: 'Track',
+        enabled: true,
+        subscribe: 'type = "track"',
+        mapping: {
+          event: { '@path': '$.event' },
+          properties: { '@path': '$.properties' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'track',
+      event: 'Purchase Completed',
+      userId: 'user-123',
+      properties: {
+        total: 99.99,
+        items: [
+          { name: 'Product A', price: 49.99 },
+          { name: 'Product B', price: 50.00 }
+        ],
+        shipping: {
+          method: 'express',
+          cost: 10
+        }
+      }
+    })
+
+    const [trackEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = trackEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.track?.(context)
+
+    expect(mockAppcues.track).toHaveBeenCalledWith('Purchase Completed', {
+      total: 99.99,
+      items: [
+        { name: 'Product A', price: 49.99 },
+        { name: 'Product B', price: 50.00 }
+      ],
+      shipping: {
+        method: 'express',
+        cost: 10
+      }
+    })
+  })
+})

package/src/track/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event to track in Appcues.
+   */
+  event: string
+  /**
+   * Properties to associate with the event.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/track/index.ts

@@ -0,0 +1,33 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Appcues } from '../types'
+
+const action: BrowserActionDefinition<Settings, Appcues, Payload> = {
+  title: 'Track',
+  description: 'Send Segment track events to Appcues.',
+  platform: 'web',
+  fields: {
+    event: {
+      label: 'Event Name',
+      description: 'The name of the event to track in Appcues.',
+      required: true,
+      type: 'string',
+      default: { '@path': '$.event' }
+    },
+    properties: {
+      label: 'Event Properties',
+      description: 'Properties to associate with the event.',
+      required: false,
+      type: 'object',
+      default: { '@path': '$.properties' }
+    }
+  },
+  defaultSubscription: 'type = "track"',
+  perform: (appcues, { payload }) => {
+    const { event, properties } = payload
+    appcues.track(event, properties)
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,21 @@
+declare global {
+  interface Window {
+    Appcues: Appcues
+    AppcuesSettings: AppcuesSettings
+  }
+}
+
+export interface Appcues {
+  track(event_name: string, properties?: Properties): void
+  identify(userId: string, traits?: Properties): void
+  group(groupId: string, traits?: Properties): void
+  page(): void
+}
+
+export interface AppcuesSettings {
+  enableURLDetection: boolean
+}
+
+export type Properties = {
+  [k: string]: unknown
+}

package/tsconfig.json

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