Campaign attribution

SDK 1.0.3 captures campaign attribution automatically. Initialize analytics once; no campaign option or script attribute is needed:

import { useAnalytics } from "@owleye/analytics";

const analytics = useAnalytics("owl_your_tracking_id");

SDK 1.0.3 automatically captures bounded utm_source, utm_medium, utm_campaign, utm_term, and utm_content values from the current page. Arbitrary query parameters and URL fragments remain excluded by default. Use broad, non-personal campaign labels; never put emails, recipient IDs, secrets, or click IDs in campaign fields. No campaign settings or browser storage are required, and attribution is not persisted after the tags disappear from the URL.

Value limits

Accepted campaign values are trimmed and limited to 200 UTF-8 bytes each. Known emails, URLs, IP addresses, UUIDs, long numeric/token-like values, credential patterns, and invisible control characters are dropped. The automatic query is capped at 2,048 encoded bytes by dropping whole parameters; oversized source queries fail closed. The first occurrence of each case-insensitive key wins, so a later duplicate cannot revive an unsafe value. These checks reduce accidental disclosure; they do not make arbitrary user text safe.

Build and compare a campaign

Use Console → Campaigns to build a link with a campaign, source, and medium. Keyword (utm_term) and content (utm_content) are optional. Use shared placement or creative labels, such as analytics_tools and hero_button, rather than recipient-specific values.

https://your-site.example/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=launch&utm_term=analytics_tools&utm_content=hero_button

Load the tagged URL after collection is permitted, then check Campaigns. Campaign totals remain distinct counts; one visitor can appear in multiple variants, so adding variant visitor counts does not reproduce the overall audience. Small or personal-looking variants are withheld, not reported as zero. Historical events without these fields cannot be backfilled.

What do the reports measure?

Overview acquisition groups recorded pageviews by channel, source tag or referrer. These are pageviews and estimated pageview audiences, not visits or confirmed conversions. A source-only tag such as utm_source=chatgpt.com is sufficient for the AI channel; no campaign or medium tag is required. Recognized AI tags are normalized to a common provider code, such as chatgpt. Unknown labels remain Other or are withheld under the existing privacy threshold.

Campaigns requires a nonempty utm_campaign. It associates activity at or after the first tagged pageview with that campaign within the same fixed 30-minute UTC cohort. Its interactions count includes all custom and rule events, including clicks and visibility rules. It is not a count of successful signups or purchases. The API’s legacy conversions field remains an alias for interactions for compatibility. A source-only AI tag belongs in Overview acquisition, not an invented campaign.

Ordered funnels use selected pageviews and named outcome events. In Pro View, select an AI entry-channel filter to follow cohorts whose selected funnel entry has an AI signal. Later steps do not need to repeat the tag. Track a confirmed outcome where it succeeds; a click or form submission is only an interaction. Funnel entry selection, time windows, retained data and privacy thresholds still apply. Cohorts can merge or split people and cannot establish cross-device identity or causation.

How are AI sources classified?

The channel-v2 rules recognize bounded, case-insensitive AI provider tags and approved referrer host families using one registry. For example, chatgpt.com, chatgpt and openai tags normalize to chatgpt; www.chatgpt.com and its trailing-dot form are recognized referrers. Host matches require a domain boundary: notchatgpt.com and chatgpt.com.attacker.example are not ChatGPT.

Paid and email medium tags take channel precedence. An arrival tagged utm_source=newsletter&utm_medium=email with a ChatGPT referrer is classified as Email; the source and observed referrer remain available in their separate breakdowns. Those aggregate views do not establish a row-level link between their audiences. The version describes report-time classification of retained signals; raw recorded tags and hosts are unchanged.

A source tag can be copied or manually supplied. A referrer describes an observed referring surface. Neither proves an AI user, recommendation or influence. Without a recognized source or external referrer, traffic stays Direct / unknown. The AI analyst analyzes recorded evidence; it cannot reconstruct an absent acquisition signal. AI crawler activity is a separate population from AI referrals.

For an untagged SPA route, current-event tags remain empty. An ordered funnel or the documented campaign cohort join can associate later events with earlier evidence; the SDK does not silently rewrite the later URL, use browser storage, or persist a first-touch campaign across documents.

Privacy and upgrades

Full captureQuery remains a broader opt-in. Do not enable it just for campaigns. URL fragments also remain excluded unless explicitly enabled. Known personal-looking labels are rejected, but that is not a guarantee that arbitrary text is safe: operators must use non-personal labels. Existing consent gates and Global Privacy Control behavior still apply.

Remove old captureCampaigns options and data-owleye-capture-campaigns attributes. They no longer affect collection, including when set to false; a deprecated no-op TypeScript field lets old source compile. Keep the SDK aligned with the matching API deployment and review visitor notices when upgrading.

For script tags, see CDN tracking examples. Rules and performance bundles use the same automatic attribution policy. Collection describes tagged events and is not persistent first-touch or cross-session advertising attribution. Privacy defaults still apply.