Skip to content

BRD-002 URL Journey Tracking

BRD – SDK-Based URL & UTM Journey Tracking Mapped to Chat Session

Product: MachineAvatars
Feature: SDK-Level URL Journey Capture & Session Mapping

1. Background & Problem Statement

  • MachineAvatars is deployed on customer websites using a JavaScript SDK.
  • While users interact with the chatbot, they navigate across multiple internal pages.
  • Without SDK-level tracking, the complete URL and UTM journey cannot be reliably captured or mapped to a chatbot session.

2. Objective

Using the MachineAvatars SDK, capture the full URL and UTM journey of a user—from entry to exit—during an active chatbot session and store it mapped to a unique Session ID.

3. Scope

In-Scope

  • Capture entry URL and UTM parameters at session initialization via SDK.
  • Capture all internal URL changes during an active chatbot session.
  • Maintain chronological order of visited URLs.
  • Map the complete journey to a single Session ID.

Out-of-Scope

  • Cross-tab or cross-device journey tracking.
  • User-level identity tracking beyond session scope.
  • Analytics dashboards or visualization.

4. User Personas

  • End User: Navigates the website while chatting.
  • Customer Admin (Indirect): Expects accurate session-level journey data.

5. High-Level User Flow

  1. Customer embeds the MachineAvatars SDK on the website.
  2. User lands on the site (with or without UTMs).
  3. SDK initializes chatbot session and generates Session ID.
  4. SDK captures entry URL and UTM parameters.
  5. User navigates across internal URLs.
  6. SDK captures each URL change in sequence.
  7. Session ends via close, timeout, or exit.
  8. Complete journey is stored against the Session ID.

6. Functional Requirements

  • FR-1: SDK shall capture the entry URL at chatbot session initialization.
  • FR-2: SDK shall capture standard UTM parameters at session start.
  • FR-3: SDK shall detect and record all internal URL changes during the session.
  • FR-4: All recorded URLs shall be stored in chronological order.
  • FR-5: The full URL journey shall be mapped to a single Session ID.

7. Constraints & Non-Functional Requirements

  • SDK tracking must not affect page navigation performance.
  • Must support both SPA route changes and full page navigations.
  • Data capture must be lightweight and non-blocking.

8. Acceptance Criteria

  • Given the SDK is installed, when a chatbot session starts, then entry URL and UTMs are captured.
  • Given the user navigates internally, when the session is active, then each URL is recorded in order.
  • Given the session ends, when stored, then the full journey is retrievable via Session ID.
  • Given multiple sessions, when queried, then journeys remain isolated per Session ID.