@envive-ai/react-hooks 0.3.56 → 0.3.58

package/src/hooks/WidgetInteraction/__tests__/chatTriggerWidget.test.ts

@@ -0,0 +1,51 @@
+import { ChatElementDisplayLocationV3 } from '../../../application/models';
+import { CHAT_TRIGGER_WIDGET, WidgetInteractionComponent } from '../types';
+
+// System-initiated triggers: the chat opens without the shopper clicking a widget. These must not
+// produce an intentional WIDGET_CLICKED, or they inflate every "meaningful engagement" metric.
+const SYSTEM_TRIGGERS = [
+  ChatElementDisplayLocationV3.WINDOW_API_CALL,
+  ChatElementDisplayLocationV3.REFERRER_BASED_PROMPT,
+  ChatElementDisplayLocationV3.AUTOMATIC_PROMPT,
+];
+
+describe('CHAT_TRIGGER_WIDGET', () => {
+  it('maps every display location', () => {
+    for (const location of Object.values(ChatElementDisplayLocationV3)) {
+      expect(CHAT_TRIGGER_WIDGET[location]).not.toBeUndefined();
+    }
+  });
+
+  it('attributes system-initiated triggers to no widget', () => {
+    for (const location of SYSTEM_TRIGGERS) {
+      expect(CHAT_TRIGGER_WIDGET[location]).toBeNull();
+    }
+  });
+
+  it('attributes user-initiated triggers to a widget', () => {
+    const userTriggers = Object.values(ChatElementDisplayLocationV3).filter(
+      location => !SYSTEM_TRIGGERS.includes(location),
+    );
+
+    for (const location of userTriggers) {
+      expect(CHAT_TRIGGER_WIDGET[location]).not.toBeNull();
+    }
+  });
+
+  it('attributes a social proof trigger to social_proof, not floating_button', () => {
+    // Regression guard: useChatToggle used to hardcode FLOATING_BUTTON for every open,
+    // so a suggestion click on the social proof widget was credited to the floating button.
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON]).toBe(
+      WidgetInteractionComponent.SOCIAL_PROOF,
+    );
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.SOCIAL_PROOF_TEXT_FIELD]).toBe(
+      WidgetInteractionComponent.SOCIAL_PROOF,
+    );
+  });
+
+  it('still attributes the floating button to floating_button', () => {
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.FLOATING_BUTTON]).toBe(
+      WidgetInteractionComponent.FLOATING_BUTTON,
+    );
+  });
+});

package/src/hooks/WidgetInteraction/types.ts

@@ -1,3 +1,4 @@
+import { ChatElementDisplayLocationV3 } from '../../application/models';
 import { EnviveMetricsEventName, SpiffyMetricsEventName } from '../../contexts/amplitudeContext';
 
 export interface WidgetInteractionContext {
@@ -114,6 +115,58 @@ export const INTERACTION_TYPE_CLASS: Record<WidgetInteractionType, InteractionCl
   [WidgetInteractionType.VARIANT_SELECTOR_DISMISSED]: InteractionClass.NAVIGATIONAL,
 };
 
