@envive-ai/react-hooks 0.1.0

package/src/adapters/amplitude/amplitudeAdapter.ts

@@ -0,0 +1,454 @@
+import Logger from "src/application/logging/logger";
+import { createInstance } from "@amplitude/analytics-browser";
+// import { sessionReplayPlugin } from '@amplitude/plugin-session-replay-browser';
+import { FeatureGates } from "src/application/models/featureGates";
+import { OrgConfig } from "src/application/models/api/orgConfigResults";
+import { OrgShortName } from "src/application/models";
+import { FeatureFlagService } from "src/application/service/featureFlagService";
+import { userIdAtom } from "src/atoms/app";
+import { getAtomStore } from "src/atoms/atomStore";
+import { featureFlagServiceAtom, orgConfigAtom } from "src/atoms/org/org";
+import { WindowDataLayerService } from "src/application/service/windowDataLayerService";
+import { orgAnalyticsGoogleAnalyticsConfigAtom } from "src/atoms/org/orgAnalyticsConfig";
+import { OrgAnalyticsGoogleAnalyticsConfig } from "src/application/models/api/orgAnalyticsConfig";
+import { EnvironmentService } from "src/application/service/environmentService";
+import {
+  LocalStorageKeys,
+  LocalStorageService,
+} from "src/application/service/localStorageService";
+import { StubAmplitudeAdapter } from "src/adapters/amplitude";
+import { ContextSourceEnum } from "@spiffy-ai/commerce-api-client";
+import { useEnviveConfig } from "src/contexts/enviveConfigContext";
+
+import type {
+  BrowserClient,
+  EnrichmentPlugin,
+  Event,
+  ServerZoneType,
+} from "@amplitude/analytics-types";
+import { EnabledFeatures } from "src/enabled-features";
+import { EventsDispatcher, SpiffyEvent } from "src/events";
+
+export enum SpiffyMetricsEventName {
+  BundleLoaded = "Bundle Loaded",
+  ChatLiveAgentBtnClick = "Chat Live Agent Btn Click",
+  ChatFloatingButtonVisible = "Chat Floating Button Visible",
+  ChatComponentVisible = "Chat Component Visible",
+  ChatComponentExpanded = "Chat Component Expanded",
+  ChatComponentCollapsed = "Chat Component Collapsed",
+  ChatUserMessageInput = "Chat User Message Input",
+  ChatSuggestionClicked = "Chat Suggestion Clicked",
+  ChatAssistantResponse = "Chat Assistant Response",
+  ProductCardClicked = "Product Card Clicked",
+  ProductReviewCardClicked = "Product Review Card Clicked",
+  AddToCartClicked = "Add to Cart Clicked",
+  PromptCardClicked = "Prompt Card Clicked",
+  SupportedEvent = "Supported Event",
+  SearchBackToResponseClicked = "Search Back to Response Clicked",
+  PerformanceMetrics = "Performance Metrics",
+  SearchBarClicked = "Search Bar Clicked",
+  OrderLookupStarted = "Order Lookup Started",
+  OrderLookupFormSubmitted = "Order Lookup Form Submitted",
+  SearchComponentVisible = "Search Component Visible",
+  GlobalSearchPromptClicked = "Global Search Prompt Clicked", // This is the scrolling list of suggestion buttons in global search
+  SearchInputStarted = "Search Input Started",
+  SearchQuerySubmitted = "Search Query Submitted",
+  // SearchAutocompleteViewed = 'Search Autocomplete Viewed', // TODO: add this when autocomplete is added
+  // SearchAutocompleteClicked = 'Search Autocomplete Clicked', // TODO: add this when autocomplete is added
+  SearchResultsViewed = "Search Results Viewed",
+  SearchTimeToFirstClick = "Search Time to First Click",
+  SearchZeroResultsRate = "Search Zero Results Rate",
+  SearchFilterClicked = "Search Filter Clicked",
+  SearchSortClicked = "Search Sort Clicked",
+}
+
+class AmplitudeAdapter {
+  private underlyingAmplitudeClient: BrowserClient | undefined = undefined;
+
+  private internalEventTrackingEnrichment: EnrichmentPlugin | undefined =
+    undefined;
+
+  private supplementalDefaultProps: Record<string, unknown>;
+
+  constructor(
+    private readonly userId: string,
+    private readonly orgConfig: OrgConfig,
+    private readonly featureFlagService: FeatureFlagService,
+    private readonly orgGaConfig?: OrgAnalyticsGoogleAnalyticsConfig
+  ) {
+    this.supplementalDefaultProps = {};
+  }
+
+  init(): void {
+    this.underlyingAmplitudeClient = this.createUnderlyingClient();
+  }
+
+  getUnderlyingAmplitudeClient(): BrowserClient | undefined {
+    return this.underlyingAmplitudeClient;
+  }
+
+  getSupplementalDefaultProps(): Record<string, unknown> {
+    return this.supplementalDefaultProps;
+  }
+
+  setSupplementalDefaultProps(
+    supplementalDefaultProps: Record<string, unknown>
+  ): void {
+    this.supplementalDefaultProps = supplementalDefaultProps;
+  }
+
+  getEventTrackingEnrichment(): EnrichmentPlugin {
+    if (this.internalEventTrackingEnrichment !== undefined) {
+      return this.internalEventTrackingEnrichment;
+    }
+
+    this.internalEventTrackingEnrichment = {
+      name: "page-view-tracking-enrichment",
+      type: "enrichment",
+      setup: async () => undefined,
+      execute: async (event: Event): Promise<Event> => {
+        let enrichedEvent: Event;
+
+        const eventsToEnrich = [
+          "[Amplitude] Page Viewed",
+          `[Spiffy] ${SpiffyMetricsEventName.BundleLoaded}`,
+        ];
+
+        if (eventsToEnrich.includes(event.event_type)) {
+          const windowProps = window._spiffy ? { ...window._spiffy } : {};
+
+          if (windowProps.publicKey) {
+            delete windowProps.publicKey;
+          }
+
+          const globalProperties = Object.entries(windowProps).reduce<
+            Record<string, string>
+          >(
+            (acc, [key, value]) => ({
+              ...acc,
+              [`globalProperties.${key}`]: `${value}`,
+            }),
+            {}
+          );
+
+          const enabledFeatures = await EnabledFeatures.get(
+            this.orgConfig,
+            this.featureFlagService
+          );
+          const enabledFeaturesProperties = Object.entries(
+            enabledFeatures
+          ).reduce<Record<string, string>>(
+            (acc, [key, value]) => ({
+              ...acc,
+              [`enabledFeatures.${key}`]: `${value}`,
+            }),
+            {}
+          );
+
+          const timingProperties = {
+            // This property can be useful to detect bias in A/B testing.
+            //
+            // It is a proxy metric for the value of "Started" (in Dev Tools > Network > Timing)
+            // for the network request to send the Page Viewed event to Amplitude.
+            //
+            // If the value is higher for one group, visitors in that group are subject to
+            // a higher likelihood that the page fails to send the event to Amplitude before
+            // they navigate away, leading to relative underreporting of page views for that group.
+            "timing.enriched_at_ms": window.performance?.now(),
+          };
+
+          enrichedEvent = {
+            ...event,
+            event_properties: {
+              ...event.event_properties,
+              ...this.getDefaultTrackingProps(),
+              ...globalProperties,
+              ...enabledFeaturesProperties,
+              ...timingProperties,
+            },
+          };
+        } else {
+          enrichedEvent = event;
+        }
+
+        EventsDispatcher.dispatch(SpiffyEvent.AMPLITUDE_EVENT, enrichedEvent);
+
+        return enrichedEvent;
+      },
+    };
+
+    return this.internalEventTrackingEnrichment;
+  }
+
+  amplitudeSessionReplayInit(): boolean {
+    // TODO: enable session replay only for UV so we can triage issues with search analytics
+    // remove when we can easily do this through AI Studio or no longer needed for UV
+    const orgShortName = this.orgConfig.org.org.shortName;
+    const isEnabled =
+      orgShortName === OrgShortName.UniqueVintage &&
+      this.featureFlagService.isClientSessionEnabled() &&
+      this.featureFlagService.isFeatureGateEnabled(
+        FeatureGates.IsNewFeatureEnabled
+      );
+    const sampleRate = 1;
+
+    try {
+      Logger.logDebug(
+        `[spiffy-ai] amplitude session-replay initializing isEnabled=${isEnabled} sampleRate=${sampleRate}`
+      );
+
+      if (!isEnabled) {
+        return isEnabled;
+      }
+
+      // amplitudeInstance.add(sessionReplayPlugin({ sampleRate }));
+
+      return isEnabled;
+    } catch (e) {
+      Logger.logError(
+        "[spiffy-ai] Error initializing amplitude session-replay",
+        e
+      );
+      return false;
+    }
+  }
+
+  createUnderlyingClient(): BrowserClient {
+    const { amplitudeApiKey, dataResidency } = useEnviveConfig();
+    const currentAmplitudeInstance: BrowserClient = createInstance();
+    const isSessionsEnabled = this.amplitudeSessionReplayInit();
+    currentAmplitudeInstance.add(this.getEventTrackingEnrichment());
+    currentAmplitudeInstance.init(amplitudeApiKey, this.userId, {
+      serverZone: dataResidency as ServerZoneType,
+      trackingOptions: {
+        ipAddress: true,
+      },
+      autocapture: {
+        // Amplitude tracks marketing attribution by default.
+        // Browser SDK 2 captures UTM parameters, referrer information,
+        // and click IDs as user properties.
+        attribution: true,
+        // Amplitude tracks page view events by default.
+        // The default behavior sends a page view event on initialization.
+        // The event type for this event is [Amplitude] Page Viewed.
+        pageViews: {
+          trackHistoryChanges: "pathOnly",
+        },
+        // Amplitude tracks session events by default.
+        // A session is the period of time a user has your website open.
+        sessions: isSessionsEnabled,
+        // Amplitude tracks form interaction events by default.
+        // The SDK tracks [Amplitude] Form Started when the user initially
+        // interacts with the form element. An initial interaction can be the
+        // first change to a text input, radio button, or dropdown.
+        formInteractions: false,
+        // Amplitude tracks file download events by default.
+        // The SDK tracks [Amplitude] File Downloaded when the user clicks an anchor
+        // or <a> tag linked to a file
+        fileDownloads: false,
+      },
+    });
+
+    return currentAmplitudeInstance;
+  }
+
+  getDefaultTrackingProps(): Record<string, unknown> {
+    const { env } = useEnviveConfig();
+    const gatesProps = this.orgConfig.gates
+      ? this.orgConfig.gates.reduce<Record<string, boolean>>((acc, curr) => {
+          if (curr.name && curr.value != null) {
+            return { ...acc, [`feature_gate.${curr.name}`]: curr.value };
+          }
+
+          return acc;
+        }, {})
+      : {};
+    const experimentProps = this.orgConfig.experiments
+      ? this.orgConfig.experiments.reduce<Record<string, unknown>>(
+          (acc, curr) => {
+            if (curr.name && curr.value != null) {
+              return {
+                ...acc,
+                [`product_experiment.${curr.name}`]: curr.value,
+              };
+            }
+
+            return acc;
+          },
+          {}
+        )
+      : {};
+    const orgLevelAmplitudeTrackingProps = {
+      ...gatesProps,
+      ...experimentProps,
+    };
+
+    // Keep these name value/pairs consistent with server side tracking events sent to amplitude
+    // Consult pymono for the latest list of properties. The "null" values are placeholders and
+    // left here for reference and documentation purposes.
+    return {
+      ...orgLevelAmplitudeTrackingProps,
+      ...this.supplementalDefaultProps,
+      org_id: this.orgConfig.org?.org.id,
+      app_id: "commerce-chat-react-component", // This is the app id of the current app
+      chat_id: LocalStorageService.getItem(LocalStorageKeys.ChatId),
+      env: env || "unknown",
+      app_source: EnvironmentService.getContextSource(),
+      "org.short_name": this.orgConfig.org?.org.shortName,
+      "user.id": this.userId, // This is the user id of the current user (aka "spiffy user id")
+      "cdp.user_id": null, // Not applicable, left here for future use
+      "cdp.provider": null, // Not applicable, left here for future use
+      "event.source": "web-browser",
+      "event.type": "user-activity",
+      "event.id": null, // Not applicable, left here for future use
+      "event.channel": "web",
+      "event.timestamp": null, // Implicitly set by amplitude
+    };
+  }
+
+  /**
+   * Prefixes the event properties sent to Amplitude with the event name to prevent event-level
+   * property names from clashing with app-level property names. Event properties will be in the
+   * format of `event_name.property_name`.
+   *
+   * @param eventName - The name of the event to prefix the properties for.
+   * @param eventProps - The event properties to prefix.
+   *
+   * @returns The prefixed properties.
+   */
+  private eventPropsToPrefixedEventProps = (
+    eventName: SpiffyMetricsEventName,
+    eventProps: Record<string, unknown>
+  ): Record<string, unknown> => {
+    // replaces all spaces in the event name with underscores
+    const prefix = eventName.toLowerCase().replace(/\s+/g, "_");
+
+    return Object.entries(eventProps).reduce((acc, [key, value]) => {
+      acc[`${prefix}.${key}`] = value;
+      return acc;
+    }, {} as Record<string, unknown>);
+  };
+
+  static trackEvent = async ({
+    eventName,
+    eventProps,
+    eventGroups,
+    alsoSendToGoogleAnalytics = false,
+  }: {
+    eventName: SpiffyMetricsEventName;
+    eventProps?: Record<string, unknown>;
+    eventGroups?: Record<string, unknown>;
+    alsoSendToGoogleAnalytics?: boolean;
+  }): Promise<void> => {
+    try {
+      const decoratedEventName = `[Spiffy] ${eventName}`;
+      const amplitudeInstance = AmplitudeAdapter.getSingletonInstanceOf();
+      const amplitudeClient = amplitudeInstance.getUnderlyingAmplitudeClient();
+
+      if (!amplitudeClient) {
+        Logger.logWarn("amplitude instance undefined", undefined, {
+          event_name: decoratedEventName,
+        });
+        return;
+      }
+
+      const eventData = JSON.stringify({
+        eventName,
+        eventProps,
+        created_at: new Date().toISOString(),
+      });
+      const encoder = new TextEncoder();
+      const data = encoder.encode(eventData);
+      // calculate a hash of the event properties to use as the insert_id so that duplicate events
+      // are automatically dropped by Amplitude
+      const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      const currentInsertId = hashArray
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+
+      Logger.logDebug(`amplitude tracking ${decoratedEventName}`, null, {
+        event_name: decoratedEventName,
+        props: eventProps,
+      });
+
+      amplitudeClient.track(
+        decoratedEventName,
+        {
+          ...amplitudeInstance.getDefaultTrackingProps(),
+          ...eventProps,
+          ...(eventProps
+            ? AmplitudeAdapter.getSingletonInstanceOf().eventPropsToPrefixedEventProps(
+                eventName,
+                eventProps
+              )
+            : {}),
+        },
+        {
+          ...eventGroups,
+          insert_id: currentInsertId,
+        }
+      );
+
+      if (alsoSendToGoogleAnalytics && amplitudeInstance.orgGaConfig) {
+        const dataLayer = WindowDataLayerService.getSingletonInstanceOf(
+          amplitudeInstance.orgGaConfig
+        );
+        Logger.logDebug("[spiffy-ai] GA tracking", decoratedEventName);
+        dataLayer.sendToGoogleAnalyticsCircularEventsSafe(
+          decoratedEventName,
+          eventProps
+        );
+      }
+    } catch (err) {
+      Logger.logError("[spiffy-ai] Error tracking event", err, {
+        eventName,
+        eventProps,
+      });
+    }
+  };
+
+  // All string values, like user_id, event, or user property values, have a character limit of 1024 characters.
+  // https://amplitude.com/docs/apis/analytics/http-v2
+  static amplitudeSafeString(input: string | undefined) {
+    if (!input) {
+      return null;
+    }
+    if (input.length > 1024) {
+      return input.slice(0, 1024);
+    }
+    return input;
+  }
+
+  static getSingletonInstanceOf(): AmplitudeAdapter {
+    if (EnvironmentService.getContextSource() === ContextSourceEnum.Test) {
+      return new StubAmplitudeAdapter();
+    }
+
+    const identifyingPrefix = EnvironmentService.getIdentifyingPrefix();
+
+    if (!window[identifyingPrefix]) {
+      window[identifyingPrefix] = {} as Window[typeof identifyingPrefix];
+    }
+
+    if (!window[identifyingPrefix]._amplitudeAdapter) {
+      const atomStore = getAtomStore();
+      const userId = atomStore.get(userIdAtom);
+      const orgConfig = atomStore.get(orgConfigAtom);
+      const orgGaConfig = atomStore.get(orgAnalyticsGoogleAnalyticsConfigAtom);
+      const featureFlagService = atomStore.get(featureFlagServiceAtom);
+
+      window[identifyingPrefix]._amplitudeAdapter = new AmplitudeAdapter(
+        userId,
+        orgConfig,
+        featureFlagService,
+        orgGaConfig
+      );
+      window[identifyingPrefix]._amplitudeAdapter?.init();
+    }
+
+    return window[identifyingPrefix]._amplitudeAdapter as AmplitudeAdapter;
+  }
+}
+
+export { AmplitudeAdapter };

