A managed component for Dub.co link tracking and ecommerce events
Common use is currently for Cloudflare Zaraz.
- 🔗 Link Click Tracking: Automatically tracks clicks via Dub's click ID cookie
- 📊 Lead Tracking: Track signups, form submissions, and other conversion events
- 💰 Ecommerce Tracking: Track sales, purchases, and revenue events
- 🎯 Customer Attribution: Associate events with customers for accurate attribution
- 🔐 Secure: Uses server-side tracking with API keys
- ⚡ Fast: Minimal overhead with the official Dub TypeScript SDK
Until this component is an "official" Managed Component, we need to manually host the MC in a Cloudflare Worker.
- Clone this repository
- Install dependencies with
pnpm install - Build the component with
pnpm run build - Deploy to Cloudflare Workers:
CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID> \ CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN> \ CLOUDFLARE_EMAIL=<YOUR_EMAIL> \ pnpm run release
- Follow the prompts to setup the Worker
- Login to the Cloudflare dashboard and go to the Zaraz Dashboard
- Choose Custom Managed Component
- Select
custom-mc-zaraz-dubfrom the list - Grant Server network requests permission (required for API calls)
- Grant Access client key-value store permission (recommended for click tracking)
- Configure your Dub API Key in the tool settings
Your Dub API key. You can find this in your Dub workspace settings.
The ID of the Dub workspace you want to send events to.
Pageviews are automatically tracked as lead events:
// Automatic - no code neededTrack signups, registrations, and other lead events:
zaraz.track('track', {
eventName: 'Sign Up',
customerExternalId: 'user_123',
customerEmail: '[email protected]',
customerName: 'John Doe',
})Track purchases and revenue:
zaraz.track('ecommerce', {
eventName: 'Purchase',
customerExternalId: 'user_123',
amount: 9999, // Amount in cents (e.g., $99.99)
currency: 'USD',
invoiceId: 'inv_abc123',
paymentProcessor: 'stripe',
metadata: {
productId: 'prod_123',
plan: 'premium',
},
})Associate a customer ID with the current session:
zaraz.track('identify', {
customerId: 'user_123',
customerEmail: '[email protected]',
customerName: 'John Doe',
})| Field | Type | Required | Description |
|---|---|---|---|
eventName |
string | Yes | Name of the lead event |
customerExternalId |
string | Yes | Unique customer ID in your system |
customerEmail |
string | No | Customer's email address |
customerName |
string | No | Customer's name |
customerAvatar |
string | No | URL to customer's avatar image |
eventQuantity |
number | No | Number of times to track this event |
metadata |
object | No | Additional metadata (max 10,000 characters) |
| Field | Type | Required | Description |
|---|---|---|---|
customerExternalId |
string | Yes | Unique customer ID in your system |
amount |
number | Yes | Sale amount in cents (or full value for zero-decimal currencies) |
currency |
string | No | ISO 4217 currency code (default: USD) |
eventName |
string | No | Name of the sale event |
paymentProcessor |
string | No | Payment processor used (e.g., 'stripe') |
invoiceId |
string | No | Invoice/transaction ID (used for deduplication) |
leadEventName |
string | No | Name of the lead event to attribute this sale to |
customerEmail |
string | No | Customer's email address |
customerName |
string | No | Customer's name |
customerAvatar |
string | No | URL to customer's avatar image |
metadata |
object | No | Additional metadata (max 10,000 characters) |
- Make sure you're running Node.js (>=18.0.0) and pnpm (>=8.0.0)
- Install dependencies with
pnpm install
pnpm run dev- Build with watch modepnpm run test- Run tests oncepnpm run test:dev- Run tests in watch modepnpm run lint- Lint codepnpm run lint:fix- Lint and auto-fix issuespnpm run typecheck- Type check TypeScriptpnpm run build- Full build (lint, typecheck, test, bundle)pnpm run release- Deploy to Cloudflare Workers
Run tests with:
pnpm run testOr in watch mode:
pnpm run test:devDeploy to Cloudflare Workers:
pnpm run releaseThen configure it in the Cloudflare Zaraz Dashboard.
Licensed under the Apache License.