Quack SDK Tracking Documentation

Overview

The Quack SDK provides a comprehensive event tracking system that allows you to monitor user interactions and chat behavior. The tracking system is built around the trackCallback method and supports various analytics events through the Mixpanel integration.

trackCallback Method

Purpose

The trackCallback method allows you to register a custom callback function that will be invoked whenever tracking events occur within the Quack SDK.

Signature

trackCallback(callback: (eventName: string, properties: any) => void): void

Parameters

• callback: A function that receives two parameters:

  • eventName (string): The name of the event being tracked

  • properties (object): An object containing event-specific data and metadata

Usage Example

// Set up tracking callback
window.quack.trackCallback((eventName, properties) => {
  console.log("Event tracked:", eventName, properties);

  // Send to your analytics service
  analytics.track(eventName, properties);
});

Tracked Events

Core Chat Events

1. chatbot_session_start

Triggered when a new chat session begins.

When it triggers: Fired immediately when a user initiates a new chat session, either by clicking the chat button or through proactive chat activation.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL when session started

• chatId (string): Unique chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name (same as eventName parameter)

Implementation Example:

winow.quack.trackCallback((eventName, properties) => {
  if (eventName === "chatbot_session_start") {
    // Track session start in your analytics
    analytics.track("Chat Session Started", {
      page: properties.entry_page,
      sessionId: properties.chatId,
      isProactive: properties.isProactive,
    });

    // Update user engagement metrics
    updateUserEngagement("chat_started");
  }
});

2. chatbot_session_created

Fired when a chat session is successfully created on the backend.

When it triggers: Occurs after the backend successfully creates and initializes a new chat session, confirming that the session is ready for messaging.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Unique chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "chatbot_session_created") {
    // Log successful session creation
    console.log("chat session ready:", properties.chatId);

    // Track funnel step completion
    analytics.track("Chat Session Ready", {
      sessionId: properties.chatId,
      tenant: properties.tenant,
    });

    // Initialize session-specific tracking
    sessionTracker.init(properties.chatId);
  }
});

3. chatbot_loaded

Triggered when the chatbot widget is fully loaded and ready.

When it triggers: Fires when the chatbot widget has completely loaded all necessary resources and is ready for user interaction.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Chat session identifier (if available)

• isProactive (boolean): Whether this is a proactive session

• event (string): Event name

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "chatbot_loaded") {
    // Track widget load time
    const loadTime = performance.now();
    analytics.track("Widget Loaded", {
      loadTime: loadTime,
      page: properties.entry_page,
      tenant: properties.tenant,
    });

    // Enable chat-related UI elements
    enableChatFeatures();

    // Track page performance
    performanceTracker.recordWidgetLoad(loadTime);
  }
});

4. chatbot_viewed

Fired when the chatbot interface becomes visible to the user.

When it triggers: Occurs when the chat interface is opened and becomes visible to the user, typically after clicking the chat button.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "chatbot_viewed") {
    // Track chat visibility
    analytics.track("Chat Interface Viewed", {
      sessionId: properties.chatId,
      page: properties.entry_page,
      timestamp: new Date().toISOString(),
    });

    // Start session timer
    sessionTimer.start(properties.chatId);

    // Track user engagement
    userEngagement.recordChatView();
  }
});

User Interaction Events

5. chat_button_clicked

Triggered when the chat toggle button is clicked.

When it triggers: Fires every time the user clicks the main chat toggle button, whether opening or closing the chat interface.

Properties:

• tenant (string): The tenant identifier

• opened (boolean): Whether the chat was opened (true) or closed (false)

• chatId (string): Chat session identifier

• isProactive (boolean): Whether this is a proactive session

• event (string): Event name

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "chat_button_clicked") {
    const action = properties.opened ? "opened" : "closed";

    // Track button interaction
    analytics.track(
      `Chat ${action.charAt(0).toUpperCase() + action.slice(1)}`,
      {
        sessionId: properties.chatId,
        action: action,
      }
    );

    // Update UI state tracking
    if (properties.opened) {
      uiTracker.recordChatOpen();
    } else {
      uiTracker.recordChatClose();
    }
  }
});

6. user_message_sent

Fired when a user sends a message in the chat.

When it triggers: Occurs immediately after a user submits a message in the chat interface, before the bot response.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name

• message (object): Message details

  • text (string): The message content

  • createdAt (string): Timestamp when message was created

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "user_message_sent") {
    // Track user engagement
    analytics.track("User Message Sent", {
      sessionId: properties.chatId,
      messageLength: properties.message.text.length,
      timestamp: properties.message.createdAt,
    });

    // Update conversation metrics
    conversationTracker.recordUserMessage(
      properties.chatId,
      properties.message.text.length
    );

    // Analyze message intent (without logging content for privacy)
    messageAnalytics.analyzeIntent(properties.message.text);
  }
});

