SegOps AIDocs

AI Session Detection (M16a)

Track when users arrive at your site from AI-powered search engines. The `ai_referral_session` event is the foundation for understanding AI-driven traffic and (once 30 days of data accumulates) attributing conversions to AI discovery.

What it does#

When a user lands on a page after clicking a result in ChatGPT, Perplexity, Claude, Gemini, or Grok, trackPageView() automatically detects the AI source from document.referrer and emits an ai_referral_session event through the standard ingestion pipeline. No backend changes required.

SDK Integration#

typescript
import { SegOpsClient } from '@segops/sdk';

const segops = new SegOpsClient({ apiUrl: 'https://...', apiKey: 'sk_...' });

// Call on every page load (e.g. in _app.tsx or layout.tsx)
segops.trackPageView({ userId: currentUser?.id });

trackPageView() always emits a page_viewed event. It additionally emits ai_referral_session when document.referrer matches a known AI provider domain.

SegOpsPageView options#

FieldTypeDefaultDescription
userIdstring'anonymous'User identifier
pathstringwindow.location.pathnameOverride detected path

Detected providers#

ProviderMatched domains
chatgptchatgpt.com, chat.openai.com
perplexityperplexity.ai
claudeclaude.ai
geminigemini.google.com
grokgrok.com, x.com

ai_referral_session event payload#

json
{
  "source_provider": "chatgpt",
  "query_hint": "best running shoes",
  "landing_url": "https://example.com/products/shoes",
  "referrer_url": "https://chatgpt.com/?q=best+running+shoes"
}

query_hint is extracted from ?q=, ?query=, or ?search= params on the referrer URL. It is null if none are present.

Analytics dashboard#

Navigate to /analytics → AI Referrals tab to see:

  • Total AI-referred sessions (30-day rolling)
  • Sessions per day bar chart
  • Provider breakdown table
  • Top 10 landing pages

Data model#

AIReferralSource (Postgres, global config table — not tenant-scoped):

FieldTypeDescription
providervarchar(64)Unique provider ID
domain_patternsjsonbList of matched hostnames
display_namevarchar(128)Human-readable label

Seeded via migration ingestion/0003_seed_aireferralsource.py.

Integration with other features#

  • Segments (Module 1): Create a segment with event_count condition on ai_referral_session to identify users who arrived via AI search.
  • M16b (deferred): Once 30 days of data accumulates, the attribution model links ai_referral_session events to downstream conversions.

Key code paths#

  • SDK detection: sdks/typescript/src/client.ts — _detectAiReferrer(), _extractQueryHint(), trackPageView()
  • Analytics endpoint: apps/api/apps/analytics/views.py — ai_referral_sessions()
  • ClickHouse queries use JSONExtractString(payload, 'field') — payload is stored as a raw JSON String