Allow use of integrations directly from NPM (#669)

This patch allows customers to import classic integrations directly from NPM, and use those instead of them being loaded from CDN.

This can be useful in a case where one can't afford to have too many concurrent network requests (due to limits imposed by browsers) , and would rather prefer few larger requests instead.

Author: zikaari

.changeset/khaki-ducks-lick.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Allow use of integrations directly from NPM

packages/browser/package.json

@@ -43,7 +43,7 @@
   "size-limit": [
     {
       "path": "dist/umd/index.js",
-      "limit": "27.2 KB"
+      "limit": "27.3 KB"
     }
   ],
   "dependencies": {
@@ -61,6 +61,7 @@
   },
   "devDependencies": {
     "@internal/config": "0.0.0",
+    "@segment/analytics.js-integration-amplitude": "^3.3.3",
     "@segment/inspector-webext": "^2.0.3",
     "@size-limit/preset-big-lib": "^7.0.8",
     "@types/flat": "^5.0.1",

packages/browser/src/browser/__tests__/integration.test.ts

@@ -19,6 +19,7 @@ import { PriorityQueue } from '../../lib/priority-queue'
 import { getCDN, setGlobalCDNUrl } from '../../lib/parse-cdn'
 import { clearAjsBrowserStorage } from '../../test-helpers/browser-storage'
 import { ActionDestination } from '@/plugins/remote-loader'
+import { ClassicIntegrationBuilder } from '../../plugins/ajs-destination/types'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let fetchCalls: Array<any>[] = []
@@ -975,6 +976,11 @@ describe('.Integrations', () => {
     windowSpy.mockImplementation(
       () => jsd.window as unknown as Window & typeof globalThis
     )
+
+    const documentSpy = jest.spyOn(global, 'document', 'get')
+    documentSpy.mockImplementation(
+      () => jsd.window.document as unknown as Document
+    )
   })
 
   it('lists all legacy destinations', async () => {
@@ -1032,6 +1038,58 @@ describe('.Integrations', () => {
       }
     `)
   })
+
+  it('uses directly provided classic integrations without fetching them from cdn', async () => {
+    const amplitude = // @ts-ignore
+      (await import('@segment/analytics.js-integration-amplitude')).default
+
+    const intializeSpy = jest.spyOn(amplitude.prototype, 'initialize')
+    const trackSpy = jest.spyOn(amplitude.prototype, 'track')
+
+    const [analytics] = await AnalyticsBrowser.load(
+      {
+        writeKey,
+        classicIntegrations: [
+          amplitude as unknown as ClassicIntegrationBuilder,
+        ],
+      },
+      {
+        integrations: {
+          Amplitude: {
+            apiKey: 'abc',
+          },
+        },
+      }
+    )
+
+    await analytics.ready()
+    expect(intializeSpy).toHaveBeenCalledTimes(1)
+
+    await analytics.track('test event')
+
+    expect(trackSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores directly provided classic integrations if settings for them are unavailable', async () => {
+    const amplitude = // @ts-ignore
+      (await import('@segment/analytics.js-integration-amplitude')).default
+
+    const intializeSpy = jest.spyOn(amplitude.prototype, 'initialize')
+    const trackSpy = jest.spyOn(amplitude.prototype, 'track')
+
+    const [analytics] = await AnalyticsBrowser.load({
+      writeKey,
+      classicIntegrations: [amplitude as unknown as ClassicIntegrationBuilder],
+    })
+
+    await analytics.ready()
+
+    expect(intializeSpy).not.toHaveBeenCalled()
+
+    await analytics.track('test event')
+
+    expect(trackSpy).not.toHaveBeenCalled()
+  })
 })
 
 describe('Options', () => {

packages/browser/src/browser/index.ts

@@ -24,6 +24,7 @@ import {
 } from '../core/buffer'
 import { popSnippetWindowBuffer } from '../core/buffer/snippet'
 import { inspectorHost } from '../core/inspector'
+import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
 
 export interface LegacyIntegrationConfiguration {
   /* @deprecated - This does not indicate browser types anymore */
@@ -152,7 +153,8 @@ async function registerPlugins(
   analytics: Analytics,
   opts: InitOptions,
   options: InitOptions,
-  plugins: Plugin[]
+  plugins: Plugin[],
+  legacyIntegrationSources: ClassicIntegrationSource[]
 ): Promise<Context> {
   const tsubMiddleware = hasTsubMiddleware(legacySettings)
     ? await import(
@@ -164,18 +166,20 @@ async function registerPlugins(
       })
     : undefined
 
-  const legacyDestinations = hasLegacyDestinations(legacySettings)
-    ? await import(
-        /* webpackChunkName: "ajs-destination" */ '../plugins/ajs-destination'
-      ).then((mod) => {
-        return mod.ajsDestinations(
-          legacySettings,
-          analytics.integrations,
-          opts,
-          tsubMiddleware
-        )
-      })
-    : []
+  const legacyDestinations =
+    hasLegacyDestinations(legacySettings) || legacyIntegrationSources.length > 0
+      ? await import(
+          /* webpackChunkName: "ajs-destination" */ '../plugins/ajs-destination'
+        ).then((mod) => {
+          return mod.ajsDestinations(
+            legacySettings,
+            analytics.integrations,
+            opts,
+            tsubMiddleware,
+            legacyIntegrationSources
+          )
+        })
+      : []
 
   if (legacySettings.legacyVideoPluginsEnabled) {
     await import(
@@ -274,6 +278,7 @@ async function loadAnalytics(
   inspectorHost.attach?.(analytics as any)
 
   const plugins = settings.plugins ?? []
+  const classicIntegrations = settings.classicIntegrations ?? []
   Context.initMetrics(legacySettings.metrics)
 
   // needs to be flushed before plugins are registered
@@ -284,7 +289,8 @@ async function loadAnalytics(
     analytics,
     opts,
     options,
-    plugins
+    plugins,
+    classicIntegrations
   )
 
   const search = window.location.search ?? ''

packages/browser/src/core/analytics/index.ts

@@ -28,7 +28,10 @@ import { CookieOptions, Group, ID, User, UserOptions } from '../user'
 import autoBind from '../../lib/bind-all'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
 import type { LegacyDestination } from '../../plugins/ajs-destination'
-import type { LegacyIntegration } from '../../plugins/ajs-destination/types'
+import type {
+  LegacyIntegration,
+  ClassicIntegrationSource,
+} from '../../plugins/ajs-destination/types'
 import type {
   DestinationMiddlewareFunction,
   MiddlewareFunction,
@@ -58,6 +61,7 @@ export interface AnalyticsSettings {
   writeKey: string
   timeout?: number
   plugins?: Plugin[]
+  classicIntegrations?: ClassicIntegrationSource[]
 }
 
 export interface InitOptions {

packages/browser/src/plugins/ajs-destination/index.ts

@@ -17,8 +17,19 @@ import {
   applyDestinationMiddleware,
   DestinationMiddlewareFunction,
 } from '../middleware'
-import { loadIntegration, resolveVersion, unloadIntegration } from './loader'
-import { LegacyIntegration } from './types'
+import {
+  buildIntegration,
+  loadIntegration,
+  resolveIntegrationNameFromSource,
+  resolveVersion,
+  unloadIntegration,
+} from './loader'
+import { LegacyIntegration, ClassicIntegrationSource } from './types'
+import { isPlainObject } from '@segment/analytics-core'
+import {
+  isDisabledIntegration as shouldSkipIntegration,
+  isInstallableIntegration,
+} from './utils'
 
 export type ClassType<T> = new (...args: unknown[]) => T
 
@@ -67,6 +78,7 @@ export class LegacyDestination implements Plugin {
   private onInitialize: Promise<unknown> | undefined
   private disableAutoISOConversion: boolean
 
+  integrationSource?: ClassicIntegrationSource
   integration: LegacyIntegration | undefined
 
   buffer: PriorityQueue<Context>
@@ -76,12 +88,14 @@ export class LegacyDestination implements Plugin {
     name: string,
     version: string,
     settings: JSONObject = {},
-    options: InitOptions
+    options: InitOptions,
+    integrationSource?: ClassicIntegrationSource
   ) {
     this.name = name
     this.version = version
     this.settings = { ...settings }
     this.disableAutoISOConversion = options.disableAutoISOConversion || false
+    this.integrationSource = integrationSource
 
     // AJS-Renderer sets an extraneous `type` setting that clobbers
     // existing type defaults. We need to remove it if it's present
@@ -110,13 +124,19 @@ export class LegacyDestination implements Plugin {
       return
     }
 
-    this.integration = await loadIntegration(
-      ctx,
-      analyticsInstance,
-      this.name,
-      this.version,
+    const integrationSource =
+      this.integrationSource ??
+      (await loadIntegration(
+        ctx,
+        this.name,
+        this.version,
+        this.options.obfuscate
+      ))
+
+    this.integration = buildIntegration(
+      integrationSource,
       this.settings,
-      this.options.obfuscate
+      analyticsInstance
     )
 
     this.onReady = new Promise((resolve) => {
@@ -304,7 +324,8 @@ export function ajsDestinations(
   settings: LegacySettings,
   globalIntegrations: Integrations = {},
   options: InitOptions = {},
-  routingMiddleware?: DestinationMiddlewareFunction
+  routingMiddleware?: DestinationMiddlewareFunction,
+  legacyIntegrationSources?: ClassicIntegrationSource[]
 ): LegacyDestination[] {
   if (isServer()) {
     return []
@@ -316,47 +337,47 @@ export function ajsDestinations(
   }
 
   const routingRules = settings.middlewareSettings?.routingRules ?? []
-
+  const remoteIntegrationsConfig = settings.integrations
+  const localIntegrationsConfig = options.integrations
   // merged remote CDN settings with user provided options
   const integrationOptions = mergedOptions(settings, options ?? {}) as Record<
     string,
     JSONObject
   >
 
-  return Object.entries(settings.integrations)
-    .map(([name, integrationSettings]) => {
-      if (name.startsWith('Segment')) {
-        return
-      }
-
-      const allDisableAndNotDefined =
-        globalIntegrations.All === false &&
-        globalIntegrations[name] === undefined
-
-      if (globalIntegrations[name] === false || allDisableAndNotDefined) {
-        return
-      }
+  const adhocIntegrationSources = legacyIntegrationSources?.reduce(
+    (acc, integrationSource) => ({
+      ...acc,
+      [resolveIntegrationNameFromSource(integrationSource)]: integrationSource,
+    }),
+    {} as Record<string, ClassicIntegrationSource>
+  )
 
-      const { type, bundlingStatus, versionSettings } = integrationSettings
-      // We use `!== 'unbundled'` (versus `=== 'bundled'`) to be inclusive of
-      // destinations without a defined value for `bundlingStatus`
-      const deviceMode =
-        bundlingStatus !== 'unbundled' &&
-        (type === 'browser' ||
-          versionSettings?.componentTypes?.includes('browser'))
-
-      // checking for iterable is a quick fix we need in place to prevent
-      // errors showing Iterable as a failed destiantion. Ideally, we should
-      // fix the Iterable metadata instead, but that's a longer process.
-      if ((!deviceMode && name !== 'Segment.io') || name === 'Iterable') {
-        return
-      }
+  const installableIntegrations = new Set([
+    // Remotely configured installable integrations
+    ...Object.keys(remoteIntegrationsConfig).filter((name) =>
+      isInstallableIntegration(name, remoteIntegrationsConfig[name])
+    ),
+
+    // Directly provided integration sources are only installable if settings for them are available
+    ...Object.keys(adhocIntegrationSources || {}).filter(
+      (name) =>
+        isPlainObject(remoteIntegrationsConfig[name]) ||
+        isPlainObject(localIntegrationsConfig?.[name])
+    ),
+  ])
+
+  return Array.from(installableIntegrations)
+    .filter((name) => !shouldSkipIntegration(name, globalIntegrations))
+    .map((name) => {
+      const integrationSettings = remoteIntegrationsConfig[name]
       const version = resolveVersion(integrationSettings)
       const destination = new LegacyDestination(
         name,
         version,
         integrationOptions[name],
-        options
+        options,
+        adhocIntegrationSources?.[name]
       )
 
       const routing = routingRules.filter(
@@ -368,5 +389,4 @@ export function ajsDestinations(
 
       return destination
     })
-    .filter((xt) => xt !== undefined) as LegacyDestination[]
 }