attribution-kit

Multi-touch marketing attribution for Vue 3 and Nuxt.

Track where every visitor came from — UTM parameters, referrer, or direct — and attach a full touch history to your API requests. Works as a framework-agnostic core, a Vue composable, or a zero-config Nuxt module.

Features

• 🎯 Multi-touch tracking — records every source a visitor arrives from, not just the first or last.
• 🔗 UTM + referrer resolution — falls back from UTM → referrer → "Direct" automatically.
• 💾 Persistent — stores touches in localStorage with a configurable expiry (default 30 days).
• 🧹 Deduplicated — the same source on the same day isn't recorded twice.
• 📦 Three entry points — pure core, Vue composable, Nuxt module. Use what you need.
• 🟦 Fully typed — written in TypeScript, ships with declarations.

Installation

npm install attribution-kit

vue and nuxt are optional peer dependencies — install only what your project uses.

Usage

Vue 3

import { useTracking } from 'attribution-kit/vue'

const { tracking, getPayload } = useTracking({ ttlDays: 30 })

// `tracking` is reactive — read first/last source, touch history, etc.
console.log(tracking.value)

// attach attribution to outgoing requests (e.g. in an axios interceptor)
axios.interceptors.request.use((config) => {
  if (['post', 'put', 'patch'].includes(config.method ?? '')) {
    config.data = { ...config.data, ...getPayload() }
  }
  return config
})

Optionally register the plugin to share options app-wide:

import { createApp } from 'vue'
import Attribution from 'attribution-kit/vue'

createApp(App).use(Attribution, { ttlDays: 30 }).mount('#app')

Nuxt

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['attribution-kit/nuxt'],

  attribution: {
    ttlDays: 30,
  },
})

That's it. Tracking initializes automatically on first load, and useTracking() is auto-imported everywhere — no manual import needed:

<script setup lang="ts">
const { tracking, getPayload } = useTracking()
</script>

Framework-agnostic core

For any other environment (vanilla JS, a Node script, another framework):

import { createTracker } from 'attribution-kit'

const tracker = createTracker({ ttlDays: 30 })
tracker.init()

const payload = tracker.getPayload()

Configuration

| Option | Type | Default | Description | | ------------ | -------- | ------------------------ | -------------------------------------------- | | ttlDays | number | 30 | How long touches are kept before expiring. | | storageKey | string | "attribution_touches" | The localStorage key used to persist data. |

Payload shape

getPayload() returns an object ready to send with your API requests:

{
  "tracking": {
    "first_visit_time": "2026-01-01T10:00:00.000Z",
    "first_source": "Google Ads",
    "last_source": "WhatsApp",
    "touches_count": 3,
    "touches": [
      {
        "source": "Google Ads",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "winter-sale",
        "timestamp": "2026-01-01T10:00:00.000Z"
      }
    ]
  }
}

License

MIT © Kerolos Sadek