STRATCONN-6430 - [Rokt] - new Hybrid, CAPI and Audience Destination (#3491)

* progress

* progress

* more progress

* progress

* multistatus

* auth

* throw error for non batch fail valiation

* post partner call

* Tiffany feedback

* separating device id and ad id fields

* updating dateofbirth to dob

* more instructions from Tiffany

* adding web plugin

* removing qualified files

* adding web pluging with test

* adding server side unit test

* adding unit tests for rokt capi

* snapshot tests done

* types

* removing unreferenced code

* reviewed with partner - tests updated

Author: joe-ayoub-segment

packages/browser-destinations/destinations/rokt-plugins/README.md

@@ -0,0 +1,31 @@
+# @segment/analytics-browser-actions-rokt-plugins
+
+The Rokt Browser Plugin browser action destination for use with @segment/analytics-next.
+
+## License
+
+MIT License
+
+Copyright (c) 2025 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributing
+
+All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.

packages/browser-destinations/destinations/rokt-plugins/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@segment/analytics-browser-actions-rokt-plugins",
+  "version": "1.0.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "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": {
+    "@segment/browser-destination-runtime": "^1.92.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": ">=1.55.0"
+  }
+}

packages/browser-destinations/destinations/rokt-plugins/src/__tests__/index.test.ts

@@ -0,0 +1,81 @@
+import { Analytics, Context, Plugin } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import browserPluginsDestination from '..'
+import { rtidIntegrationFieldName, rtidQuerystringName, storageRTIDKey } from '../utils'
+
+const example: Subscription[] = [
+  {
+    partnerAction: 'roktPlugin',
+    name: 'Rokt Browser Plugin',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {}
+  }
+]
+
+let browserActions: Plugin[]
+let roktPlugin: Plugin
+let ajs: Analytics
+
+beforeEach(async () => {
+  browserActions = await browserPluginsDestination({ subscriptions: example })
+  roktPlugin = browserActions[0]
+
+  ajs = new Analytics({
+    writeKey: 'w_123'
+  })
+
+  Object.defineProperty(window, 'location', {
+    value: {
+      search: ''
+    },
+    writable: true
+  })
+
+  window.localStorage.removeItem(storageRTIDKey)
+})
+
+describe('ajs-integration', () => {
+  test('updates the original event with a Rokt rtid from the querystring', async () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: `?${rtidQuerystringName}=dummyQuerystringValue`
+      },
+      writable: true
+    })
+
+    await roktPlugin.load(Context.system(), ajs)
+
+    const ctx = new Context({
+      type: 'track',
+      event: 'Test Event',
+      properties: {
+        greeting: 'Yo!'
+      }
+    })
+
+    const updatedCtx = await roktPlugin.track?.(ctx)
+
+    const roktIntegrationsObj = updatedCtx?.event?.integrations['Rokt Conversions API']
+    expect(roktIntegrationsObj[rtidIntegrationFieldName]).toEqual('dummyQuerystringValue')
+  })
+
+  test('updates the original event with a Rokt rtid from storage', async () => {
+    window.localStorage.setItem(storageRTIDKey, 'dummyStorageValue')
+
+    await roktPlugin.load(Context.system(), ajs)
+
+    const ctx = new Context({
+      type: 'track',
+      event: 'Test Event',
+      properties: {
+        greeting: 'Yo!'
+      }
+    })
+
+    const updatedCtx = await roktPlugin.track?.(ctx)
+
+    const roktIntegrationsObj = updatedCtx?.event?.integrations['Rokt Conversions API']
+    expect(roktIntegrationsObj[rtidIntegrationFieldName]).toEqual('dummyStorageValue')
+  })
+})

packages/browser-destinations/destinations/rokt-plugins/src/generated-types.ts

@@ -0,0 +1,26 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { storageFallback, storageRTIDKey, rtidQuerystringName } from './utils'
+import { UniversalStorage } from '@segment/analytics-next'
+import roktPlugin from './roktPlugin'
+
+export const destination: BrowserDestinationDefinition<Settings, {}> = {
+  name: 'Rokt Browser Plugins',
+  mode: 'device',
+  initialize: async ({ analytics }) => {
+    const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
+    const urlParams = new URLSearchParams(window.location.search)
+    const rtid: string | null = urlParams.get(rtidQuerystringName) || null
+    if (rtid) {
+      storage.set(storageRTIDKey, rtid)
+    }
+    return {}
+  },
+  settings: {},
+  actions: {
+    roktPlugin
+  }
+}
+
+export default browserDestination(destination)

packages/browser-destinations/destinations/rokt-plugins/src/index.ts