+/**
+ * Attribution map: which widget a chat open/close should be credited to, given the surface that
+ * triggered it.
+ *
+ * `null` marks a *system-initiated* trigger — the auto-popup timer, a referrer-based prompt, or a
+ * merchant `window` API call. Those are not user clicks, so they must not emit an intentional
+ * WIDGET_CLICKED. The chat's own WIDGET_EXPANDED still records that the chat opened, so no signal
+ * is lost by skipping them.
+ *
+ * Keyed exhaustively on purpose: adding a ChatElementDisplayLocationV3 member is a compile error
+ * until it is given an attribution here, rather than silently defaulting to the wrong widget.
+ */
+export const CHAT_TRIGGER_WIDGET: Record<
+  ChatElementDisplayLocationV3,
+  WidgetInteractionComponent | null
+> = {
+  [ChatElementDisplayLocationV3.PROMPT_CAROUSEL]: WidgetInteractionComponent.SUGGESTION_BAR,
+  [ChatElementDisplayLocationV3.TITLED_PROMPT_CAROUSEL]: WidgetInteractionComponent.EMBEDDED_WIDGET,
+  [ChatElementDisplayLocationV3.TYPING_ANIMATION]: WidgetInteractionComponent.EMBEDDED_WIDGET,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON]:
+    WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_SECONDARY_BUTTON]:
+    WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_TEXT_FIELD]: WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_COMPARISON_PROMPT_BUTTON]:
+    WidgetInteractionComponent.POST_INTERACTION_COMPARISON,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_COMPARISON_TEXT_FIELD]:
+    WidgetInteractionComponent.POST_INTERACTION_COMPARISON,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_PROMPT_BUTTON]:
+    WidgetInteractionComponent.CHAT_PREVIEW,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_TEXT_FIELD]: WidgetInteractionComponent.CHAT_PREVIEW,
+  [ChatElementDisplayLocationV3.PROMPT_BUTTON_CAROUSEL_WITH_IMAGE_PROMPT_BUTTON]:
+    WidgetInteractionComponent.SINGLE_IMAGE_PROMPT,
+  [ChatElementDisplayLocationV3.PROMPT_BUTTON_CAROUSEL_WITH_IMAGE_TEXT_FIELD]:
+    WidgetInteractionComponent.SINGLE_IMAGE_PROMPT,
+  [ChatElementDisplayLocationV3.FLOATING_BUTTON]: WidgetInteractionComponent.FLOATING_BUTTON,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_OVERLAY]: WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_CLOSE_BUTTON]:
+    WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_PROMPT_BUTTON]:
+    WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_TEXT_INPUT]: WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.PRODUCT_CARD_PROMPT_BUTTON]:
+    WidgetInteractionComponent.IMAGE_PROMPT_CARD,
+  [ChatElementDisplayLocationV3.PRODUCT_CARD_TEXT_FIELD]:
+    WidgetInteractionComponent.IMAGE_PROMPT_CARD,
+  // System-initiated — see note above.
+  [ChatElementDisplayLocationV3.WINDOW_API_CALL]: null,
+  [ChatElementDisplayLocationV3.REFERRER_BASED_PROMPT]: null,
+  [ChatElementDisplayLocationV3.AUTOMATIC_PROMPT]: null,
+};
+
 export type URL = {
   url: string;
 };

package/src/services/amplitudeService/__tests__/amplitudeService.test.ts

@@ -241,6 +241,82 @@ describe('AmplitudeService', () => {
       expect(eventProps).toHaveProperty('chat_user_message_input.count', 5);
     });
 