package/src/adapters/amplitude/index.ts

@@ -0,0 +1,2 @@
+export * from './amplitudeAdapter';
+export * from './stubAmplitudeAdapter';

package/src/adapters/amplitude/stubAmplitudeAdapter.ts

@@ -0,0 +1,34 @@
+import { AmplitudeAdapter } from 'src/adapters/amplitude';
+import { OrgConfig } from 'src/application/models/api/orgConfigResults';
+import { FeatureFlagService } from 'src/application/service/featureFlagService';
+
+import type { BrowserClient, EnrichmentPlugin, Event } from '@amplitude/analytics-types';
+
+export class StubAmplitudeAdapter extends AmplitudeAdapter {
+  constructor() {
+    super('test', {} as OrgConfig, {} as FeatureFlagService );
+  }
+
+  init = (): void => {};
+
+  getUnderlyingAmplitudeClient = (): BrowserClient | undefined => undefined;
+
+  getSupplementalDefaultProps = (): Record<string, unknown> => ({});
+
+  setSupplementalDefaultProps = (): void => {};
+
+  getEventTrackingEnrichment = (): EnrichmentPlugin => ({
+    name: 'stub-enrichment',
+    type: 'enrichment',
+    setup: async () => undefined,
+    execute: async (event: Event) => event,
+  });
+
+  amplitudeSessionReplayInit = (): boolean => false;
+
+  createUnderlyingClient = (): BrowserClient => ({}) as BrowserClient;
+
+  getDefaultTrackingProps = (): Record<string, unknown> => ({});
+
+  trackEvent = (): Promise<void> => Promise.resolve();
+}