Track Ask AI entry point in analytics (#4646)

.changeset/ask-view-trigger.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Track which Ask AI entry point opened the chat in ask view analytics.

packages/gitbook/src/components/AI/useAI.tsx

@@ -7,7 +7,7 @@ import type { CustomizationAIMode } from '@gitbook/api';
 import type { GitBookAssistant } from '@gitbook/browser-types';
 import { Icon, type IconName } from '@gitbook/icons';
 
-import { useAIChatController, useAIChatState } from '.';
+import { type AskAITrigger, useAIChatController, useAIChatState } from '.';
 import { AIChatIcon, AISearchIcon, getAIChatName } from '../AIChat';
 import { useIntegrationAssistants } from '../Integrations';
 import { useSetSearchState } from '../Search/useSearch';
@@ -26,7 +26,8 @@ export type AIConfig = {
     };
 };
 
-export type Assistant = Omit<GitBookAssistant, 'icon'> & {
+export type Assistant = Omit<GitBookAssistant, 'icon' | 'open'> & {
+    open: (query?: string, trigger?: AskAITrigger) => void;
     /**
      * Unique identifier for the assistant. Generated automatically using Crypto.randomUUID().
      * @example '123e4567-e89b-12d3-a456-426614174000'
@@ -102,8 +103,8 @@ export function useAI(): AIContext {
                     className="size-text-lg"
                 />
             ),
-            open: (query?: string) => {
-                chatController.open();
+            open: (query?: string, trigger?: AskAITrigger) => {
+                chatController.open(trigger);
                 if (query) {
                     chatController.postMessage({ message: query });
                 }

packages/gitbook/src/components/AI/useAIChat.tsx

@@ -11,6 +11,7 @@ import {
     type AIStreamResponseToolCallPending,
     type AIToolCallResult,
     SiteInsightsDisplayContext,
+    type SiteInsightsEventAskView,
 } from '@gitbook/api';
 
 import { getInsightsSession, useTrackEvent } from '../Insights';
@@ -60,6 +61,8 @@ export type AIChatStatus =
     | 'error'
     | 'confirm';
 
+export type AskAITrigger = NonNullable<SiteInsightsEventAskView['trigger']>;
+
 export type AIChatState = {
     /**
      * If true, the chat is open.
@@ -160,7 +163,7 @@ type AIChatEventListener = (input?: Omit<AIChatEvent, 'type'>) => void;
 
 export type AIChatController = {
     /** Open the dialog */
-    open: () => void;
+    open: (trigger?: AskAITrigger) => void;
     /** Close the dialog */
     close: () => void;
     /** Post a message to the session */
@@ -302,22 +305,28 @@ export function AIChatProvider(props: {
     const eventsRef = React.useRef<Map<AIChatEvent['type'], AIChatEventListener[]>>(new Map());
 
     // Open AI chat and sync with search state
-    const onOpen = React.useCallback(() => {
-        setIntercomLauncherHidden(true);
+    const onOpen = React.useCallback(
+        (trigger?: AskAITrigger) => {
+            setIntercomLauncherHidden(true);
+            if (!renderMessageOptions?.asEmbeddable) {
+                trackEvent({ type: 'ask_view', trigger });
+            }
 
-        const { initialQuery } = globalState.getState();
-        globalState.setState((state) => ({ ...state, opened: true }));
+            const { initialQuery } = globalState.getState();
+            globalState.setState((state) => ({ ...state, opened: true }));
 
-        // Update search state to show ask mode with first message or current ask value
-        setSearchState((prev) => ({
-            ask: prev?.ask ?? initialQuery ?? '',
-            query: prev?.query ?? null,
-            scope: prev?.scope ?? 'default',
-            open: false, // Close search popover when opening chat
-        }));
+            // Update search state to show ask mode with first message or current ask value
+            setSearchState((prev) => ({
+                ask: prev?.ask ?? initialQuery ?? '',
+                query: prev?.query ?? null,
+                scope: prev?.scope ?? 'default',
+                open: false, // Close search popover when opening chat
+            }));
 
-        notify(eventsRef.current.get('open'), {});
-    }, [setSearchState]);
+            notify(eventsRef.current.get('open'), {});
+        },
+        [setSearchState, trackEvent, renderMessageOptions?.asEmbeddable]
+    );
 
     // Close AI chat and clear ask parameter
     const onClose = React.useCallback(() => {

packages/gitbook/src/components/AIChat/AIChat.tsx

@@ -24,7 +24,6 @@ import {
     EmbeddableFrameTitle,
 } from '../Embeddable/EmbeddableFrame';
 import { useIsMounted, useNow } from '../hooks';
-import { useTrackEvent } from '../Insights';
 import { Button } from '../primitives';
 import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SideSheet } from '../primitives/SideSheet';
@@ -68,16 +67,6 @@ export function AIChat() {
         }
     );
 
-    // Track the view of the AI chat
-    const trackEvent = useTrackEvent();
-    React.useEffect(() => {
-        if (chat.opened) {
-            trackEvent({
-                type: 'ask_view',
-            });
-        }
-    }, [chat.opened, trackEvent]);
-
     return (
         <SideSheet
             side="right"

packages/gitbook/src/components/AIChat/AIChatButton.tsx

@@ -39,7 +39,7 @@ export function AIChatButton(props: {
                 </div>
             }
             aria-label={tString(language, 'ai_chat_ask', assistant.label)}
-            onClick={() => assistant.open()}
+            onClick={() => assistant.open(undefined, 'site')}
         >
             {showLabel ? t(language, 'ask') : null}
         </Button>

packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx

@@ -33,7 +33,7 @@ export function AskAIParagraphButton(props: { content: string; className?: Class
             id: `text-${fnv1a(text, { size: 32 })}`,
             content: text,
         });
-        chatController.open();
+        chatController.open('hover');
         chatController.setDraft(tString(language, 'ai_chat_paragraph_draft'));
         chatController.focus();
     };

packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx

@@ -84,7 +84,7 @@ export function AskAITextSelection() {
             id: `text-${fnv1a(content, { size: 32 })}`,
             content,
         });
-        chatController.open();
+        chatController.open('selection');
         chatController.focus();
         clear();
     };

packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx

@@ -61,9 +61,7 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
         }
 
         trackEvent(
-            {
-                type: 'ask_view',
-            },
+            { type: 'ask_view', trigger: 'embed' },
             {
                 pageId: null,
                 displayContext: api.SiteInsightsDisplayContext.Embed,

packages/gitbook/src/components/PageActions/PageActions.tsx

@@ -67,7 +67,7 @@ export function ActionOpenAssistant(props: {
                         href: page.href,
                     });
                 }
-                assistant.open();
+                assistant.open(undefined, 'page');
             }}
         />
     );