Skip to Content
DocumentationWeb SDKInstallation

Installation

Install the Package

npm install @attributehq/web-sdk

CDN (Script Tag)

Pin to a major version for automatic patch updates:

<script src="https://unpkg.com/@attributehq/web-sdk@1/dist/attribution.umd.js"></script>

Or pin to an exact version:

<script src="https://cdn.jsdelivr.net/npm/@attributehq/web-sdk@1.0.0/dist/attribution.umd.js"></script>

When using CDN, the SDK is available as window.AttributeHQ:

<script>
  AttributeHQ.init({
    apiKey: 'ak_your_api_key',
    appId: 'your-app-uuid',
  })
</script>

Initialization

Call init() once, as early as possible. The SDK is a singleton — calling init() a second time is a no-op.

import { init } from '@attributehq/web-sdk'
 
init({
  apiKey: 'ak_your_api_key',
  appId: 'your-app-uuid',
})

What Happens on Init

  1. Configuration is validated and defaults applied
  2. A new session is created (or resumed if within 30-minute window)
  3. If this is the user’s first visit (__ahq_installed not in localStorage), the SDK sends an install request and stores the attribution result
  4. If autoTrackPageViews is enabled (default), the initial page view is tracked and SPA navigation is monitored

Configuration Options

OptionTypeDefaultDescription
apiKeystring—Required. API key from your dashboard (format: ak_xxx)
appIdstring—Required. App UUID from your dashboard
batchSizenumber10Number of events per batch before auto-flush
flushIntervalnumber5000Time in ms between automatic flush attempts
maxQueueSizenumber100Maximum events stored in the offline queue
autoTrackPageViewsbooleantrueAuto-track page views including SPA navigation
debugbooleanfalseLog debug messages to console

Framework Examples

Next.js / React

'use client'
 
import { useEffect } from 'react'
import { init } from '@attributehq/web-sdk'
 
export function AttributeHQProvider({ children }) {
  useEffect(() => {
    init({
      apiKey: 'ak_your_api_key',
      appId: 'your-app-uuid',
    })
  }, [])
 
  return children
}

Always initialize in a useEffect to ensure the SDK runs client-side only. The SDK requires window and localStorage.

Vanilla HTML

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@attributehq/web-sdk@1/dist/attribution.umd.js"></script>
</head>
<body>
  <script>
    AttributeHQ.init({
      apiKey: 'ak_your_api_key',
      appId: 'your-app-uuid',
    })
  </script>
</body>
</html>
OverviewEvent Tracking