Thunder Script

Thunder Script is a lightweight, asynchronous snippet (typically added in your site’s <head>) that collects visitor, source, and login attribution data in real time. By embedding a small JavaScript file, Thunder can:

Identify visitors across sessions (durable device/user identifier)

Capture landing (first-visit) context: referrer, UTM parameters, and click IDs

Detect and attribute logins (when you provide customer info in localStorage)

Persist key attribution parameters while gracefully handling browser storage limitations

Quick Start

Install the script (add to your <head>):

On customer login, set their details in localStorage under the key user:

That’s it. Thunder will:

Send a one-time “landing” event for the session

Automatically send a “login” event once the user object is present and the landing is recorded

What Thunder Collects

Page visit context (landing event)

Domain

Referrer domain (or “direct visit”)

UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)

Click IDs (gclid, dclid, wbraid, gbraid, fbclid, ttclid, sccid → normalized to thdr_* fields)

Thunder-generated IDs: uid (persistent) and jid (journey/session)

Same context as above, plus your provided customer attributes:

email (lowercased)

phone (normalized to E.164-like format, e.g., +15551234567)

Note: Thunder does not collect payment details or other sensitive fields by default. Only the data you provide (e.g., user object) and the visitor/session attribution context are sent.

How Thunder Works

1) Initial Load (Async)

The script loads asynchronously and immediately attempts to:

Generate or retrieve a durable uid (stored in localStorage and sessionStorage, falling back to cookies when needed)

Create a session-like jid (stored non-persistently)

Normalize and store referrer and UTM/click identifiers

2) UTM and Referrer Propagation

Thunder inspects the current URL and the document referrer:

If a ref param is missing and the referrer domain is different from the current domain, Thunder appends ref=<referrer-domain>.

If UTM or click ID params are missing on the current page but present on the referrer, Thunder appends normalized “thdr_” parameters to preserve attribution:

UTM params mirrored as: thdr_utm_source, thdr_utm_medium, thdr_utm_campaign, thdr_utm_term, thdr_utm_content, plus custom tg/tm/tk/ts groups (tg1–tg4, tm1–tm4, tk1–tk4, ts1–ts4), ti, tc.

Click ID mappings:

gclid, dclid, wbraid, gbraid → thdr_tg0

fbclid → thdr_tm0

ttclid → thdr_tk0

sccid → thdr_ts0

When parameters are added, Thunder uses history.replaceState (or falls back to redirect) to update the URL without additional page loads.

3) Event Collection

Landing event

Sent once per session when no prior landing was recorded (requestSent flag).

Includes uid, jid, domain, referrer domain (or “direct visit”), and all captured UTM/click identifiers.

If the user object is already present, Thunder also flags login as sent for the session.

Automatically sent once per session after the landing event is recorded and a valid user object is found in localStorage.

Thunder polls briefly (every ~25ms) for the presence of user and then sends the event exactly once (loginSent flag).

Transport & resilience

Data is POSTed to: https://trythunder.app/api/thnder/custom

Network calls use exponential backoff and retry.

Errors are POSTed to: https://trythunder.app/api/thnder/error

4) Session Management

uid (durable ID): generated via crypto.randomUUID() when available (fallback to RFC4122 v4-like). Stored persistently (localStorage) and mirrored in session storage (and cookies as a last resort).

jid (journey/session): generated for the visit and stored non-persistently to mark session boundaries.

Keys Thunder uses in storage

uid (persistent): durable visitor id

jid (session): journey/session id

utms (session): JSON string of captured UTM/click params

referrer (session): normalized referrer domain

requestSent (session): landing sent flag

loginSent (session): login sent flag

Thunder prioritizes:

sessionStorage/localStorage when available

Cookies (SameSite=Lax) as a fallback

Benefits

Durable identity across sessions: A single uid helps bind sessions together.

Better attribution: UTMs and click IDs are preserved, even when the landing page lacks them but the referrer had them.

Automatic login attribution: Tie authenticated actions back to the same visitor/session without additional code.

Resilient delivery: Retries with exponential backoff; graceful fallbacks for storage.

Privacy and Compliance

Consent: Depending on your region (e.g., GDPR, CCPA), configure consent banners and ensure Thunder Script only runs and/or stores identifiers after consent where required.

Data you provide: If you store email and mobile in localStorage.user, Thunder will transmit those values as provided. Consider hashing or tokenizing customer identifiers on your side if required by your policies.

Cookies and storage: Thunder uses SameSite=Lax for cookies and prefers web storage when available.

No sensitive payment data: Thunder does not collect payment details by default.

Always consult your legal team to ensure your implementation complies with applicable regulations.

Troubleshooting

No events appearing

Ensure the script tag is present in <head> and reachable: https://cdn.trythunder.app/public/custom.js

Confirm the page isn’t blocked by CSP from loading the script or posting to trythunder.app

Check that at least one storage mechanism is available (localStorage, sessionStorage, or cookies)

Verify that localStorage.getItem("user") returns a valid JSON object with at least one of: id, email, or mobile

Ensure a landing event has been recorded (Thunder waits for landing → then sends login)

Confirm you didn’t previously set loginSent during this session

UTM parameters missing

Thunder only appends UTMs from the referrer if they are missing on the current URL

Confirm the referrer URL actually contains the expected UTM or click ID parameters

Key Takeaways

Easy setup: Add one script tag and start collecting landing/login attribution immediately.

Unified identity: Durable uid and per-session jid help connect events over time.

Robust attribution: UTMs and click IDs are preserved and propagated.

Privacy-aware: Honors your consent gating. You control what customer data you provide.

1. Script integration

Thunder Script#

Quick Start#

What Thunder Collects#

How Thunder Works#

1) Initial Load (Async)#

2) UTM and Referrer Propagation#

3) Event Collection#

4) Session Management#

Keys Thunder uses in storage#

Benefits#

Privacy and Compliance#

Troubleshooting#

Key Takeaways#