7. bot_message_sent

Triggered when the bot sends a message to the user.

When it triggers: Fires when the chatbot or system sends a response message to the user, including automated responses and agent messages.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name

• message (object): Message details

  • text (string): The message content

  • createdAt (string): Timestamp when message was created

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "bot_message_sent") {
    // Track bot response metrics
    analytics.track("Bot Message Sent", {
      sessionId: properties.chatId,
      responseLength: properties.message.text.length,
      timestamp: properties.message.createdAt,
    });

    // Measure response time
    const responseTime = conversationTracker.getResponseTime(properties.chatId);
    if (responseTime) {
      performanceTracker.recordResponseTime(responseTime);
    }

    // Track conversation flow
    conversationAnalytics.recordBotResponse(
      properties.chatId,
      properties.message.text
    );
  }
});

8. cta_button_clicked

Fired when a call-to-action button is clicked within the chat interface.

When it triggers: Occurs when a user clicks any interactive button within chat messages, such as quick reply buttons, links, or action buttons.

Properties:

• tenant (string): The tenant identifier

• button_name (string): Name/identifier of the clicked button

• chatId (string): Chat session identifier

• isProactive (boolean): Whether session was initiated proactively

• event (string): Event name

• link (string): URL of the clicked link (when applicable)

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "cta_button_clicked") {
    // Track CTA interactions
    analytics.track("CTA Button Clicked", {
      buttonName: properties.button_name,
      sessionId: properties.chatId,
      link: properties.link || null,
    });

    // Track conversion funnel
    if (properties.button_name === "schedule_demo") {
      conversionTracker.recordDemoRequest(properties.chatId);
    }

    // Update button performance metrics
    ctaTracker.recordButtonClick(properties.button_name, properties.chatId);
  }
});

Proactive Chat Events

9. chatbot_proactive

Triggered when a proactive chat session is initiated.

When it triggers: Fires when the system automatically initiates a chat session without user interaction, typically based on predefined rules or user behavior patterns.

Properties:

• tenant (string): The tenant identifier

• entry_page (string): Current page URL

• chatId (string): Chat session identifier

• isProactive (boolean): Always true for this event

• event (string): Event name

Implementation Example:

window.quack.trackCallback((eventName, properties) => {
  if (eventName === "chatbot_proactive") {
    // Track proactive engagement
    analytics.track("Proactive Chat Triggered", {
      sessionId: properties.chatId,
      triggerPage: properties.entry_page,
      timestamp: new Date().toISOString(),
    });

    // Update proactive campaign metrics
    proactiveCampaigns.recordTrigger({
      page: properties.entry_page,
      sessionId: properties.chatId,
      tenant: properties.tenant,
    });

    // Track conversion potential
    conversionTracker.recordProactiveStart(properties.chatId);
  }
});

Event Properties Reference

Common Properties

All events include these standard properties:

Property	Type	Description
tenant	string	Unique identifier for the tenant/organization
event	string	The event name (matches the eventName parameter)
chatId	string	Unique identifier for the chat session
isProactive	boolean	Indicates if the session was initiated proactively

Contextual Properties

Additional properties that may be included:

Property	Type	Description
entry_page	string	URL of the page where the event occurred
opened	boolean	Whether chat was opened (for button click events)
button_name	string	Identifier of clicked button
message	object	Message content and metadata
link	string	URL for link-related events

Implementation Details

Best Practices

1. Always register trackCallback early: Set up your tracking callback before initializing chat sessions

2. Handle errors gracefully: Wrap your tracking logic in try-catch blocks

3. Respect user privacy: Ensure compliance with privacy regulations when tracking user data

4. Filter sensitive data: Avoid logging sensitive information in message content

5. Use consistent naming: Follow your organization's event naming conventions

6. In development mode, tracking events are logged to the console instead of being sent to analytics services.

Example Integration

// Set up comprehensive tracking
window.quack.trackCallback((eventName, properties) => {
  // Log for debugging
  console.log("Quack Event:", eventName, properties);

  // Send to multiple analytics services
  try {
    // Google Analytics
    gtag("event", eventName, properties);

    // Custom analytics
    yourAnalytics.track(eventName, {
      ...properties,
      timestamp: new Date().toISOString(),
      source: "quack-sdk",
    });

    // Mixpanel (if using directly)
    mixpanel.track(eventName, properties);
  } catch (error) {
    console.error("tracking error:", error);
  }
});

Troubleshooting

Common Issues

1. Events not firing: Ensure trackCallback is set before chat initialization

2. Missing properties: Check that the chat session is properly established

3. Duplicate events: Verify that trackCallback is only set once

Debug Mode

Enable debug mode by setting localStorage.setItem("quack-debug", "true") to see additional logging information.