Tracking installation guide

GEO Tracking collects pseudonymous AI referral, assisted-session, crawler, engagement and conversion events. It does not collect PII by default and applies the consent state supplied by the implementation.

Collection topology

Before installation

1. Open the workspace Tracking page.
2. Create a tracking site for the exact production hostname.
3. Add allowed origins, including staging only when that environment intentionally shares the site.
4. Select consent mode and retention between 1 and 730 days.
5. Copy the one-time site write token.
6. Store the token in the appropriate deployment/tag configuration; it is not a platform API key.

Prefer separate tracking sites and tokens for development, staging and production.

Browser script

<script
  async
  src="https://geo.thyris.cloud/geo.js"
  data-site="SITE_ID"
  data-token="geo_site_one_time_write_token"
  data-endpoint="https://geo.thyris.cloud/api/v2/geo/events"
  data-consent="granted"
></script>

Use the consent value produced by the site's consent-management logic. Do not hardcode granted unless the applicable policy and user choice make it true.

Next.js

Install @thyris/geo-tracking, then mount the Next.js integration from @thyris/geo-tracking/next in the application layout. Configure collector URL, site token and consent through server-safe configuration.

Use the server client for trusted conversion events. Never import a server-only platform API key or provider credential into a client component.

Server-side Events API

Endpoint:

POST https://geo.thyris.cloud/api/v2/geo/events

Authentication:

x-geo-site-token: geo_site_one_time_write_token

Example batch:

{
  "events": [
    {
      "name": "campaign_conversion",
      "idempotencyKey": "order-2026-000123-campaign-conversion",
      "occurredAt": "2026-09-20T12:00:00.000Z",
      "sessionId": "pseudonymous-browser-session",
      "pageUrl": "https://brand.example/campaign",
      "referrer": "https://chatgpt.com/",
      "targetId": "TARGET_UUID",
      "campaignId": "CAMPAIGN_UUID",
      "consent": "granted",
      "source": "server",
      "properties": {
        "conversionType": "qualified_lead"
      }
    }
  ]
}

One batch accepts 1–100 events. idempotencyKey is required and must be stable for the same logical event. The collector returns accepted, duplicate, rejected and received counts.

Event schema

Field	Required	Contract
name	Yes	Event name, 2–120 characters
idempotencyKey	Yes	8–255 characters; unique per workspace logical event
occurredAt	No	ISO 8601 timestamp; server time is used when absent
sessionId	No	Pseudonymous source ID; hashed with site context
pageUrl	No	Maximum 4096 characters; sensitive query keys are removed
referrer	No	Maximum 4096 characters; classified and sanitized
targetId	No	Workspace target UUID
campaignId	No	Workspace campaign UUID
consent	Yes	granted, denied, or not_required
properties	No	Event-specific JSON without secrets or unnecessary PII
source	No	browser, server, import, or webhook; default browser
sdkVersion	No	SDK version, maximum 40 characters

Recognized event names

Event	Recommended use
ai_referral_visit	Landing visit with an eligible AI referrer
ai_assisted_session	Session influenced by a recognized AI interaction
page_view	Page view used for journey context
engagement	Meaningful engagement defined by the workspace
lead	Lead creation
signup	Account or subscription signup
purchase	Completed purchase outcome
campaign_conversion	Campaign-defined conversion
content_interaction	Interaction with a measured content asset
crawler_visit	AI crawler observation
publication_exposure	Exposure to a GEO-managed publication

Custom names are accepted by the event schema, but use a governed naming/version convention so reporting remains consistent.

Referrer classification

Managed classification recognizes ChatGPT, Perplexity, Gemini, Microsoft Copilot, Claude, Meta AI and You.com domains. Other AI-like hostnames remain unknown_ai; GEO does not guess them into a named provider. Non-AI sources remain referral/direct/unknown as applicable.

Google Tag Manager

Import the GEO template, then configure:

• HTTPS collector URL
• Site write token
• Event name and idempotency value
• Page/referrer/campaign variables
• Consent mapping, including analytics_storage

Preview the container and verify accepted/rejected counts before publishing the GTM version.

WordPress

Install the GEO tracking plugin and configure it under Settings > Thyris GEO. The plugin requires HTTPS for frontend collection and passes available WordPress consent state. Confirm caching/minification does not remove data attributes or duplicate initialization.

Consent behavior

When the site's consent mode is required, events whose payload consent is not granted are rejected with reason consent_required. not_required should only be used when the workspace's legal/privacy owner has confirmed that configuration.

Consent state is operational input, not legal advice. Align it with the customer's consent-management platform and jurisdictional requirements.

URL and session privacy

• URL username, password and fragments are removed.
• Query keys resembling e-mail, phone, name, token, secret, password or address are removed.
• Supplied session IDs are hashed with the tracking site; raw IDs are not used as canonical identities.
• Avoid sending PII or secrets in properties.
• Apply and test retention and data-subject workflows before production.

Validation procedure

1. Open the site from an allowed origin.
2. Send one page_view with granted consent and a unique idempotency key.
3. Send it again and confirm the second event is counted as duplicate.
4. Test a denied/missing consent state according to site policy.
5. Test an unauthorized origin and invalid/revoked token.
6. Send a server conversion linked to the pseudonymous session.
7. Confirm sanitized URL, referrer classification, target/campaign link and source.
8. Confirm Tracking and Attribution dashboards show coverage and limitations.
9. Test token rotation and old-token revocation.
10. Test retention maintenance and a privacy access/delete request.

Troubleshooting

Symptom	Check
401 Site token required	x-geo-site-token or bearer header is present
401 Invalid or inactive site token	Correct environment/site, token not revoked/expired, site active
403 Origin is not allowed	Exact origin/hostname in allowed origins
400 Invalid event batch	Batch size, required fields, timestamp, UUIDs and enums
422 with rejected events	Consent mode and per-event rejection reasons
Duplicate count increases	Reused idempotency key for the same or different logical event
AI source is unknown	Referrer URL/hostname and managed-classifier coverage
Attribution is low confidence	Tracking coverage, session continuity, touchpoints and sample size

Related documentation

• Tracking, impact, and attribution
• Security, privacy, and governance
• API, SDK, and MCP