Click on the **Create API Key** button to create the key. Make sure to copy your API key and store it in a safe place. You won't be able to see it again.
[Webhooks](/concepts/webhooks/introduction) are *push-based*, meaning that Dub will send events to your webhook receiver endpoint when specific events occur, while a REST API is *pull-based*, meaning that you need to consistently poll the API endpoint to get real-time updates.
Check out our [webhooks documentation](/concepts/webhooks/introduction) to learn more.
# API keys
Source: https://dub.co/docs/api-reference/tokens
Learn how API keys work on Dub.
API keys on Dub allow you to access your workspace programmatically. This is useful for integrating Dub into your application or with other tools and services.
Each API key is tied to a specific workspace – meaning you can use it to access that workspace's resources without having to worry about "leaking" access to other workspaces.
API keys on Dub follow the format:
```bash .env
DUB_API_KEY=dub_xxxxxxxx
```
By default, you can use this key to perform any API request without restriction, so it must be stored securely in your app's server-side code (such as in an environment variable or credential management system). Don’t expose this key on a website.
## Create an API key
You can create an API key by following these steps:
Click on the **Create API Key** button to create the key. Make sure to copy your API key and store it in a safe place. You won't be able to see it again.
These machine users will show up on your workspace's **People** tab, but will not contribute to your workspace's user count.
# Location data
Source: https://dub.co/docs/concepts/analytics/location
When a user clicks a link without the app installed, they're redirected to the app store. After installing and opening the app, you can retrieve the original link information and redirect them to the appropriate screen.
## Android Play Store
Android provides the [Install Referrer API](https://developer.android.com/google/play/installreferrer) which allows you to retrieve information about how a user came to install your app, including the referrer URL.
Here is how it works in a nutshell:
1. User taps a deep link on a device without your app installed
2. Dub redirects the user to the App Store or Play Store by using [device targeting](https://dub.co/help/article/device-targeting)
3. User installs your app from the app store
4. App reads the install referrer on first launch
5. App extracts the deep link from the referrer URL and tracks the deep link open event using the [`/track/open` endpoint](/api-reference/endpoint/track-open)
6. Redirect the user to the appropriate screen using the destination URL returned by the `/track/open` endpoint
### Understanding the Referrer URL Structure
When Dub redirects users to the Play Store, the referrer URL contains the deep link information in a nested structure. The referrer URL looks like this:
```
https://play.google.com/store/apps/details?id=com.example.app&referrer=deepLink%3Dhttps%253A%252F%252Fdub.sh%252Fgps
```
To extract the original deep link, you need to:
1. Parse the `referrer` parameter from the Play Store URL
2. URL decode it to get the `deepLink` parameter
3. URL decode the `deepLink` value to get the actual deep link
The code examples below show how to implement this extraction process.
### Step 1: Add the Install Referrer dependency
First, you'll need to add the Google Play Install Referrer library to your project.
This page displays two options:
* **Get the App**: Copies the deep link to the clipboard before redirecting to the App Store.
* **Get the App without Copying**: Redirects directly to the App Store without copying the deep link to the clipboard.
After the user installs your app, the deep link resolution method depends on the button they clicked.
#### 1. Deterministic clipboard-based tracking
This method uses the iOS clipboard to pass the deep link into your app after installation, ensuring reliable and direct link resolution.
Here is how it works in a nutshell:
1. User taps **Get the App** button on the landing page.
2. Dub copies the deep link URL to the clipboard.
3. The user is redirected to the App Store to download your app.
4. After installation, your app reads the clipboard to retrieve the deep link.
5. Your app calls the [`/track/open` endpoint](/api-reference/endpoint/track-open) with the `deepLink` parameter in the request body.
6. Dub returns the destination URL, and your app navigates the user to the appropriate screen (see [deep links quickstart](/concepts/deep-links/quickstart) for more details).
#### 2. Probabilistic IP-based tracking
This method relies on matching the user’s device IP address from the initial click event to the app open event after installation.
1. User taps **Get the App without Copying** button on the landing page.
2. The user is redirected directly to the App Store to download your app.
3. Dub has already tracked the click and stored the IP address at the time of deep link click.
4. After installation, your app calls the [`/track/open` endpoint](/api-reference/endpoint/track-open) with the `dubDomain` parameter in the request body.
5. Dub matches the user using IP-based tracking and returns the destination URL.
6. If a destination URL is returned, your app navigates the user to the appropriate screen (see [deep links quickstart](/concepts/deep-links/quickstart) for more details).
### Track the deep link open
The following logic determines whether to use clipboard-based tracking or IP-based tracking:
* **Clipboard-based tracking**: Used when a deep link is found in the clipboard (e.g., `acme.link`). The app sends the `deepLink` parameter in the request body.
* **IP-based tracking**: Used when no deep link is found in the clipboard. The app sends only the `dubDomain` parameter, allowing Dub to match the user based on their IP address.
This ensures the most reliable tracking method is chosen automatically.
For example, you're creating an ad campaign to drive traffic to a specific product page within your mobile app.
By following the quickstart guide below, you'll be able to make sure that all your short links are set up with deep linking functionality.
## Step 1: Configure your deep link domains on Dub
Before you can create deep links, you need to configure your deep link domains in your Dub workspace. This involves adding a custom domain that will be used for your deep links and configuring your deep link configuration files.
In the domain modal, click on **Show advanced settings**, which will open up the Deep Link Configuration settings fields.
**iOS (apple-app-site-association)**
For iOS apps, upload your Apple App Site Association file to enable iOS deep links:
```json apple-app-site-association
{
"applinks": {
"apps": [],
"details": [
{
"appID": "YOUR_APP_ID",
"paths": []
}
]
}
}
```
**Android (assetlinks.json)**
For Android apps, upload your AssetLinks file to enable Android deep links:
```json assetlinks.json
[
{
"target": {
"namespace": "android_app",
"package_name": "YOUR_PACKAGE_NAME",
"sha256_cert_fingerprints": []
},
"relation": ["delegate_permission/common.handle_all_urls"]
}
]
```
Finally, click **Create link** to create your deep link. This link will act as a Firebase Dynamic Link replacement.
Click on **Create Webhook** to create a new webhook.
Fill in the required fields in the webhook creation form:
1. **Name**: Give your webhook a name that helps you identify it.
2. **URL**: Enter the URL of the endpoint where you want to send the webhook. We recommend using [webhook.site](https://webhook.site/) to test your webhook.
3. **Signing secret**: This is an auto-generated secret key that you can use to verify the authenticity of the webhook in your application. Learn more about [verifying webhook requests](/concepts/webhooks/verify-webhook-requests).
4. **Events**: Select the events you want to listen to. You can select multiple events. Refer to the [Event Types](/concepts/webhooks/event-types) section to see the list of available events.
Finally, click on **Create webhook** to create the webhook.
## Viewing webhook event logs
We also provide you with a webhook event logs page where you can view all the webhook events that have been sent to your webhook endpoint in real-time.
To view the webhook event logs, select the webhook from the [**Webhooks** settings page](https://app.dub.co/webhooks) and click on the **Webhook Logs** tab.
Here, you'll see a list of all the webhook events that have been sent to your webhook endpoint:
You can also select on a specific event, which will open up a sheet with more details about the event:
## Sending test events
You can send test events to your webhook URL to ensure that it's working correctly. To do this:
This will open up a modal where you can select the event you want to send.
You'll see a success message and receive the webhook event in the webhook endpoint you specified.
Make sure to keep this secret safe by only storing it in a secure environment variable (e.g. `DUB_WEBHOOK_SECRET`). Do not commit it to git or add it in any client-side code.
## Verifying a webhook request
To verify, you can use the secret key to generate your own signature for each webhook. If both signatures match then you can be sure that a received event came from Dub.
The steps required are:
1. Get the raw body of the request.
2. Extract the signature from the `Dub-Signature` header.
3. Calculate the HMAC of the raw body using the `SHA-256` hash function and the secret.
4. Compare the calculated `HMAC` with the one sent in the `Dub-Signature` header. If they match, the webhook is verified.
Here's an example of how you can verify a webhook request in different languages:
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Appwrite for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure Appwrite
Next, configure Appwrite to track lead conversion events during the sign up process.
Create a new API key with the `sessions.write` scope enabled and save the API key for later use. You can also copy your project ID and endpoint from the project's Settings page.
Then, in your Next.js app, install the Appwrite Node.js SDK.
```bash
npm i node-appwrite
```
* **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.
# Auth0
Source: https://dub.co/docs/conversions/leads/auth0
Learn how to track lead conversion events with Auth0 and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Auth0 for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure Auth0
Next, configure Auth0 to track lead conversion events.
Here's how it works in a nutshell:
1. In the sign in `afterCallback` function, check if the user is a new sign up.
2. If the user is a new sign up, check if the `dub_id` cookie is present.
3. If the `dub_id` cookie is present, send a lead event to Dub using `dub.track.lead`
4. Delete the `dub_id` cookie.
```typescript app/api/auth/[auth0]/route.js
import { handleAuth, handleCallback, type Session } from "@auth0/nextjs-auth0";
import { cookies } from "next/headers";
import { dub } from "@/lib/dub";
const afterCallback = async (req: Request, session: Session) => {
const userExists = await getUser(session.user.email);
if (!userExists) {
createUser(session.user);
// check if dub_id cookie is present
const clickId = cookies().get("dub_id")?.value;
if (clickId) {
// send lead event to Dub
await dub.track.lead({
clickId,
eventName: "Sign Up",
customerExternalId: session.user.id,
customerName: session.user.name,
customerEmail: session.user.email,
customerAvatar: session.user.image,
});
// delete the dub_id cookie
cookies().set("dub_id", "", {
expires: new Date(0),
});
}
return session;
}
};
export default handleAuth({
callback: handleCallback({ afterCallback }),
});
```
Here's the full list of attributes you can pass when sending a lead event:
| Property | Required | Description |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------- |
| `clickId` | **Yes** | The unique `dub_id` parameter that the lead conversion event is attributed to. |
| `eventName` | **Yes** | The name of the event. Example: "Sign up". |
| `customerExternalId` | **Yes** | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. |
| `customerEmail` | No | The email address of the customer. If not passed, a random email address will be generated. |
| `customerName` | No | The name of the customer. If not passed, a random name will be generated (e.g. "Big Red Caribou"). |
| `customerAvatar` | No | The avatar URL of the customer. If not passed, a random avatar URL will be generated. |
## 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.
# Better Auth
Source: https://dub.co/docs/conversions/leads/better-auth
Learn how to track lead conversion events with Better Auth and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Better Auth for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Installation
* **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.
# Clerk
Source: https://dub.co/docs/conversions/leads/clerk
Learn how to track lead conversion events with Clerk and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Clerk for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure Clerk
Next, configure Clerk to track lead conversion events when a new user signs up. Here's a quick video showing how to do this:
Here's a quick summary of the steps:
* **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.
# Client-side tracking
Source: https://dub.co/docs/conversions/leads/client-side
Learn how to track lead conversion events with Dub using client-side tracking
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
## Quickstart
You can group your hostnames when adding them to the allow list:
* `example.com`: Tracks traffic **only** from `example.com`.
* `*.example.com`: Tracks traffic from **all subdomains** of `example.com`, but **not** from `example.com` itself.
* **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.
# Server-side tracking
Source: https://dub.co/docs/conversions/leads/introduction
Learn how to track lead conversion events with Dub using server-side tracking
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application as lead events on Dub.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure lead tracking
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:
* **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.
# NextAuth.js
Source: https://dub.co/docs/conversions/leads/next-auth
Learn how to track lead conversion events with NextAuth.js and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses NextAuth.js for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure NextAuth.js Options
Then, set up your NextAuth.js configuration options to track lead conversion events using the `dub` TypeScript SDK.
Here's how it works in a nutshell:
1. Use NextAuth's [`signIn` event](https://next-auth.js.org/configuration/events#signin) to detect when there's a new sign up.
2. If the user is a new sign up, check if the `dub_id` cookie is present.
3. If the `dub_id` cookie is present, send a lead event to Dub using `dub.track.lead`
4. Delete the `dub_id` cookie.
Under the hood, Dub records the user as a customer and associates them with the click event that they came from. The user's unique ID is now the source of truth for all future events – hence why we don't need the `dub_id` cookie anymore.
* **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.
# Segment
Source: https://dub.co/docs/conversions/leads/segment
Learn how to track lead conversion events with Segment and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Segment to track conversions.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
## Configure Segment Action
Next, configure [Segment Dub (Actions)](https://app.segment.com/goto-my-workspace/destinations/catalog/actions-dub) to track lead conversion events.
Below the selected action, you’ll see the mapping for that action.
You can customize the trigger and mapping to fit the specific needs of your application.
Finally, click **Next** and then **Save and enable** to add the mapping to the destination.
* **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.
# Supabase
Source: https://dub.co/docs/conversions/leads/supabase
Learn how to track lead conversion events with Supabase and Dub
In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses Supabase for user authentication.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
## Configure Supabase
Next, configure Supabase to track lead conversion events in the auth callback function.
Here's how it works in a nutshell:
1. In the `/api/auth/callback` route, check if:
* the `dub_id` cookie is present.
* the user is a new sign up (created in the last 10 minutes).
2. If the `dub_id` cookie is present and the user is a new sign up, send a lead event to Dub using `dub.track.lead`
3. Delete the `dub_id` cookie.
* **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.
# Quickstart
Source: https://dub.co/docs/conversions/quickstart
Learn how to track conversion analytics with Dub.
In this guide, we'll walk you through the steps to get started with [conversion tracking on Dub](https://dub.co/help/article/dub-conversions):
1. [Enable conversion tracking for your links](#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the `@dub/analytics` client-side SDK](#step-2-install-the-dub-analytics-client-side-sdk)
3. [Install the Dub server-side SDK + track conversion events](#step-3-install-the-dub-server-side-sdk-track-conversion-events)
4. [View your conversions](#step-4-view-your-conversions)
## Step 1: Enable conversion tracking for your links
This option will enable conversion tracking in the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) for all future links.
You can install the `@dub/analytics` script in several different ways:
Our most common lead event is `Sign Up`, which happens when a user signs up for an account. Depending on which authentication framework you're using, here are a few examples of how to send `Sign Up` lead events:
Depending on which payment processor you're using, we offer native integrations for the following:
* **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.
## Example Apps
You can group your hostnames when adding them to the allow list:
* `example.com`: Tracks traffic **only** from `example.com`.
* `*.example.com`: Tracks traffic from **all subdomains** of `example.com`, but **not** from `example.com` itself.
* **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.
# Server-side tracking
Source: https://dub.co/docs/conversions/sales/introduction
Learn how to track sales conversion events with Dub using server-side tracking
In this guide, we will be focusing on tracking sales conversion events with Dub.
## Prerequisites
Before you get started, make sure you follow the [Dub Conversions quickstart guide](/conversions/quickstart) to get Dub Conversions set up for your links:
1. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links)
2. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction)
3. [Install the Dub server-side SDK](/sdks/overview#server-side-sdks)
Then, depending on your authentication provider, follow the relevant guide to set up lead conversion tracking:
* **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.
## Currency conversion support
For simplicity, Dub records all sales in the default currency of your Dub workspace. This means that if you pass a different currency, it will be automatically converted to USD for reporting consistency – using the latest foreign exchange rates.
```typescript TypScript
await dub.track.sale({
customerExternalId: "cus_RBfbD57HDzPKpduI8elr5qHA",
amount: 15480, // this will be converted from PLN to USD
currency: "pln",
paymentProcessor: "stripe",
eventName: "Purchase",
});
```
Below the selected action, you’ll see the mapping for that action.
You can customize the trigger and mapping to fit the specific needs of your application.
Finally, click **Next** and then **Save and enable** to add the mapping to the destination.
* **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.
# Shopify
Source: https://dub.co/docs/conversions/sales/shopify
Learn how to track sale conversion events with Shopify and Dub
In this guide, we will be focusing on tracking sale events from Shopify by leveraging Dub's Shopify integration.
## Step 1: Enable conversion tracking for your links
First, you'll need to enable conversion tracking for your Dub links to be able to start tracking conversions.
There are a few ways to do this:
1. [On a workspace-level](/conversions/quickstart#option-1-on-a-workspace-level)
2. [On a link-level](/conversions/quickstart#option-2-on-a-link-level)
3. [Via the API](/conversions/quickstart#option-3-via-the-api)
## Step 2: Install the Dub Shopify app
With the Shopify app, you can also create [conversion-enabled links](/conversions//quickstart#step-1%3A-enable-conversion-tracking-for-your-links) directly from your Shopify store:
If you want a more powerful link builder, you can also use the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) to create conversion-enabled links.
* **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.
## Currency conversion support
For simplicity, Dub records all sales in the native currency of the Shopify store. For example, if you're using USD for your Shopify store, Dub will record all sales in USD – even if your customers are paying in a different currency.
```json orders/paid
// Shopify orders/paid event payload
// @see: https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-orders/paid
{
...
"current_subtotal_price_set": {
"shop_money": {
"amount": "398.00", // this is the amount that Dub will record
"currency_code": "USD" // this is the currency of your Shopify store
},
"presentment_money": {
"amount": "572.25",
"currency_code": "CAD"
}
},
...
}
```
# Stripe
Source: https://dub.co/docs/conversions/sales/stripe
Learn how to track sale conversion events with Stripe and Dub
In this guide, we will be focusing on tracking sale events with Stripe as the payment processor by leveraging Dub's Stripe integration.
## Installing the Dub Stripe integration
Dub comes with a powerful Stripe integration that automatically listens to payment events on Stripe and track them as sales on Dub.
Here's how you can install the Dub Stripe integration:
This will redirect you to the [Dub OAuth flow](/integrations/quickstart), where you can select the Dub workspace you want to connect to your Stripe account.
Once you click on **Authorize**, you will be redirected back to the Dub app settings page on Stripe, where you should see that the integration is now installed.
Finally, when the user completes the checkout flow, Dub will automatically [track the sale event](/api-reference/endpoint/track-sale) and [update the customer's `customerExternalId`](/api-reference/endpoint/update-a-customer) with their Stripe customer ID for future reference.
Alternatively, if you have a marketing site that you're redirecting your users to first, you can do this instead:
1. [Install the @dub/analytics client-side SDK](/sdks/client-side/introduction), which automatically detects the `dub_id` in the URL and stores it as a first-party cookie on your site.
2. Then, retrieve and append the `dub_id` value as the `client_reference_id` parameter to the payment links on your pricing page / CTA button (prefixed with `dub_id_`).
```
https://buy.stripe.com/xxxxxx?client_reference_id=dub_id_xxxxxxxxxxxxxx
```
* **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.
## Example Apps
## Introduction
Dub's codebase is set up in a monorepo (via [Turborepo](https://turbo.build/repo)) and is fully [open-source on GitHub](https://github.com/dubinc/dub).
Here's the monorepo structure:
```
apps
├── web
packages
├── cli
├── email
├── embeds
├── prisma
├── stripe-app
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils
```
The `apps` directory contains the code for:
* `web`: The entirety of Dub's application ([app.dub.co](https://app.dub.co)) + our link redirect infrastructure.
The `packages` directory contains the code for:
* `cli`: A CLI for easily shortening URLs with the Dub API.
* `email`: Dub's email application with function to send emails and templates.
* `embeds`: A package used embed Dub's referral dashboard.
* `prisma`: Prisma Configuration for Dub's web-app.
* `stripe-app`: The Stripe app for dub conversions.
* `tailwind-config`: The Tailwind CSS configuration for Dub's web app.
* `tinybird`: Dub's Tinybird configuration.
* `tsconfig`: The TypeScript configuration for Dub's web app.
* `ui`: Dub's UI component library.
* `utils`: A collection of utility functions and constants used across Dub's codebase.
## How `app.dub.co` works
Dub's web app is built with [Next.js](https://nextjs.org) and [TailwindCSS](https://tailwindcss.com).
It also utilizes code from the `packages` directory, specifically the `@dub/ui` and `@dub/utils` packages.
All of the code for the web app is located in here: [`main`/apps/web/app/app.dub.co](https://github.com/dubinc/dub/tree/main/apps/web/app/app.dub.co). This is using the Next.js [route group pattern](https://nextjs.org/docs/app/building-your-application/routing/route-groups).
There's also the API server, which is located in here: [`main`/apps/web/app/api](https://github.com/dubinc/dub/tree/main/apps/web/app/api)
When you run `pnpm dev` to start the development server, the app will be available at [http://localhost:8888](http://localhost:8888). The reason we use `localhost:8888` and not `app.localhost:8888` is because Google OAuth doesn't allow you to use localhost subdomains.
## How link redirects work on Dub
Link redirects on Dub are powered by [Next.js Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware).
To handle high traffic, we use Redis to cache every link's metadata when it's first created. This allows us to serve redirects without hitting our MySQL database.
Here's the code that powers link redirects: [`main`/apps/web/lib/middleware/link.ts](https://github.com/dubinc/dub/blob/main/apps/web/lib/middleware/link.ts)
## Running Dub locally
To run Dub locally, you'll need to set up the following:
* A [Tinybird](https://www.tinybird.co/) account
* An [Upstash](https://upstash.com/) account
* A [PlanetScale](https://planetscale.com/)-compatible MySQL database
Watch this video from our friends at Tinybird to learn how to set up Dub locally:
## Step 1: Local setup
First, you'll need to clone the Dub repo and install the dependencies.
Navigate to the [QStash tab](https://console.upstash.com/qstash) and copy the `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY` from the **Request Builder** section into your `.env` file.
### Using server-side SDKs
If you're using our [server-side SDKs](/sdks/overview), you can generate an embed token using the `dub.embedTokens.referrals` method.
On top of that, it also:
* lets you [track clicks on the client-side](/sdks/client-side/features/client-side-click-tracking) using query parameters (e.g. `?via=john`)
* [automatically fetch the partner and discount data](/sdks/client-side/features/client-side-click-tracking#automatically-fetching-partner-and-discount-data) for a given link – which is helpful for displaying [dual-sided incentives](https://dub.co/help/article/dual-sided-incentives)
You can install the `@dub/analytics` script in several different ways:
Our most common lead event is `Sign Up`, which happens when a user signs up for an account. Depending on which authentication framework you're using, here are a few examples of how to send `Sign Up` lead events:
Depending on which payment processor you're using, we offer native integrations for the following:
# Client-side click tracking
Source: https://dub.co/docs/sdks/client-side/features/click-tracking
Track clicks on the client-side using query parameters
With the [`@dub/analytics` script](/sdks/client-side/introduction), you can track clicks on the client-side using query parameters (e.g. `?via=john`, `?ref=jane`).
A few use cases include:
* You're using [Dub Partners](https://dub.co/help/article/dub-partners) with [dual-sided incentives](https://dub.co/help/article/dual-sided-incentives) and want to display a banner that says: *"John referred you to Acme and gave you 25% off"*
* You are migrating from an existing affiliate management platform (e.g. [Rewardful](https://dub.co/help/article/migrating-from-rewardful)) that uses query parameters to track conversions.
* You are running an ad on a platform like Google/Reddit that requires you to use your main site domain for the URL (no short links allowed) – so instead of using a short link, you can use a query parameter to track clicks.
* You have dynamically generated referral pages (e.g. [Tesla](https://www.tesla.com/referral/peeroke520149)) and want to track clicks [using a `trackClick()` function](#manually-tracking-clicks-with-the-trackclick-function) inside your application code.
## Quickstart
Here's how you can enable client-side click-tracking with the `@dub/analytics` script:
You can group your hostnames when adding them to the allow list:
* `example.com`: Tracks traffic **only** from `example.com`.
* `*.example.com`: Tracks traffic from **all subdomains** of `example.com`, but **not** from `example.com` itself.
{partner.name} referred you to Acme and gave you {discount.amount}{" "} {discount.type} off
${DubAnalytics.partner.name} referred you to Acme and gave you ${DubAnalytics.discount.amount} ${DubAnalytics.discount.type} off
## Manually tracking clicks with the `trackClick()` function
This is helpful for tracking clicks on:
* Dynamically generated referral pages (e.g. [Tesla](https://www.tesla.com/referral/peeroke520149))
* Dynamic user-generated content/webpages:
* Dub's public analytics dashboards (e.g. [app.dub.co/share/:slug](https://app.dub.co/share/dash_6NSA6vNm017MZwfzt8SubNSZ))
* Cal.com's booking pages (e.g. [cal.com/steven](https://cal.com/steven))
* Tella's video pages (e.g. [tella.tv/video/:slug](https://www.tella.tv/video/cluvcfcfi00tw0fjrgizr4pw2))
The `trackClick()` function allows you to manually trigger click events from your application code. This is useful when you want to track clicks that happen programmatically.
The `trackClick()` function accepts an object with the following parameters:
Then, when a conversion event occurs (e.g. a user signs up for an account), you can check for the `dub_id` cookie and attribute the conversion to the original click by [tracking a lead event](/conversions/leads/introduction).
Finally, when the user completes a purchase (e.g. subscribing to a plan, purchasing a product, etc.), you can [track a sale event](/conversions/sales/introduction). Under the hood, Dub will automatically attribute the sale to the original link click.
## Quickstart
You can group your hostnames when adding them to the allow list:
* `example.com`: Tracks traffic **only** from `example.com`.
* `*.example.com`: Tracks traffic from **all subdomains** of `example.com`, but **not** from `example.com` itself.
If you're using [Dub Partners](/partners/quickstart) for affiliate management, you will also need to set up the `data-domains` property to enable [client-side click-tracking](/sdks/client-side/features/client-side-click-tracking).
```js
```
Then, make sure to activate the `@dub/analytics` script by following these steps:
1. Navigate to your Shopify admin panel.
2. Go to **Online Store** > **Themes**.
3. Click on **Customize** for your current theme.
4. In the theme editor, select the **App embeds** tab.
5. Locate the **Analytics Script** for the Dub Conversions app and toggle it to activate.
If you're using Dub Partners, this script also lets you [track clicks on the client-side](/sdks/client-side/features/client-side-click-tracking) using query parameters (e.g. `?via=john`). This gives you the flexibility to track clicks directly on your website or app, without needing to rely on link redirects.
## Installation guides
You can install the `@dub/analytics` script in several different ways:
### Using server-side SDKs
If you're using our [server-side SDKs](/sdks/overview), you can generate an embed token using the `dub.embedTokens.referrals` method.
You can self-host Dub on your own servers and cloud infrastructure for greater control over your data and design. This guide will walk you through the entire process of setting up Dub on your own servers.
## Prerequisites
Before you begin, make sure you have the following:
* A [GitHub](https://github.com/) account
* A [Tinybird](https://www.tinybird.co/) account
* An [Upstash](https://upstash.com/) account
* A [PlanetScale](https://planetscale.com/) account
* A [Vercel](https://vercel.com/) account
* Either a [Cloudflare](https://www.cloudflare.com/) or [AWS](https://aws.com) account
You'll also need a custom domain that you will be using for your Dub instance, with an optional custom short domain for your links.
In this guide, we'll use `acme.com` as a placeholder for your custom domain, and `ac.me` as a placeholder for your custom short domain.
## Step 1: Local setup
First, you'll need to clone the Dub repo and install the dependencies.
Navigate to the [QStash tab](https://console.upstash.com/qstash) and copy the `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY` from the **Request Builder** section into your `.env` file.
In your bucket settings, copy the **S3 API** value – you'll need it in Step 3.
Then, click **Create API Token**.
Make sure to name your API token something relevant to the service that will be using the token.
Give it "Object Read & Write" permissions, and we recommend only applying ito to a single bucket.
You can leave the remaining settings (TTL, Client IP Address Filtering) as is, and click **Create API Token**.
After you create you token, copy the `Access Key ID` and `Secret Access Key` values – you'll need them in the next step.
In the **Environment Variables** section, add all of the environment variables from your `.env` file by copying all of them and pasting it into the first input field. A few notes:
* Remove the `PROJECT_ID_VERCEL` environment variable for now since we will only get the project ID after deploying the project.
* Replace the `NEXTAUTH_URL` environment variable with the app domain that you will be using (e.g. `https://app.acme.com`).
Click on **Deploy** to deploy your project.