@@ -0,0 +1,34 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import {
+  storageRTIDKey,
+  rtidIntegrationFieldName,
+  storageFallback
+} from '../utils'
+import { UniversalStorage } from '@segment/analytics-next'
+
+const action: BrowserActionDefinition<Settings, {}, Payload> = {
+  title: 'Rokt Browser Plugin',
+  description: 'Enriches all Segment payloads with Rokt rtid Querystring value',
+  platform: 'web',
+  hidden: false,
+  defaultSubscription: 'type = "track" or type = "identify" or type = "page" or type = "group" or type = "alias"',
+  fields: {},
+  lifecycleHook: 'enrichment',
+  perform: (_, { context, analytics }) => {
+    const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
+    const rtid: string | null = storage.get(storageRTIDKey)
+    if (rtid) {
+      const integrationsData: Record<string, string> = {}
+      integrationsData[rtidIntegrationFieldName] = rtid
+      if (context.event.integrations?.All !== false || context.event.integrations['Rokt Conversions API']) {
+        context.updateEvent(`integrations.Rokt Conversions API`, integrationsData)
+      }
+    }
+
+    return
+  }
+}
+
+export default action

packages/browser-destinations/destinations/rokt-plugins/src/roktPlugin/generated-types.ts

@@ -0,0 +1,18 @@
+// The name of the storage location where we'll cache the Rokt rtid Querystring value
+export const storageRTIDKey = 'analytics_rokt_capi_rtid'
+
+// The name of the Rokt rtid querystring to retrieve when the page loads
+export const rtidQuerystringName = 'rtid'
+
+// The field name to include for the Rokt rtid cookie in the "context.integrations.Rokt Conversions API" object
+export const rtidIntegrationFieldName = 'rtid'
+
+export const storageFallback = {
+  get: (key: string) => {
+    const data = window.localStorage.getItem(key)
+    return data
+  },
+  set: (key: string, value: string) => {
+    return window.localStorage.setItem(key, value)
+  }
+}

packages/browser-destinations/destinations/rokt-plugins/src/roktPlugin/index.ts

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

packages/browser-destinations/destinations/rokt-plugins/src/utils.ts

@@ -0,0 +1,82 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Testing snapshot for actions-rokt-capi destination: send action - all fields 1`] = `
+Object {
+  "device_info": Object {
+    "android_advertising_id": "xI%Z3kWrnFUD^fL(n8@",
+    "android_uuid": "xI%Z3kWrnFUD^fL(n8@",
+    "http_header_user_agent": "xI%Z3kWrnFUD^fL(n8@",
+    "ios_advertising_id": "xI%Z3kWrnFUD^fL(n8@",
+    "ios_idfv": "xI%Z3kWrnFUD^fL(n8@",
+  },
+  "environment": "production",
+  "events": Array [
+    Object {
+      "data": Object {
+        "custom_attributes": Object {
+          "audience_name": "xI%Z3kWrnFUD^fL(n8@",
+          "status": "drop",
+        },
+        "custom_event_type": "other",
+        "event_name": "audiencemembershipupdate",
+        "source_message_id": "xI%Z3kWrnFUD^fL(n8@",
+        "timestamp_unixtime_ms": null,
+      },
+      "event_type": "custom_event",
+    },
+    Object {
+      "data": Object {
+        "custom_attributes": Object {
+          "amount": 72258322505400.31,
+          "confirmationref": "xI%Z3kWrnFUD^fL(n8@",
+          "conversiontype": "xI%Z3kWrnFUD^fL(n8@",
+          "currency": "CAD",
+          "testType": "xI%Z3kWrnFUD^fL(n8@",
+        },
+        "custom_event_type": "transaction",
+        "event_name": "conversion",
+        "source_message_id": "xI%Z3kWrnFUD^fL(n8@",
+        "timestamp_unixtime_ms": null,
+      },
+      "event_type": "custom_event",
+    },
+  ],
+  "integration_attributes": Object {
+    "1277": Object {
+      "passbackconversiontrackingid": "xI%Z3kWrnFUD^fL(n8@",
+    },
+  },
+  "ip": "xI%Z3kWrnFUD^fL(n8@",
+  "user_attributes": Object {
+    "billingzipcode": "xI%Z3kWrnFUD^fL(n8@",
+    "dob": "20581114",
+    "firstname": "xI%Z3kWrnFUD^fL(n8@",
+    "gender": "f",
+    "lastname": "xI%Z3kWrnFUD^fL(n8@",
+    "mobile": "xI%Z3kWrnFUD^fL(n8@",
+    "segment_xI%Z3kWrnFUD^fL(n8@": false,
+  },
+  "user_identities": Object {
+    "customerid": "test-user-id-456",
+    "email": "[email protected]",
+    "other2": "xI%Z3kWrnFUD^fL(n8@",
+  },
+}
+`;
+
+exports[`Testing snapshot for actions-rokt-capi destination: send action - required fields 1`] = `
+Object {
+  "device_info": Object {},
+  "environment": "production",
+  "integration_attributes": Object {
+    "1277": Object {
+      "passbackconversiontrackingid": "xI%Z3kWrnFUD^fL(n8@",
+    },
+  },
+  "user_attributes": Object {},
+  "user_identities": Object {
+    "customerid": "test-user-id-123",
+    "other2": "xI%Z3kWrnFUD^fL(n8@",
+  },
+}
+`;