@suucha/attribution-web

Web attribution capture and persistence for Suucha Web SDK. Parses URL utm_* params, click IDs (gclid / fbclid / ttclid / msclkid), and infers media_source from document.referrer.

Install

pnpm add @suucha/core @suucha/web @suucha/attribution-web

Usage

import { suucha } from '@suucha/core';
import { setupWeb } from '@suucha/web';
import { AttributionWeb } from '@suucha/attribution-web';

setupWeb();

const attribution = new AttributionWeb({
  touchModel: 'first',  // 'first' | 'last' | 'both'
  cookieTtlDays: 30,
});

suucha.addParameterIntercept(attribution);

// Now every event auto-includes 'attr_*' params:
//   attr_media_source, attr_medium, attr_campaign, attr_gclid, ...
suucha.log('page_view');

Touch Models

| Model | Behavior | Use Case | |---|---|---| | 'first' (default) | Persists on first visit; subsequent visits don't overwrite | "Where did this user come from originally?" | | 'last' | Overwrites on every visit with new attribution | "Where did this user come from most recently?" | | 'both' | Stores both, attaches merged on events | Custom attribution modeling downstream |

Captured Fields

| Field | Source | |---|---| | media_source | utm_source, or inferred from referrer | | medium | utm_medium, or inferred | | campaign | utm_campaign | | content | utm_content | | term | utm_term | | gclid | Google Ads click ID | | fbclid | Facebook click ID | | ttclid | TikTok click ID | | msclkid | Bing Ads click ID | | landing_path, landing_url | First page visited | | referrer | document.referrer | | captured_at | Capture timestamp |

Custom Referrer Rules

import { AttributionWeb, DEFAULT_REFERRER_RULES } from '@suucha/attribution-web';

const attr = new AttributionWeb({
  referrerInferRules: [
    ...DEFAULT_REFERRER_RULES,
    {
      pattern: /^https?:\/\/my-partner\.com\//i,
      mediaSource: 'my-partner',
      medium: 'partnership',
    },
  ],
});

Cookie Names

• suucha_attribution_first — first-touch record
• suucha_attribution_last — last-touch record

Override via cookieName: 'my_prefix'.

License

MIT © Suucha Studio