Tracking Engine

v5.0.0 · Core tracking orchestrator with identity resolution, domainprint sync, IndexedDB attribution persistence, custom events API, and native app support.

Public API — `window.impressio`

Method	Returns	Description
`impressio.track(userId)`	`Promise<{fingerprint, domainprint, userId}>`	Manual tracking with custom userId (e.g., after login)
`impressio.getDomainprint()`	`Promise<string>`	Get current domainprint (from cookie or backend)
`impressio.getFingerprint()`	`Promise<string>`	Get current fingerprint hash
`impressio.getIdentity()`	`Promise<{fingerprint, domainprint, userId, debug}>`	Get complete identity info
`impressio.trackEvent(name, data, opts)`	`Promise`	Send custom event (auto-stores conversions in IDB)
`impressio.getAttribution()`	`Promise<Object>`	Export all attribution touchpoints from IndexedDB
`impressio.clearAttribution()`	`Promise`	Wipe attribution data (GDPR right to erasure)
`impressio.version`	`string`	`"5.0.0"`
`impressio.isNativeApp`	`boolean`	Whether running inside a native WebView
`impressio.platform`	`string`	`"web"` \| `"react-native"` \| `"flutter"` \| `"ios-webview"`

Custom Events API

// Standard event
impressio.trackEvent('purchase', {
  value: 49.99,
  currency: 'EUR',
  product_id: 'SKU-123'
});

// Force-mark as conversion
impressio.trackEvent('custom_lead', {
  source: 'contact-form'
}, { conversion: true });

// Auto-conversion events (stored in IndexedDB automatically):
// purchase, signup, lead, add_to_cart, subscribe

Attribution Persistence (IndexedDB)

The engine maintains a local attribution store using IndexedDB (impressio_attribution database). Touchpoints persist for 30 days and are sent with every tracking payload.

Touchpoint Types

Type	Trigger	Data Captured
`campaign`	URL contains UTM or click ID params	utm_source, utm_medium, utm_campaign, gclid, fbclid, etc.
`referral`	External referrer (different hostname)	referrer URL
`pageview`	Every page load	pathname, title, referrer
`event`	`trackEvent()` with conversion flag	eventName, eventData, conversion: true

Attribution Export

const data = await impressio.getAttribution();
// {
//   touchpoints: [...],        // All touchpoints (30-day window)
//   firstTouch: { params },    // First campaign touch
//   lastTouch: { params },     // Last campaign touch
//   totalPageviews: 12,
//   conversions: [...],
//   sessionStart: 1710000000000,
//   sessionEnd: 1710086400000
// }

// Push to your own dataLayer
window.dataLayer.push({
  event: 'impressio_attribution',
  ...data.firstTouch.params
});

Recognized Attribution Parameters

utm_source, utm_medium, utm_campaign, utm_content, utm_term,
gclid, fbclid, ttclid, msclkid, li_fat_id, dclid, twclid

Identity Resolution

The tracking engine maintains a domainprint — a persistent, cross-session identifier stored in cookie __dp. When the backend detects that two domainprints belong to the same user, it returns a primary domainprint in the response, which the client automatically syncs.

Flow:
1. Client sends { fingerprint, domainprint, userId } to POST /t
2. Backend runs identity resolution (fingerprint collision detection)
3. If merge found → response includes { domainprint: "primary-dp" }
4. Client overwrites cookie __dp with primary domainprint
5. All future events use the merged identity

User ID Resolution

The engine resolves userId from multiple sources, in priority order:

data-user-id attribute on <script> tag
window.IMPRESSIO_USER_ID global
window.dataverse?.user?.userID
localStorage.getItem('userId')
Cookie user_id
Fallback: anon_{domainprint[0:16]}

Native App Support

Automatically detects native WebView environments and adapts behavior:

Platform	Detection	Storage
React Native	`window.ReactNativeWebView`	localStorage (no cookies)
Flutter	`window.flutter_inappwebview`	localStorage
iOS WebView	`window.webkit?.messageHandlers`	localStorage
Android WebView	`window.Android`	localStorage

Behavioral V2 Integration

After the main tracking event is sent, the engine starts a 6-second behavioral data collection via window.__behavioralV2. If sufficient data is collected, a second payload is sent with pattern analysis metrics:

Behavioral payload includes:
├─ Mouse: avgVelocity, velocityVariance, angleChange, straightLineRatio
├─ Keyboard: avgInterval, intervalVariance, avgKeyDuration, suspiciouslyRegular
└─ Scroll: avgDelta, deltaVariance, uniformDelta

Tracking Payload Schema

POST https://t.getimpress.io/t
Content-Type: application/json

{
  organizationId: "org-123",
  fingerprint: "abc123...def456...",  // 64 chars
  domainprint: "dp-789...",
  userId: "user@example.com" | "anon_abc123...",
  site: "example.com",
  page: "/product/42",
  referrer: "https://google.com/search?q=...",
  urlParams: "?utm_source=google&gclid=...",
  viewport: "1920x1080",
  timezone: "Europe/Madrid",
  language: "es-ES",
  timestamp: 1710000000000,
  source: "adaptive-tracking",
  strategy: "complete",
  ga4ClientId: "GA1.2.123456789.1710000000",
  attribution: {
    touchpoints_count: 5,
    first_touch: { utm_source: "google", gclid: "..." },
    last_touch: { utm_source: "facebook", fbclid: "..." },
    campaigns_count: 2
  }
}