diff --git a/conversions/leads/client-side.mdx b/conversions/leads/client-side.mdx new file mode 100644 index 0000000..4b660df --- /dev/null +++ b/conversions/leads/client-side.mdx @@ -0,0 +1,36 @@ +--- +title: Client-side tracking +og:title: Client-side lead tracking with Dub +description: Learn how to track lead conversion events with Dub using client-side tracking +--- + +import LeadsIntro from "/snippets/leads-intro.mdx"; +import ClientSideLeadTracking from "/snippets/client-side-lead-tracking.mdx"; +import ClientSideTrackingInstall from "/snippets/client-side-tracking-install.mdx"; +import LeadsOutro from "/snippets/leads-outro.mdx"; + + + +## 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) + + + +## Client-side lead tracking + + + + + Client-side conversion tracking comes with some limitations: - **Ad + blockers**: Users with ad blockers may prevent tracking scripts from loading - + **JavaScript disabled**: Events won't be tracked if users have JavaScript + disabled - **Network issues**: Failed network requests won't retry + automatically - **Privacy concerns**: Some users may block client-side + tracking for privacy reasons For more accurate conversion tracking, consider + using [server-side conversion tracking](/api-reference/endpoint/track-lead). + + + diff --git a/conversions/leads/introduction.mdx b/conversions/leads/introduction.mdx index 8ef30d9..2382fee 100644 --- a/conversions/leads/introduction.mdx +++ b/conversions/leads/introduction.mdx @@ -1,7 +1,8 @@ --- -title: "Introduction" -og:title: "How to track lead conversion events with Dub" -description: "Learn how to track lead conversion events with Dub" +title: Server-side tracking +sidebarTitle: Server-side tracking (recommended) +og:title: Server-side lead tracking with Dub +description: Learn how to track lead conversion events with Dub using server-side tracking --- import LeadsIntro from "/snippets/leads-intro.mdx"; diff --git a/conversions/quickstart.mdx b/conversions/quickstart.mdx index c41b776..eb79e92 100644 --- a/conversions/quickstart.mdx +++ b/conversions/quickstart.mdx @@ -8,13 +8,14 @@ import DubClientInstall from "/snippets/dub-client-install.mdx"; import DubClientInstallVerify from "/snippets/dub-client-install-verify.mdx"; import InstallServerSdksTrackConversions from "/snippets/install-server-sdks-track-conversions.mdx"; import ViewConversions from "/snippets/view-conversions.mdx"; +import DubConversionTrackingDemoApps from "/snippets/dub-conversion-tracking-demo-apps.mdx"; Conversion tracking require a [Business plan](https://dub.co/pricing) subscription or higher. -[Dub Conversions](https://dub.co/help/article/dub-conversions) is a powerful tool that lets you turn any [short link you create on Dub](https://dub.co/help/article/how-to-create-link) into a full attribution engine. This allows you to understand how well your links are translating to actual users and revenue dollars. +Dub's powerful [attribution platform](https://dub.co/analytics) lets you understand how well your links are translating to actual users and revenue dollars. -In this guide, we'll walk you through the steps to get started with Dub Conversions: +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) @@ -32,6 +33,11 @@ In this guide, we'll walk you through the steps to get started with Dub Conversi ## Step 1: Enable conversion tracking for your links + + If you're using [Dub Partners](/partners/quickstart), you can skip this step + since partner links will have conversion tracking enabled by default. + + 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: @@ -139,13 +145,4 @@ Once you've enabled conversion tracking for your links, all your tracked convers ## Example Apps - - - See the full example on GitHub. - - + diff --git a/conversions/sales/client-side.mdx b/conversions/sales/client-side.mdx new file mode 100644 index 0000000..68d692b --- /dev/null +++ b/conversions/sales/client-side.mdx @@ -0,0 +1,42 @@ +--- +title: Client-side tracking +og:title: Client-side sale tracking with Dub +description: Learn how to track sales conversion events with Dub on the client-side +--- + +import ClientSideTrackingInstall from "/snippets/client-side-tracking-install.mdx"; +import ViewConversions from "/snippets/view-conversions.mdx"; +import ClientSideSaleTracking from "/snippets/client-side-sale-tracking.mdx"; + +When it comes to [conversion tracking](/conversions/quickstart), a `sale` event happens when a user purchases your product or service. Examples include: + +- Subscribing to a paid plan +- Usage expansion (upgrading from one plan to another) + +## 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) + + + +## Client-side sale tracking + + + + + Client-side conversion tracking comes with some limitations: - **Ad + blockers**: Users with ad blockers may prevent tracking scripts from loading - + **JavaScript disabled**: Events won't be tracked if users have JavaScript + disabled - **Network issues**: Failed network requests won't retry + automatically - **Privacy concerns**: Some users may block client-side + tracking for privacy reasons For more accurate conversion tracking, consider + using [server-side conversion tracking](/api-reference/endpoint/track-sale). + + +## View conversion results + +And that's it – you're all set! You can now sit back, relax, and watch your conversion revenue grow. We provide 3 different views to help you understand your conversions: + + diff --git a/conversions/sales/introduction.mdx b/conversions/sales/introduction.mdx index c01a790..2057581 100644 --- a/conversions/sales/introduction.mdx +++ b/conversions/sales/introduction.mdx @@ -1,7 +1,8 @@ --- -title: "Introduction" -og:title: "How to track sale conversion events with Dub" -description: "Learn how to track sales conversion events with Dub" +title: Server-side tracking +sidebarTitle: Server-side tracking (recommended) +og:title: Server-side sale tracking with Dub +description: Learn how to track sales conversion events with Dub using server-side tracking --- import SalesPrerequisites from "/snippets/sales-prerequisites.mdx"; diff --git a/docs.json b/docs.json index 28f020d..dcd00c7 100644 --- a/docs.json +++ b/docs.json @@ -61,24 +61,29 @@ "group": "Tracking lead events", "pages": [ "conversions/leads/introduction", - "conversions/leads/clerk", - "conversions/leads/better-auth", - "conversions/leads/next-auth", - "conversions/leads/supabase", - "conversions/leads/auth0", - "conversions/leads/appwrite", - "conversions/leads/segment", - "conversions/leads/google-tag-manager" + "conversions/leads/client-side", + { + "group": "Auth providers", + "pages": [ + "conversions/leads/clerk", + "conversions/leads/better-auth", + "conversions/leads/next-auth", + "conversions/leads/supabase", + "conversions/leads/auth0", + "conversions/leads/appwrite" + ] + }, + "conversions/leads/segment" ] }, { "group": "Tracking sale events", "pages": [ "conversions/sales/introduction", + "conversions/sales/client-side", "conversions/sales/stripe", "conversions/sales/shopify", - "conversions/sales/segment", - "conversions/sales/google-tag-manager" + "conversions/sales/segment" ] } ] @@ -153,8 +158,8 @@ { "group": "Features", "pages": [ + "sdks/client-side/features/click-tracking", "sdks/client-side/features/conversion-tracking", - "sdks/client-side/features/client-side-click-tracking", "sdks/client-side/features/cross-domain-tracking", "sdks/client-side/features/reverse-proxy-support" ] @@ -227,6 +232,16 @@ "api-reference/endpoint/update-a-commission" ] }, + { + "group": "Domains API", + "pages": [ + "api-reference/endpoint/create-a-domain", + "api-reference/endpoint/update-a-domain", + "api-reference/endpoint/delete-a-domain", + "api-reference/endpoint/register-a-domain", + "api-reference/endpoint/check-a-domain-availability" + ] + }, { "group": "Folders API", "pages": [ @@ -243,16 +258,6 @@ "api-reference/endpoint/retrieve-a-list-of-tags", "api-reference/endpoint/update-a-tag" ] - }, - { - "group": "Domains API", - "pages": [ - "api-reference/endpoint/create-a-domain", - "api-reference/endpoint/update-a-domain", - "api-reference/endpoint/delete-a-domain", - "api-reference/endpoint/register-a-domain", - "api-reference/endpoint/check-a-domain-availability" - ] } ] } @@ -322,6 +327,10 @@ "source": "/sdks/js-client/overview", "destination": "/sdks/client-side/installation-guides/react" }, + { + "source": "/sdks/client-side/features/client-side-click-tracking", + "destination": "/sdks/client-side/features/click-tracking" + }, { "source": "/self-hosting/guide", "destination": "/self-hosting" diff --git a/examples.mdx b/examples.mdx index d17649f..848614c 100644 --- a/examples.mdx +++ b/examples.mdx @@ -3,6 +3,8 @@ title: "What can you build with Dub?" description: "Explore ideas and examples of what you can build with the Dub API" --- +import DubConversionTrackingDemoApps from "/snippets/dub-conversion-tracking-demo-apps.mdx"; + ## Dub Links With Dub's [API](/api-reference/introduction), you can integrate Dub's link infrastructure into your application. This includes use cases like: @@ -57,14 +59,4 @@ You can also combine Dub Conversions with [Webhooks](/concepts/webhooks/introduc - give both the referrer and referee 1 month free of your product - send a swag link when a user reaches 5 referrals - - - Example app that shows how to use Dub Conversions with the Dub Typescript - SDK - - + diff --git a/images/conversions/allowed-hostnames.png b/images/conversions/allowed-hostnames.png index 93471f5..a870a6d 100644 Binary files a/images/conversions/allowed-hostnames.png and b/images/conversions/allowed-hostnames.png differ diff --git a/images/conversions/publishable-key.png b/images/conversions/publishable-key.png new file mode 100644 index 0000000..aba64ba Binary files /dev/null and b/images/conversions/publishable-key.png differ diff --git a/sdks/client-side/features/client-side-click-tracking.mdx b/sdks/client-side/features/click-tracking.mdx similarity index 99% rename from sdks/client-side/features/client-side-click-tracking.mdx rename to sdks/client-side/features/click-tracking.mdx index 7711918..75778f3 100644 --- a/sdks/client-side/features/client-side-click-tracking.mdx +++ b/sdks/client-side/features/click-tracking.mdx @@ -1,5 +1,5 @@ --- -title: Client-side click-tracking +title: Client-side click tracking description: Track clicks on the client-side using query parameters --- diff --git a/sdks/client-side/features/conversion-tracking.mdx b/sdks/client-side/features/conversion-tracking.mdx index a06ce3d..f03cc4f 100644 --- a/sdks/client-side/features/conversion-tracking.mdx +++ b/sdks/client-side/features/conversion-tracking.mdx @@ -1,8 +1,13 @@ --- -title: Conversion-tracking -description: Learn how to use the @dub/analytics script to track conversion events +title: Client-side conversion tracking +sidebarTitle: Conversion tracking +description: Learn how to use the @dub/analytics script to track conversion events on the client-side --- +import ClientSideTrackingInstall from "/snippets/client-side-tracking-install.mdx"; +import ClientSideLeadTracking from "/snippets/client-side-lead-tracking.mdx"; +import ClientSideSaleTracking from "/snippets/client-side-sale-tracking.mdx"; + `@dub/analytics` is a client-side script for [tracking conversion events](/conversions/quickstart) with Dub. By default, the script handles the detection of the `dub_id` query parameter and storing it as a first-party cookie: @@ -34,3 +39,13 @@ Finally, when the user completes a purchase (e.g. subscribing to a plan, purchas alt="A diagram showing how sale events are tracked in the conversion funnel" /> + + + +## Client-side lead tracking + + + +## Client-side sale tracking + + diff --git a/snippets/client-side-lead-tracking.mdx b/snippets/client-side-lead-tracking.mdx new file mode 100644 index 0000000..0b3eb06 --- /dev/null +++ b/snippets/client-side-lead-tracking.mdx @@ -0,0 +1,100 @@ +import LeadsAttributes from "/snippets/leads-attributes.mdx"; + +Once the analytics script is installed, you can start tracking lead events in your application on the client-side. + +Here are the quickstart examples for tracking lead events: + + + +```typescript React +import { useAnalytics } from "@dub/analytics/react"; +import { useState } from "react"; + +export function SignUpForm() { + const { trackLead } = useAnalytics(); + const [name, setName] = useState(""); + const [email, setEmail] = useState(""); + const handleSubmit = (e: React.FormEvent) => { + e.preventDefault(); + + // Track the lead event + trackLead({ + eventName: "Sign Up", + customerExternalId: email, + customerName: name, + customerEmail: email, + }); + }; + + return ( +
+ setName(e.target.value)} + required + /> + setEmail(e.target.value)} + required + /> + +
+ ); +} +``` + +```html Other + + + + + + Sign Up + + +
+ + + +
+ + + + +``` + + + + + +**When to track leads** + +You should track lead events after successful user actions such as: + +- User registration or account creation +- Newsletter subscription +- Contact form submission +- Demo request or trial signup +- Download of gated content + +Ensure the event is triggered **only after the backend confirms the action was completed successfully**. This guarantees accurate lead data and prevents false or incomplete entries. diff --git a/snippets/client-side-sale-tracking.mdx b/snippets/client-side-sale-tracking.mdx new file mode 100644 index 0000000..fb02ea3 --- /dev/null +++ b/snippets/client-side-sale-tracking.mdx @@ -0,0 +1,79 @@ +import SaleAttributes from "/snippets/sale-attributes.mdx"; + +Once the analytics script is installed, you can start tracking sale events in your application on the client-side. + + + +```typescript React +import { useAnalytics } from "@dub/analytics/react"; +import { useState } from "react"; + +export function CheckoutForm() { + const { trackSale } = useAnalytics(); + // … +} + const handleSubmit = (e: React.FormEvent) => { + e.preventDefault(); + + // Track the sale event + trackSale({ + eventName: "Purchase", + customerExternalId: "cus_RBfbD57H", + amount: 5000, // $50.00 + invoiceId: "in_1MtHbELkdIwH", + }); + }; + + return ( +
+ ... +
+ ); +} +``` + +```html Other + + + + + + Checkout + + +
+ ... + +
+ + + + +``` + + + + + +**When to track sale** + +Track sale events only after a user successfully completes a purchase or payment-related action, such as: + + - Completing a checkout or order + - Subscription payment + - Invoice payment + - Any paid trial or demo conversion + +Ensure the event is triggered **only after the backend confirms the payment was successful**. This guarantees accurate sale data and prevents false or incomplete entries. diff --git a/snippets/client-side-tracking-install.mdx b/snippets/client-side-tracking-install.mdx new file mode 100644 index 0000000..b63863b --- /dev/null +++ b/snippets/client-side-tracking-install.mdx @@ -0,0 +1,94 @@ +## Quickstart + + + + + +Before you can track conversions on the client-side, you need to generate a publishable key from your Dub workspace. + +To do that, navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and generate a new publishable key under the **Publishable Key** section. + + + Enabling conversion tracking for a workspace + + + + + + +Then, you'll need to allowlist your site's domain to allow the client-side conversion events to be ingested by Dub. + +To do that, navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and add your site's domain to the **Allowed Hostnames** list. + +This provides an additional layer of security by ensuring only authorized domains can track conversions using your publishable key. + + + Enabling conversion tracking for a workspace + + +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. + + + When testing things out locally, you can add `localhost` to the **Allowed + Hostnames** list temporarily. This will allow local events to be ingested by + Dub. Don't forget to remove it once you're ready to go live! + + + + + + +Next, install the Dub analytics script in your application. + +import DubClientInstall from "/snippets/dub-client-install.mdx"; + + + +You must configure the **publishable key** you generated in step 1 when installing the analytics script. Without this key, client-side conversion tracking will not work. + + + +```typescript React +import { Analytics as DubAnalytics } from '@dub/analytics/react'; + +export default function RootLayout({ + children, +}) { + return ( + + {children} + + + ); +} +``` + +```html Other + +``` + + + + + + diff --git a/snippets/dub-client-install.mdx b/snippets/dub-client-install.mdx index 7a9f2d8..06b3be2 100644 --- a/snippets/dub-client-install.mdx +++ b/snippets/dub-client-install.mdx @@ -4,21 +4,21 @@ You can install the `@dub/analytics` script in several different ways: Add Dub Analytics to your React app Add Dub Analytics to your website Add Dub Analytics via GTM @@ -38,28 +38,28 @@ You can install the `@dub/analytics` script in several different ways: } - href="https://dub.co/docs/sdks/client-side/installation-guides/framer" + href="/sdks/client-side/installation-guides/framer" > Add Dub Analytics to your Framer site Add Dub Analytics to your Shopify store Add Dub Analytics to your WP site Add Dub Analytics to your Webflow site diff --git a/snippets/dub-conversion-tracking-demo-apps.mdx b/snippets/dub-conversion-tracking-demo-apps.mdx new file mode 100644 index 0000000..8cc7d82 --- /dev/null +++ b/snippets/dub-conversion-tracking-demo-apps.mdx @@ -0,0 +1,34 @@ + + + Example app that shows how to track conversion events with Dub. + + + Example app that shows how to track conversion events with Segment and Dub. + + + Example app that shows how to track Clerk signup events with Dub. + + + Example app that shows how to track Cal.com booking events with Dub. + + diff --git a/snippets/install-server-sdks-track-conversions.mdx b/snippets/install-server-sdks-track-conversions.mdx index c1ad1b6..9ee7b9b 100644 --- a/snippets/install-server-sdks-track-conversions.mdx +++ b/snippets/install-server-sdks-track-conversions.mdx @@ -6,27 +6,26 @@ import AuthProviders from "/snippets/auth-providers.mdx"; guide](https://dub.co/docs/conversions/sales/shopify) for more information. -Dub uses server-side event tracking to track conversions, which is more reliable than client-side tracking. Depending on which framework you're using, you can use our [native SDKs](/sdks/overview): +The recommended way to track conversions on Dub is using [server-side tracking](/conversions/leads/introduction), which is more reliable than [client-side tracking](/conversions/leads/client-side). + +Depending on which framework you're using, you can use our [native SDKs](/sdks/overview): TypeScript library for the Dub API - + Go library for the Dub API - + Python library for the Dub API - + Ruby library for the Dub API + + PHP library for the Dub API + If you're using a framework that isn't listed, you can use the Dub REST API to track events on the server-side: