@ht-sdks/events-sdk-js-browser 1.1.0 → 1.3.0

package/src/core/http-cookies/server-examples/node-next-js.md

@@ -0,0 +1,75 @@
+**These server examples should not be used as is. They should be adapted to your setup and "productionized".**
+
+An example HTTPCookieService written as a Next.js API Route.
+
+```Javascript
+import type { NextApiRequest, NextApiResponse } from "next";
+
+const USER_COOKIE = "htjs_user_id";
+const ANON_COOKIE = "htjs_anonymous_id";
+
+function getDomain(request: NextApiRequest) {
+  const domain = request.headers.host?.toString() ?? "";
+  if (domain.startsWith("localhost")) return "localhost";
+  return domain;
+}
+
+function renewCookies(request: NextApiRequest, response: NextApiResponse, browserName: string, serverName: string) {
+  const cookie = request.cookies[browserName] ?? request.cookies[serverName];
+  if (!cookie) return "";
+  const maxAge = 31_536_000; // 1 year in seconds
+  const domain = getDomain(request);
+  response.setHeader("Set-Cookie", [
+    ...((response.getHeader("Set-Cookie") as string[]) ?? []),
+    `${browserName}=${cookie}; Max-Age=${maxAge}; Domain=${domain}; Path=/; SameSite=Lax;`,
+    `${serverName}=${cookie}; Max-Age=${maxAge}; Domain=${domain}; Path=/; SameSite=Lax; httpOnly=true;`,
+  ]);
+  return cookie;
+}
+
+function clearServerCookie(request: NextApiRequest, response: NextApiResponse, serverName: string) {
+  const cookie = "";
+  const maxAge = 0;
+  const domain = getDomain(request);
+  response.setHeader("Set-Cookie", [
+    ...((response.getHeader("Set-Cookie") as string[]) ?? []),
+    `${serverName}=${cookie}; Max-Age=${maxAge}; Domain=${domain}; Path=/; SameSite=Lax; httpOnly;`,
+  ]);
+  return cookie;
+}
+
+export default function handler(request: NextApiRequest, response: NextApiResponse) {
+  if (request.method?.toUpperCase() !== "POST") {
+    response.status(404);
+    response.end();
+    return;
+  }
+
+  const slug = (request.query.slug as string).toLowerCase();
+
+  if (slug === "renew") {
+    response.status(200);
+    response.json({
+      userId: renewCookies(request, response, USER_COOKIE, `${USER_COOKIE}_srvr`),
+      anonymousId: renewCookies(request, response, ANON_COOKIE, `${ANON_COOKIE}_srvr`),
+    });
+  } else if (slug === "clear") {
+    response.status(200);
+    response.json({
+      userId: clearServerCookie(request, response, `${USER_COOKIE}_srvr`),
+      anonymousId: clearServerCookie(request, response, `${ANON_COOKIE}_srvr`),
+    });
+  } else {
+    response.status(404);
+    response.end();
+  }
+}
+```
+
+The HTTPCookieService must live on the same domain and IP address as your website's HTML document.
+
+As one way to accomplish this, you could create one Next.js project to serve both your HTML site and your API.
+
+The above example code might live at `src/pages/api/ht/[slug].ts`, while your other non-API pages might live somewhere like `src/pages/blog/index.tsx`.
+
+See [Next.js](https://nextjs.org/docs) for more information.

package/src/core/user/index.ts

@@ -21,6 +21,7 @@ import {
   hasSessionExpired,
   updateSessionExpiration,
 } from '../session'
+import type { HTTPCookieService } from '../http-cookies'
 
 export type ID = string | null | undefined
 
@@ -32,6 +33,11 @@ export interface UserOptions {
   localStorageFallbackDisabled?: boolean
   persist?: boolean
 
+  /**
+   * Replicates "BrowserCookie" actions against a matching "ServerCookie".
+   */
+  httpCookieService?: HTTPCookieService
+
   cookie?: {
     key?: string
     oldKey?: string
@@ -134,6 +140,14 @@ export class User {
       legacyUser.id && this.id(legacyUser.id)
       legacyUser.traits && this.traits(legacyUser.traits)
     }
+
+    // HTTPCookies require that localStorage values be synced to cookies
+    if (this.options.httpCookieService) {
+      this.identityStore.getAndSync(this.anonKey)
+      this.identityStore.getAndSync(this.idKey)
+      this.options.httpCookieService?.dispatchCreate()
+    }
+
     autoBind(this)
   }
 
@@ -145,11 +159,22 @@ export class User {
     const prevId = this.identityStore.getAndSync(this.idKey)
 
     if (id !== undefined) {
+      const clearingIdentity = id === null
+      const changingIdentity = id !== prevId && prevId !== null && id !== null
+      const creatingIdentity = id !== prevId && prevId === null && id !== null
+
       this.identityStore.set(this.idKey, id)
 
-      const changingIdentity = id !== prevId && prevId !== null && id !== null
+      if (clearingIdentity) {
+        this.options?.httpCookieService?.dispatchClear()
+      }
+
       if (changingIdentity) {
-        this.anonymousId(null)
+        this.anonymousId(null) // this also runs dispatchClear()
+      }
+
+      if (changingIdentity || creatingIdentity) {
+        this.options?.httpCookieService?.dispatchCreate()
       }
     }
 
@@ -176,28 +201,36 @@ export class User {
 
     if (id === undefined) {
       let val = this.identityStore.getAndSync(this.anonKey)
+      let migrated = false
 
       // support anonymousId migration from other analytics providers
       if (!val) {
         val = decryptRudderHtValue(
           this.identityStore.getAndSync(rudderHtAnonymousIdKey) ?? ''
         )
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = this.identityStore.getAndSync(segmentAnonymousIdKey)
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = decryptRudderValue(
           this.identityStore.getAndSync(rudderAnonymousIdKey) ?? ''
         )
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = this.legacySIO()?.[0] ?? null
       }
 
+      if (migrated) {
+        this.options?.httpCookieService?.dispatchCreate()
+      }
+
       if (val) {
         return val
       }
@@ -205,11 +238,16 @@ export class User {
 
     if (id === null) {
       this.identityStore.set(this.anonKey, null)
-      return this.identityStore.getAndSync(this.anonKey)
+      const clearedVal = this.identityStore.getAndSync(this.anonKey)
+      this.options?.httpCookieService?.dispatchClear()
+      return clearedVal
     }
 
     this.identityStore.set(this.anonKey, id ?? uuid())
-    return this.identityStore.getAndSync(this.anonKey)
+    const syncedVal = this.identityStore.getAndSync(this.anonKey)
+
+    this.options?.httpCookieService?.dispatchCreate()
+    return syncedVal
   }
 
   traits = (traits?: Traits | null): Traits | undefined => {

package/src/core/user/tld.ts

@@ -1,4 +1,4 @@
-import cookie from 'js-cookie'
+import cookie, { CookieAttributes } from 'js-cookie'
 
 /**
  * Levels returns all levels of the given url.
@@ -45,11 +45,15 @@ export function tld(url: string): string | undefined {
 
   const lvls = levels(parsedUrl)
 
-  // Lookup the real top level one.
+  // Test for the top most domain that the browser allows
   for (let i = 0; i < lvls.length; ++i) {
-    const cname = '__tld__'
+    const cname = Math.round(Math.random() * 10_000).toString()
     const domain = lvls[i]
-    const opts = { domain: '.' + domain }
+    const opts = {
+      domain: '.' + domain,
+      path: '/',
+      sameSite: 'Lax',
+    } as CookieAttributes
 
     try {
       // cookie access throw an error if the library is ran inside a sandboxed environment (e.g. sandboxed iframe)

package/src/generated/version.ts

@@ -1,2 +1,2 @@
 // This file is generated.
-export const version = '1.1.0'
+export const version = '1.3.0'

package/src/index.ts

@@ -9,5 +9,6 @@ export * from './core/user'
 
 export type { HtEventsSnippet } from './browser/standalone-interface'
 export type { MiddlewareFunction } from './plugins/middleware'
+export { Destination } from './plugins/destinations'
 export { getGlobalAnalytics } from './lib/global-analytics-helper'
 export { UniversalStorage, Store, StorageObject } from './core/storage'

package/src/node/index.ts

@@ -20,7 +20,7 @@ export class AnalyticsNode {
 
     const nodeSettings = {
       writeKey: settings.writeKey,
-      name: 'analytics-node-next',
+      name: 'events-sdk-js-node',
       type: 'after' as Plugin['type'],
       version: 'latest',
     }

package/src/plugins/analytics-node/index.ts

@@ -23,7 +23,7 @@ export async function post(
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'User-Agent': 'analytics-node-next/latest',
+        'User-Agent': 'events-sdk-js-node/latest',
         Authorization: `Basic ${btoa(writeKey)}`,
       },
       body: JSON.stringify(event),
@@ -39,7 +39,7 @@ export async function post(
 
 export function analyticsNode(settings: AnalyticsNodeSettings): Plugin {
   const send = async (ctx: Context): Promise<Context> => {
-    ctx.updateEvent('context.library.name', 'analytics-node-next')
+    ctx.updateEvent('context.library.name', 'events-sdk-js-node')
     ctx.updateEvent('context.library.version', version)
     ctx.updateEvent('_metadata.nodeVersion', process.versions.node)
 

package/src/plugins/destinations/destination.ts

@@ -0,0 +1,85 @@
+import type { DestinationPlugin, Plugin } from '../../core/plugin'
+import { Context, ContextCancelation } from '../../core/context'
+import {
+  applyDestinationMiddleware,
+  DestinationMiddlewareFunction,
+} from '../middleware'
+
+// removes the return type from a function
+type NoReturn<T> = T extends (...args: any[]) => any
+  ? (...args: Parameters<T>) => void | Promise<void>
+  : T
+
+type PluginActions = Pick<
+  Plugin,
+  'alias' | 'group' | 'identify' | 'page' | 'screen' | 'track'
+>
+
+type DestinationActions = {
+  [K in keyof PluginActions]: NoReturn<PluginActions[K]>
+}
+
+/**
+ * Convenience class for writing 3rd party destination plugins
+ */
+export class Destination implements DestinationPlugin {
+  readonly type = 'destination'
+  readonly middleware: DestinationMiddlewareFunction[] = []
+
+  constructor(
+    readonly name: string,
+    readonly version: string,
+    readonly actions: DestinationActions
+  ) {}
+
+  isLoaded() {
+    return true
+  }
+
+  load() {
+    console.debug(`loaded destination plugin: ${this.name} v${this.version}`)
+    return Promise.resolve()
+  }
+
+  addMiddleware(...fn: DestinationMiddlewareFunction[]) {
+    this.middleware.push(...fn)
+  }
+
+  alias = this._createMethod('alias')
+  group = this._createMethod('group')
+  identify = this._createMethod('identify')
+  page = this._createMethod('page')
+  screen = this._createMethod('screen')
+  track = this._createMethod('track')
+
+  private async transform(ctx: Context): Promise<Context> {
+    const modifiedEvent = await applyDestinationMiddleware(
+      this.name,
+      ctx.event,
+      this.middleware
+    )
+
+    if (modifiedEvent == null) {
+      ctx.cancel(
+        new ContextCancelation({
+          retry: false,
+          reason: 'dropped by destination middleware',
+        })
+      )
+    }
+
+    return new Context(modifiedEvent)
+  }
+
+  private _createMethod(action: keyof DestinationActions) {
+    return async (ctx: Context): Promise<Context> => {
+      if (!this.actions[action]) return ctx
+
+      const transformedCtx = await this.transform(ctx)
+
+      await this.actions[action]!(transformedCtx)
+
+      return ctx
+    }
+  }
+}

package/src/plugins/destinations/google-tag-manager.ts

@@ -0,0 +1,96 @@
+import type { Context } from '../../core/context'
+import type { DestinationFactory } from './types'
+import { Destination } from './destination'
+
+declare global {
+  interface Window {
+    gtag: Function
+  }
+}
+
+type GoogleTagManagerSettings = {
+  /**
+   * The Google measurement ID(s) to send events to (GA4, Ads)
+   */
+  measurementId?: string | string[]
+
+  /**
+   * If a `Viewed Page` event should be sent for all `htevents.page` calls
+   */
+  trackAllPages?: boolean
+
+  /**
+   * If a `Viewed <name> Page` event should be sent for `htevents.page('Name')` calls
+   */
+  trackNamedPages?: boolean
+
+  /**
+   * If a `Viewed <category> <name> Page` event should be sent for `htevents.page('Category', 'Name')` calls
+   */
+  trackCategorizedPages?: boolean
+}
+
+/**
+ * https://github.com/segmentio/analytics.js-integrations/blob/master/integrations/google-tag-manager/lib/index.js
+ */
+const googleTagManager: DestinationFactory<GoogleTagManagerSettings> = ({
+  measurementId = [],
+  trackAllPages = false,
+  trackNamedPages = true,
+  trackCategorizedPages = true,
+}) => {
+  const measurementIds = (
+    Array.isArray(measurementId) ? measurementId : [measurementId]
+  ).filter(Boolean)
+
+  const baseEvent = ({ event }: Context) => {
+    return {
+      ...(event.userId && {
+        user_id: event.userId,
+      }),
+      ...(event.anonymousId && {
+        hightouch_anonymous_id: event.anonymousId,
+      }),
+      ...(measurementIds.length > 0 && {
+        send_to: measurementIds,
+      }),
+      ...event.properties,
+    }
+  }
+
+  return new Destination('Google Tag Manager', '0.0.1', {
+    identify: (ctx) => {
+      if (ctx.event.userId) {
+        measurementIds.forEach((measurementId) => {
+          window.gtag('config', measurementId, {
+            user_id: ctx.event.userId,
+          })
+        })
+      }
+    },
+
+    page: (ctx) => {
+      if (
+        trackAllPages ||
+        (trackNamedPages && ctx.event.name) ||
+        (trackCategorizedPages && ctx.event.category)
+      ) {
+        const eventName = ['Viewed', ctx.event.category, ctx.event.name, 'Page']
+          .filter(Boolean)
+          .join(' ')
+
+        window.gtag('event', eventName, {
+          ...baseEvent(ctx),
+        })
+      }
+    },
+
+    track: (ctx) => {
+      window.gtag('event', ctx.event.event, {
+        ...baseEvent(ctx),
+      })
+    },
+  })
+}
+
+export default googleTagManager

package/src/plugins/destinations/index.ts

@@ -0,0 +1,19 @@
+import type { DestinationSettings } from './types'
+import { Destination } from './destination'
+
+export { Destination }
+export type { DestinationSettings }
+
+export async function createDestination(
+  name: string,
+  settings: DestinationSettings
+): Promise<Destination | undefined> {
+  switch (name) {
+    case 'Google Tag Manager':
+      return import(
+        /* webpackChunkName: "google-tag-manager" */ './google-tag-manager'
+      ).then((mod) => mod.default(settings as any))
+    default:
+      return undefined
+  }
+}

package/src/plugins/destinations/types.ts

@@ -0,0 +1,8 @@
+import type { JSONObject } from '@ht-sdks/events-sdk-js-core'
+import type { Destination } from './destination'
+
+export type DestinationSettings = JSONObject
+
+export type DestinationFactory<TSettings extends DestinationSettings> = (
+  settings: TSettings
+) => Destination