+    it('should encode supplementary Unicode in widget text events for Amplitude transport', async () => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextResponse,
+        eventProps: {
+          widget_text: {
+            text_field_placeholder_text: [{ id: 'item-1', value: 'Have a question? Ask away 🙂' }],
+          },
+          response_id: 'response-1',
+        },
+      });
+
+      const eventProps = mockTrack.mock.calls[0][1];
+      expect(eventProps.widget_text).toEqual({
+        text_field_placeholder_text: [
+          {
+            id: 'item-1',
+            value: '__spiffy_utf8__:Have%20a%20question%3F%20Ask%20away%20%F0%9F%99%82',
+          },
+        ],
+      });
+      expect(eventProps.response_id).toBe('response-1');
+      expect(eventProps['widget_text_response.widget_text']).toEqual(eventProps.widget_text);
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextClicked,
+        eventProps: {
+          response_id: 'response-1',
+          string_id: 'item-1',
+          text: 'Have a question? Ask away 🙂',
+        },
+      });
+
+      const clickEventProps = mockTrack.mock.calls[1][1];
+      expect(clickEventProps.text).toBe(
+        '__spiffy_utf8__:Have%20a%20question%3F%20Ask%20away%20%F0%9F%99%82',
+      );
+      expect(clickEventProps['widget_text_clicked.text']).toBe(clickEventProps.text);
+    });
+
+    it.each([
+      ['emoji', '🙂', '__spiffy_utf8__:%F0%9F%99%82'],
+      ['ZWJ sequence', '👩‍💻', '__spiffy_utf8__:%F0%9F%91%A9%E2%80%8D%F0%9F%92%BB'],
+      ['flag', '🇧🇷', '__spiffy_utf8__:%F0%9F%87%A7%F0%9F%87%B7'],
+      ['skin tone', '👍🏽', '__spiffy_utf8__:%F0%9F%91%8D%F0%9F%8F%BD'],
+      ['non-emoji supplementary character', '𝄞', '__spiffy_utf8__:%F0%9D%84%9E'],
+      ['BMP text', 'café', 'café'],
+    ])('should preserve %s across widget click transport', async (_name, text, expected) => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextClicked,
+        eventProps: {
+          response_id: 'response-matrix',
+          string_id: 'item-matrix',
+          text,
+        },
+      });
+
+      const eventProps = mockTrack.mock.calls[0][1];
+      expect(eventProps.text).toBe(expected);
+      expect(eventProps['widget_text_clicked.text']).toBe(expected);
+    });
+
+    it('should leave supplementary Unicode unchanged for unrelated events', async () => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: { message: 'Hello 🙂' },
+      });
+
+      expect(mockTrack.mock.calls[0][1].message).toBe('Hello 🙂');
+    });
+
     it('should generate insert_id from event data', async () => {
       const service = createService();
 

package/src/services/amplitudeService/amplitudeService.ts

@@ -19,6 +19,33 @@ export { EnviveMetricsEventName, SpiffyMetricsEventName };
 
 const logger = new Logger('amplitudeService');
 
+// Amplitude's managed BigQuery data can surface supplementary Unicode as U+FFFD.
+// Keep the widget-training payload ASCII-safe without changing the displayed text.
+const UTF8_TRANSPORT_PREFIX = '__spiffy_utf8__:';
+
+const containsSupplementaryUnicode = (value: string): boolean =>
+  Array.from(value).some(character => (character.codePointAt(0) ?? 0) > 0xffff);
+
+const encodeSupplementaryUnicode = (value: unknown): unknown => {
+  if (typeof value === 'string') {
+    return containsSupplementaryUnicode(value)
+      ? `${UTF8_TRANSPORT_PREFIX}${encodeURIComponent(value)}`
+      : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(encodeSupplementaryUnicode);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        encodeSupplementaryUnicode(nestedValue),
+      ]),
+    );
+  }
+  return value;
+};
+
 export interface TrackEventParams {
   eventName: SpiffyMetricsEventName | EnviveMetricsEventName;
   eventProps?: Record<string, unknown>;
@@ -428,10 +455,15 @@ export class AmplitudeService {
       }
 
       const mappedEventProps = AmplitudeService.mapEventProps({ eventName, eventProps });
+      const amplitudeEventProps =
+        eventName === EnviveMetricsEventName.WidgetTextResponse ||
+        eventName === EnviveMetricsEventName.WidgetTextClicked
+          ? (encodeSupplementaryUnicode(mappedEventProps) as Record<string, unknown>)
+          : mappedEventProps;
 
       const eventData = JSON.stringify({
         eventName,
-        eventProps: mappedEventProps,
+        eventProps: amplitudeEventProps,
         created_at: new Date().toISOString(),
       });
       const encoder = new TextEncoder();
@@ -444,16 +476,16 @@ export class AmplitudeService {
 
       logger.logDebug(`amplitude tracking ${decoratedEventName}`, null, {
         event_name: decoratedEventName,
-        props: mappedEventProps,
+        props: amplitudeEventProps,
       });
 
       this.amplitudeClient.track(
         decoratedEventName,
         {
           ...this.getDefaultTrackingProps(eventName),
-          ...mappedEventProps,
-          ...(mappedEventProps
-            ? this.eventPropsToPrefixedEventProps(eventName, mappedEventProps)
+          ...amplitudeEventProps,
+          ...(amplitudeEventProps
+            ? this.eventPropsToPrefixedEventProps(eventName, amplitudeEventProps)
             : {}),
         },
         {