> ## Documentation Index
> Fetch the complete documentation index at: https://dub-mintlify-update-supabase-lead-tracking-guide-82850.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Server-side tracking
> Learn how to track lead conversion events with Dub using server-side tracking
Conversion tracking requires a [Business plan](https://dub.co/pricing)
subscription or higher.
When it comes to [conversion tracking](/conversions/quickstart), a `lead` event happens when a user performs an action that indicates interest in your product or service. This could be anything from:
* Signing up for an account
* Booking a demo meeting
* Joining a mailing list
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application as lead events on Dub.
## Prerequisites
First, you'll need to enable conversion tracking for your Dub links to be able to start tracking conversions:
If you're using [Dub Partners](/partners/quickstart), you can skip this step
since partner links will have conversion tracking enabled by default.
To enable conversion tracking for all future links in a workspace, you can do the following:
To enable conversion tracking for all future links in a workspace, you can do the following:
1. Navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics).
2. Toggle the **Workspace-level Conversion Tracking** switch to enable conversion tracking for the workspace.
This option will enable conversion tracking in the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) for all future links.
If you don't want to enable conversion tracking for all your links in a workspace, you can also opt to enable it on a link-level.
To enable conversion tracking for a specific link, open the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) for a link and toggle the **Conversion Tracking** switch.
You can also use the `C` keyboard shortcut when inside the link builder to
quickly enable conversion tracking for a given link.
Alternatively, you can also enable conversion tracking programmatically via the [Dub API](/api-reference/introduction). All you need to do is pass `trackConversion: true` when creating or updating a link:
```javascript Node.js
const link = await dub.links.create({
url: "https://dub.co",
trackConversion: true,
});
```
```python Python
link = d.links.create(url="https://dub.co", track_conversion=True)
```
```go Go
link, err := d.Links.Create(ctx, &dub.CreateLinkRequest{
URL: "https://dub.co",
TrackConversion: true,
})
```
```ruby Ruby
s.links.create_many(
::OpenApiSDK::Operations::CreateLinkRequest.new(
url: "https://dub.co",
track_conversion: true,
)
)
```
Then, you'd want to install the `@dub/analytics` script to your website to track conversion events.
You can install the `@dub/analytics` script in several different ways:
}
href="/sdks/client-side/installation-guides/framer"
horizontal
/>
You can **verify the installation** with the following tests:
1. Open the browser console and type in `_dubAnalytics` – if the script is installed correctly, you should see the `_dubAnalytics` object in the console.
2. Add the `?dub_id=test` query parameter to your website URL and make sure that the `dub_id` cookie is being set in your browser.
If both of these checks pass, the script is installed correctly. Otherwise, please make sure:
* The analytics script was added to the `` section of the page
* If you're using a content delivery network (CDN), make sure to purge any cached content
## Quickstart
Depending on which authentication framework you're using, we have a few pre-built guides to help you track lead events when a new user signs up for your SaaS application:
If you're not using any of the frameworks listed above, you can use the following steps to track lead events:
1. Within the sign-up API request, retrieve the `dub_id` cookie that was created by the [`@dub/analytics` client-SDK](/sdks/client-side/introduction).
2. Send an event to the Dub API with the `dub_id` value, as well as your customer's ID and any other relevant information (email, name, avatar, etc.)
If you don't have a customer ID, you can also use the customer's `email`
instead.
## Code examples
Here are some examples of how you can track lead events using our [native SDKs](/sdks/overview):
```javascript Node.js
import { Dub } from "dub";
const dub = new Dub();
const dubId = req.cookies["dub_id"];
if (dubId) {
await dub.track.lead({
clickId: dubId,
eventName: "Sign Up",
customerExternalId: customer.id,
customerName: customer.name,
customerEmail: customer.email,
customerAvatar: customer.avatar,
});
// delete the dub_id cookie
res.cookies.set("dub_id", "", {
expires: new Date(0),
});
}
```
```python Python
from dub import Dub
import os
dub = Dub(token=os.environ['DUB_API_KEY'])
dub_id = request.cookies.get('dub_id')
if dub_id:
dub.track.lead({
'click_id': dub_id,
'event_name': 'Sign Up',
'external_id': customer.id,
'customer_name': customer.name,
'customer_email': customer.email,
'customer_avatar': customer.avatar
})
# delete the dub_id cookie
response.delete_cookie('dub_id')
```
```go Go
package main
import (
"context"
dub "github.com/dubinc/dub-go"
"net/http"
)
d := dub.New(
dub.WithSecurity(os.Getenv("DUB_API_KEY")),
)
dubId, err := r.Cookie("dub_id")
if err == nil {
_, err = d.Track.Lead(context.Background(), &operations.TrackLeadRequest{
ClickId: dubId.Value,
EventName: "Sign Up",
customerExternalId: customer.ID,
CustomerName: customer.Name,
CustomerEmail: customer.Email,
CustomerAvatar: customer.Avatar,
})
// delete the dub_id cookie
http.SetCookie(w, &http.Cookie{
Name: "dub_id",
Value: "",
Expires: time.Unix(0, 0),
})
}
```
```ruby Ruby
require 'dub'
dub = ::OpenApiSDK::Dub.new
dub.config_security(
::OpenApiSDK::Shared::Security.new(
token: ENV['DUB_API_KEY']
)
)
dub_id = cookies[:dub_id]
if dub_id
req = ::OpenApiSDK::Operations::TrackLeadRequest.new(
click_id: dub_id,
event_name: 'Sign Up',
external_id: customer.id,
customer_name: customer.name,
customer_email: customer.email,
customer_avatar: customer.avatar
)
dub.track.lead(req)
# delete the dub_id cookie
cookies.delete(:dub_id)
end
```
```php PHP
setSecurity($_ENV["DUB_API_KEY"])->build();
$dubId = $_COOKIE['dub_id'] ?? null;
if ($dubId) {
$request = new Operations\TrackLeadRequest();
$request->clickId = $dubId;
$request->eventName = 'Sign Up';
$request->customerExternalId = $customer->id;
$request->customerNasme = $customer->name;
$request->customerEmail = $customer->email;
$request->customerAvatar = $customer->avatar;
$dub->track->lead($request);
// delete the dub_id cookie
setcookie('dub_id', '', time() - 3600);
}
```
Here's the full list of attributes you can pass when sending a lead event:
| Property | Required | Description |
| :------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clickId` | **Yes** | The unique ID of the click that the lead conversion event is attributed to. You can read this value from `dub_id` cookie. If an empty string is provided (i.e. if you're using [tracking a deferred lead event](/conversions/leads/deferred)), Dub will try to find an existing customer with the provided `customerExternalId` and use the `clickId` from the customer if found. |
| `eventName` | **Yes** | The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the `leadEventName` prop in `/track/sale`). |
| `customerExternalId` | **Yes** | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. |
| `customerName` | No | The name of the customer. If not passed, a random name will be generated (e.g. "Big Red Caribou"). |
| `customerEmail` | No | The email address of the customer. |
| `customerAvatar` | No | The avatar URL of the customer. |
| `mode` | No | The mode to use for tracking the lead event. `async` will not block the request; `wait` will block the request until the lead event is fully recorded in Dub; `deferred` will defer the lead event creation to a subsequent request. |
| `metadata` | No | Additional metadata to be stored with the lead event. Max 10,000 characters. |
## View your conversions
Once you've completed the setup, all your tracked conversions will show up in [Dub Analytics](https://dub.co/analytics). We provide 3 different views to help you understand your conversions:
* **Time-series**: A [time-series view](https://app.dub.co/dub/analytics?view=timeseries) of the number clicks, leads and sales.
* **Funnel chart**: A [funnel chart view](http://app.dub.co/analytics?view=funnel) visualizing the conversion & dropoff rates across the different steps in the conversion funnel (clicks → leads → sales).
* **Real-time events stream**: A [real-time events stream](https://app.dub.co/events) of every single conversion event that occurs across all your links in your workspace.
