From e6b8a817b5e615b401060d804f01ac8b99a35d18 Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Wed, 17 Sep 2025 15:06:56 -0400 Subject: [PATCH 01/13] Moves api keys to /api-keys --- api-reference/{tokens.mdx => api-keys.mdx} | 0 api-reference/introduction.mdx | 4 ++-- conversions/leads/google-tag-manager.mdx | 2 +- conversions/sales/google-tag-manager.mdx | 2 +- data-model.mdx | 2 +- docs.json | 2 +- integrations/quickstart.mdx | 2 +- sdks/client-side/introduction.mdx | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) rename api-reference/{tokens.mdx => api-keys.mdx} (100%) diff --git a/api-reference/tokens.mdx b/api-reference/api-keys.mdx similarity index 100% rename from api-reference/tokens.mdx rename to api-reference/api-keys.mdx diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index e81450aa..44a79c2f 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -16,7 +16,7 @@ https://api.dub.co ## Authentication -Authentication to Dub's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word `Bearer` followed by your API key in your requests like so: +Authentication to Dub's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word `Bearer` followed by your [API key](/api-reference/api-keys) in your requests like so: ```bash Terminal Authorization: Bearer dub_xxxxxx @@ -87,7 +87,7 @@ $links = $client->links->list(); -Learn more about [how to get your API key](/api-reference/tokens). +Learn more about [how to get your API key](/api-reference/api-keys). ## Native SDKs diff --git a/conversions/leads/google-tag-manager.mdx b/conversions/leads/google-tag-manager.mdx index 78aa1363..8aa0af4b 100644 --- a/conversions/leads/google-tag-manager.mdx +++ b/conversions/leads/google-tag-manager.mdx @@ -181,7 +181,7 @@ This will open up the tag configuration page. Under **Tag Configuration**, selec Make sure your tag configuration is set to the following: -- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`) +- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/api-keys) (starts with `dub_`) - **Event**: Select "Track lead" from the dropdown - **Click ID**: `clickId` from the Dub Server Client event data - **Customer External ID**: `customerExternalId` from the event data diff --git a/conversions/sales/google-tag-manager.mdx b/conversions/sales/google-tag-manager.mdx index 8578466c..7ba931ea 100644 --- a/conversions/sales/google-tag-manager.mdx +++ b/conversions/sales/google-tag-manager.mdx @@ -216,7 +216,7 @@ This will open up the tag configuration page. Under **Tag Configuration**, selec Make sure your tag configuration is set to the following: -- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`) +- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/api-keys) (starts with `dub_`) - **Event**: Select "Track sale" from the dropdown - **Customer External ID**: `customerExternalId` from the event data - **Amount**: `amount` from the event data (in cents) diff --git a/data-model.mdx b/data-model.mdx index dbb76ef2..cd7a148f 100644 --- a/data-model.mdx +++ b/data-model.mdx @@ -14,7 +14,7 @@ Within Dub, all data belongs to a [**Workspace**](#workspace). Within a workspac - [Tags](#tags) - [Domains](#domains) -When interacting with Dub's API, you'll also need to create a [workspace API key](/api-reference/tokens) to authenticate your requests. +When interacting with Dub's API, you'll also need to create a [workspace API key](/api-reference/api-keys) to authenticate your requests. ## Links diff --git a/docs.json b/docs.json index dcd00c79..d10f879a 100644 --- a/docs.json +++ b/docs.json @@ -121,7 +121,7 @@ "group": "Overview", "pages": [ "api-reference/introduction", - "api-reference/tokens", + "api-reference/api-keys", "api-reference/rate-limits" ] }, diff --git a/integrations/quickstart.mdx b/integrations/quickstart.mdx index ae0614d1..f8d61228 100644 --- a/integrations/quickstart.mdx +++ b/integrations/quickstart.mdx @@ -237,4 +237,4 @@ Dub supports the following scopes for OAuth 2.0: Dub also supports API key authentication; however, it is **not recommended** for building integrations. It should only be used for internal integrations or personal projects that do not require user consent. -Learn more about [API Keys](/api-reference/tokens). +Learn more about [API Keys](/api-reference/api-keys). diff --git a/sdks/client-side/introduction.mdx b/sdks/client-side/introduction.mdx index 4db48e1e..9ec8d9f3 100644 --- a/sdks/client-side/introduction.mdx +++ b/sdks/client-side/introduction.mdx @@ -41,7 +41,7 @@ You can pass the following props to the `@dub/analytics` script to customize its ## Open-source examples -Here are some open-source code examples that you can referece: +Here are some open-source code examples that you can reference: Date: Wed, 17 Sep 2025 15:07:16 -0400 Subject: [PATCH 02/13] Fixes conversion quickstart links --- conversions/quickstart.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/conversions/quickstart.mdx b/conversions/quickstart.mdx index 29f03e0c..817796b2 100644 --- a/conversions/quickstart.mdx +++ b/conversions/quickstart.mdx @@ -28,9 +28,9 @@ Dub's powerful [attribution platform](https://dub.co/analytics) lets you underst 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) +2. [Install the `@dub/analytics` client-side SDK](#step-2%3A-install-the-%40dub%2Fanalytics-client-side-sdk) +3. [Install the Dub server-side SDK + track conversion events](#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) +4. [View your conversions](#step-4%3A-view-your-conversions) ## Step 1: Enable conversion tracking for your links From 2b820d3fb62fcd5e01b8dabb3df921e382512575 Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Wed, 17 Sep 2025 17:02:33 -0400 Subject: [PATCH 03/13] Adds dub ios sdk docs --- api-reference/endpoint/track-client-lead.mdx | 10 + api-reference/endpoint/track-client-sale.mdx | 11 + api-reference/publishable-keys.mdx | 32 ++ concepts/deep-links/attribution.mdx | 203 +++++++++++- concepts/deep-links/deferred-deep-linking.mdx | 10 +- concepts/deep-links/quickstart.mdx | 102 +++++- conversions/leads/client-side.mdx | 2 +- conversions/quickstart.mdx | 2 +- conversions/sales/client-side.mdx | 2 +- conversions/sales/google-tag-manager.mdx | 2 +- conversions/sales/shopify.mdx | 2 +- docs.json | 40 ++- .../features/conversion-tracking.mdx | 51 +++ .../features/open-tracking.mdx | 296 ++++++++++++++++++ .../installation-guides/swift.mdx | 37 +++ sdks/client-side-mobile/introduction.mdx | 40 +++ sdks/overview.mdx | 8 + snippets/client-side-tracking-install.mdx | 46 +-- snippets/dub-client-mobile-install.mdx | 211 +++++++++++++ .../dub-client-mobile-installation-guides.mdx | 10 + snippets/leads-intro.mdx | 2 +- snippets/steps/allowlist-domains.mdx | 27 ++ snippets/steps/generate-publishable-key.mdx | 14 + snippets/steps/initialize-ios-sdk.mdx | 29 ++ snippets/steps/install-ios-sdk.mdx | 16 + 25 files changed, 1137 insertions(+), 68 deletions(-) create mode 100644 api-reference/endpoint/track-client-lead.mdx create mode 100644 api-reference/endpoint/track-client-sale.mdx create mode 100644 api-reference/publishable-keys.mdx create mode 100644 sdks/client-side-mobile/features/conversion-tracking.mdx create mode 100644 sdks/client-side-mobile/features/open-tracking.mdx create mode 100644 sdks/client-side-mobile/installation-guides/swift.mdx create mode 100644 sdks/client-side-mobile/introduction.mdx create mode 100644 snippets/dub-client-mobile-install.mdx create mode 100644 snippets/dub-client-mobile-installation-guides.mdx create mode 100644 snippets/steps/allowlist-domains.mdx create mode 100644 snippets/steps/generate-publishable-key.mdx create mode 100644 snippets/steps/initialize-ios-sdk.mdx create mode 100644 snippets/steps/install-ios-sdk.mdx diff --git a/api-reference/endpoint/track-client-lead.mdx b/api-reference/endpoint/track-client-lead.mdx new file mode 100644 index 00000000..b601764c --- /dev/null +++ b/api-reference/endpoint/track-client-lead.mdx @@ -0,0 +1,10 @@ +--- +openapi: post /track/lead/client +sidebarTitle: Track a lead event on the client-side +og:title: "Track a lead event on the client-side with the Dub API" +--- + + + Conversions endpoints require a [Business plan](https://dub.co/pricing) + subscription or higher. + diff --git a/api-reference/endpoint/track-client-sale.mdx b/api-reference/endpoint/track-client-sale.mdx new file mode 100644 index 00000000..e37f21b4 --- /dev/null +++ b/api-reference/endpoint/track-client-sale.mdx @@ -0,0 +1,11 @@ +--- +openapi: post /track/sale/client +sidebarTitle: Track a sale event on the client-side +og:title: "Track a sale event on the client-side with the Dub API" +--- + + + Conversions endpoints require a [Business plan](https://dub.co/pricing) + subscription or higher. + + diff --git a/api-reference/publishable-keys.mdx b/api-reference/publishable-keys.mdx new file mode 100644 index 00000000..590c8903 --- /dev/null +++ b/api-reference/publishable-keys.mdx @@ -0,0 +1,32 @@ +--- +title: "Publishable keys" +description: "Learn how publishable keys work on Dub." +--- + +import GeneratePublishableKeyStep from "/snippets/steps/generate-publishable-key.mdx"; +import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; + +Publishable keys on Dub allow you to safely embed authentication in client-side applications. +These keys are specifically designed to be used with Dub's client-side SDKs for features like conversion tracking. + +Unlike [API keys](/api-reference/api-keys) which must be kept secret, publishable keys can be safely exposed in your frontend code since they have limited capabilities. + +Publishable keys on Dub follow the format: + +```bash .env +DUB_PUBLISHABLE_KEY=dub_pk_xxxxxxxxxxxxxxxxxxxxxxxx +``` + +## Create a publishable key + +You can create a publishable key by following these steps: + + + + + + + +You can now use your publishable key to authenticate client-side requests in your application. Usage will depend on the client-side SDK you are using. + + \ No newline at end of file diff --git a/concepts/deep-links/attribution.mdx b/concepts/deep-links/attribution.mdx index e3b39e5c..86dcdb19 100644 --- a/concepts/deep-links/attribution.mdx +++ b/concepts/deep-links/attribution.mdx @@ -4,9 +4,208 @@ og:title: "How to set up deep link attribution with Dub" description: "Learn how to use deep link attribution to track conversions events with Dub." --- +import InstallationGuides from "/snippets/dub-client-mobile-installation-guides.mdx"; +import InstallIosSdkStep from "/snippets/steps/install-ios-sdk.mdx"; +import InitializeIosSdkStep from "/snippets/steps/initialize-ios-sdk.mdx"; +import ViewConversions from "/snippets/view-conversions.mdx"; + - This feature is coming soon. If you'd like early access, please [contact + Deep link attribution requires a [Business plan](https://dub.co/pricing) + subscription or higher. + + +Dub's powerful [attribution platform](https://dub.co/analytics) lets you understand how well your deep links are translating to actual users and revenue dollars inside your app. + + + This feature is currently only available for iOS (Swift). React Native and Android support are coming soon. If you'd like early access, please [contact us](https://dub.co/contact/support). -With [Dub Conversions](/conversions/quickstart), you can easily track conversion events from your deep links. + + Conversion analytics + + + +## Prerequisites + +Before you get started, make sure you have the following: + +1. Obtain your [publishable key](/api-reference/publishable-keys) (`DUB_PUBLISHABLE_KEY`) from your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and allowlist your site's domain (`DUB_DOMAIN`) to allow the client-side conversion events to be ingested by Dub. +2. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links) + +In this guide, we'll walk you through the steps to get started tracking conversions through your deep links. + +1. [Install the client-side Mobile SDK](#step-1%3A-install-the-client-side-mobile-sdk) +2. [Track deep link and deferred deep link events](#step-2%3A-track-deep-link-and-deferred-deep-link-events) +3. [Track conversion events](#step-3%3A-track-conversion-events-in-your-app) +4. [View your conversions](#step-4%3A-view-your-conversions) + +## Step 1: Install the client-side Mobile SDK + + + + +Install the [Dub iOS SDK](/sdks/client-side-mobile/installation-guides/swift) and initialize it with your publishable key and domain. + + + + + + + + + + + + +## Step 2: Track deep link and deferred deep link events + +Once the SDK has been initialized, you can start tracking deep link and deferred deep link events. +Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events. +The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then +again with the `deepLink` parameter whenever the app is opened from a deep link. + + + + +```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + @AppStorage("is_first_launch") private var isFirstLaunch = true + + var body: some View { + NavigationStack { + VStack { + // Your app content + } + .onOpenURL { url in + trackOpen(deepLink: url) + } + .onAppear { + if isFirstLaunch { + trackOpen() + isFirstLaunch = false + } + } + } + } + + private func trackOpen(deepLink: URL? = nil) { + Task { + do { + let response = try await dub.trackOpen(deepLink: deepLink) + + // Obtain the destination URL from the response + guard let url = response.link?.url else { + return + } + + // Navigate to the destination URL + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + + + +If the deep link was successfully resolved and correlated to the original click, the `response` object will contain the destination URL, which you can use to navigate the user to the appropriate screen. +It will also contain the `clickId`, which you can use to [track conversion events server-side](/conversions/quickstart#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) if you wish. + +## Step 3: Track conversion events + +You may track conversion events directly in your app with the `trackLead` and `trackSale` methods. + + + +```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + var body: some View { + // ... your app content ... + } + + private func trackLead(customerExternalId: String, name: String, email: String) { + Task { + do { + let response = try await dub.trackLead( + eventName: "User Sign Up", + customerExternalId: customerExternalId, + customerName: name, + customerEmail: email + ) + + print(response) + } catch let error as DubError { + print(error.localizedDescription) + } + } + } + + private func trackSale( + customerExternalId: String, + amount: Int, + currency: String = "usd", + eventName: String? = "Purchase", + paymentProcessor: PaymentProcessor = .custom, + invoiceId: String? = nil, + metadata: Metadata? = nil, + leadEventName: String? = nil, + customerName: String? = nil, + customerEmail: String? = nil, + customerAvatar: String? = nil + ) { + Task { + do { + let response = try await dub.trackSale( + customerExternalId: customerExternalId, + amount: amount, + currency: currency, + eventName: eventName, + paymentProcessor: paymentProcessor, + invoiceId: invoiceId, + metadata: metadata, + leadEventName: leadEventName, + customerName: customerName, + customerEmail: customerEmail, + customerAvatar: customerAvatar + ) + + print(response) + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + + + +Alternatively, you can track conversion events server-side for [lead events](/conversions/leads/introduction) and [sale events](/conversions/sales/introduction) by sending the `clickId` resolved from the deep link to your backend and then calling off to either: + +- [`POST /track/lead`](https://dub.co/docs/api-reference/endpoint/track-lead) +- [`POST /track/sale`](https://dub.co/docs/api-reference/endpoint/track-sale) + +## Step 4: View your conversions + +Once you've enabled conversion tracking for your links, all your tracked conversions will show up on your [Analytics dashboard](https://app.dub.co/analytics). We provide 3 different views to help you understand your conversions: + + diff --git a/concepts/deep-links/deferred-deep-linking.mdx b/concepts/deep-links/deferred-deep-linking.mdx index b39b692d..d5769865 100644 --- a/concepts/deep-links/deferred-deep-linking.mdx +++ b/concepts/deep-links/deferred-deep-linking.mdx @@ -469,7 +469,7 @@ Here is how it works in a nutshell: 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. +5. Your app calls the [`/track/open` endpoint](/api-reference/endpoint/track-open) with the `deepLink` parameter in the request body either directly or via a supported [Dub Mobile SDK](/sdks/client-side-mobile/introduction). 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 @@ -479,7 +479,7 @@ This method relies on matching the user’s device IP address from the initial c 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. +4. After installation, your app calls the [`/track/open` endpoint](/api-reference/endpoint/track-open) with the `dubDomain` parameter in the request body either directly or via a supported [Dub Mobile SDK](/sdks/client-side-mobile/introduction) . 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). @@ -488,7 +488,7 @@ This method relies on matching the user’s device IP address from the initial c 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. +- **IP-based tracking**: Used when no deep link is found in the clipboard or the user declined paste permissions. 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. @@ -555,7 +555,7 @@ async function trackOpen() { } ``` -```swift iOS +```swift iOS (SwiftUI) import SwiftUI @main @@ -677,7 +677,7 @@ export default function App() { } ``` -```swift iOS +```swift iOS (SwiftUI) import SwiftUI struct ContentView: View { diff --git a/concepts/deep-links/quickstart.mdx b/concepts/deep-links/quickstart.mdx index bbea1d8b..ab517660 100644 --- a/concepts/deep-links/quickstart.mdx +++ b/concepts/deep-links/quickstart.mdx @@ -58,7 +58,7 @@ In the domain modal, click on **Show advanced settings**, which will open up the **iOS (apple-app-site-association)** -For iOS apps, upload your Apple App Site Association file to enable iOS deep links: +For iOS apps, upload your [Apple App Site Association file ](https://developer.apple.com/documentation/xcode/supporting-associated-domains#Add-the-associated-domain-file-to-your-website) to enable iOS deep links: ```json apple-app-site-association { @@ -66,7 +66,7 @@ For iOS apps, upload your Apple App Site Association file to enable iOS deep lin "apps": [], "details": [ { - "appID": "YOUR_APP_ID", + "appID": ".", "paths": [] } ] @@ -103,8 +103,8 @@ Once you've set up your deep link configuration files, you can go to their respe - -Last but not least, you'll need to whitelist your deep link domain in your apps to allow them to redirect straight into a page within your app. + +Last but not least, you'll need to allowlist your deep link domain in your apps to allow them to redirect straight into a page within your app. **For iOS apps**, you'll need to [allow websites to link to your apps](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/). @@ -186,7 +186,79 @@ When a user opens your app from a deep link, you need to handle two main scenari ### Scenario 1: User has your app installed -When your app is already installed, the deep link will open your app directly. Here's how to handle it: +When your app is already installed, the deep link will open your app directly. +You may handle the deep link manually or with the supported mobile SDKs. + +**Option 1**: Handle the deep link using a supported [Dub Mobile SDK](/sdks/client-side-mobile/introduction) (iOS only) + +Follow our [Swift Installation Guide](/sdks/client-side-mobile/installation-guides/swift) to get started. + + + +```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + @AppStorage("is_first_launch") private var isFirstLaunch = true + + var body: some View { + NavigationStack { + VStack { + // Your app content + } + .onOpenURL { url in + trackOpen(deepLink: url) + } + .onAppear { + if isFirstLaunch { + trackOpen() + isFirstLaunch = false + } + } + } + } + + private func trackOpen(deepLink: URL? = nil) { + Task { + do { + let response = try await dub.trackOpen(deepLink: deepLink) + + // Obtain the destination URL from the response + guard let url = response.link?.url else { + return + } + + // Navigate to the destination URL + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + +```swift iOS (UIKit) +// AppDelegate.swift +func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { + handleDeepLink(url: url) + return true +} + +func handleDeepLink(url: URL) { + // Call the tracking endpoint with the full deep link URL + trackDeepLinkClick(deepLink: url.absoluteString) +} +``` + + + + +**Option 2**: Handle the deep link manually @@ -229,7 +301,7 @@ useEffect(() => { }, []); ``` -```swift iOS +```swift iOS (UIKit) // AppDelegate.swift func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { handleDeepLink(url: url) @@ -242,6 +314,24 @@ func handleDeepLink(url: URL) { } ``` +```swift iOS (SwiftUI) +// ContentView.swift +struct ContentView: View { + + var body: some View { + NavigationStack { + VStack { + //... your app content + } + .onOpenURL { url in + // Call the tracking endpoint with the full deep link URL + trackDeepLinkClick(deepLink: url.absoluteString) + } + } + } +} +``` + ```kotlin Android // MainActivity.kt override fun onNewIntent(intent: Intent?) { diff --git a/conversions/leads/client-side.mdx b/conversions/leads/client-side.mdx index d3e7ba75..9a598a4e 100644 --- a/conversions/leads/client-side.mdx +++ b/conversions/leads/client-side.mdx @@ -1,5 +1,5 @@ --- -title: Client-side tracking +title: Client-side tracking (web) og:title: Client-side lead tracking with Dub description: Learn how to track lead conversion events with Dub using client-side tracking --- diff --git a/conversions/quickstart.mdx b/conversions/quickstart.mdx index 817796b2..03e2b76b 100644 --- a/conversions/quickstart.mdx +++ b/conversions/quickstart.mdx @@ -12,7 +12,7 @@ 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) + Conversion tracking requires a [Business plan](https://dub.co/pricing) subscription or higher. diff --git a/conversions/sales/client-side.mdx b/conversions/sales/client-side.mdx index 547f41bd..ddd7d989 100644 --- a/conversions/sales/client-side.mdx +++ b/conversions/sales/client-side.mdx @@ -1,5 +1,5 @@ --- -title: Client-side tracking +title: Client-side tracking (web) og:title: Client-side sale tracking with Dub description: Learn how to track sales conversion events with Dub on the client-side --- diff --git a/conversions/sales/google-tag-manager.mdx b/conversions/sales/google-tag-manager.mdx index 7ba931ea..9a281bfe 100644 --- a/conversions/sales/google-tag-manager.mdx +++ b/conversions/sales/google-tag-manager.mdx @@ -9,7 +9,7 @@ import SalesAttributes from "/snippets/sale-attributes.mdx"; import ViewConversions from "/snippets/view-conversions.mdx"; - Conversion tracking require a [Business plan](https://dub.co/pricing) + Conversion tracking requires a [Business plan](https://dub.co/pricing) subscription or higher. diff --git a/conversions/sales/shopify.mdx b/conversions/sales/shopify.mdx index 315b1c72..7fee8369 100644 --- a/conversions/sales/shopify.mdx +++ b/conversions/sales/shopify.mdx @@ -7,7 +7,7 @@ description: "Learn how to track sale conversion events with Shopify and Dub" import ViewConversions from "/snippets/view-conversions.mdx"; - Conversion tracking require a [Business plan](https://dub.co/pricing) + Conversion tracking requires a [Business plan](https://dub.co/pricing) subscription or higher. diff --git a/docs.json b/docs.json index d10f879a..22fe8164 100644 --- a/docs.json +++ b/docs.json @@ -9,7 +9,14 @@ }, "favicon": "/logos/favicon.png", "contextual": { - "options": ["copy", "view", "chatgpt", "claude", "cursor", "vscode"] + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "cursor", + "vscode" + ] }, "navigation": { "anchors": [ @@ -18,7 +25,9 @@ "groups": [ { "group": "Getting Started", - "pages": ["introduction"] + "pages": [ + "introduction" + ] }, { "group": "Links", @@ -90,7 +99,10 @@ }, { "group": "Dub Partners", - "pages": ["partners/quickstart", "partners/embedded-referrals"] + "pages": [ + "partners/quickstart", + "partners/embedded-referrals" + ] }, { "group": "Integrations", @@ -109,7 +121,10 @@ }, { "group": "Open source", - "pages": ["local-development", "self-hosting"] + "pages": [ + "local-development", + "self-hosting" + ] } ] }, @@ -122,6 +137,7 @@ "pages": [ "api-reference/introduction", "api-reference/api-keys", + "api-reference/publishable-keys", "api-reference/rate-limits" ] }, @@ -140,7 +156,7 @@ ] }, { - "group": "Client-side SDK", + "group": "Client-side SDK (Web)", "pages": [ "sdks/client-side/introduction", { @@ -168,8 +184,16 @@ ] }, { - "group": "Embedded Dashboards", - "pages": ["sdks/embed/referrals", "sdks/embed/analytics"] + "group": "Client-side SDK (Mobile)", + "pages": [ + "sdks/client-side-mobile/introduction", + { + "group": "Installation Guides", + "pages": [ + "sdks/client-side-mobile/installation-guides/swift" + ] + } + ] } ] }, @@ -472,4 +496,4 @@ "destination": "/api-reference/introduction#error-handling" } ] -} +} \ No newline at end of file diff --git a/sdks/client-side-mobile/features/conversion-tracking.mdx b/sdks/client-side-mobile/features/conversion-tracking.mdx new file mode 100644 index 00000000..f03cc4fe --- /dev/null +++ b/sdks/client-side-mobile/features/conversion-tracking.mdx @@ -0,0 +1,51 @@ +--- +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: + + + A diagram showing how click events are tracked in the conversion funnel + + +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). + + + A diagram showing how lead events are tracked in the conversion funnel + + +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. + + + A diagram showing how sale events are tracked in the conversion funnel + + + + +## Client-side lead tracking + + + +## Client-side sale tracking + + diff --git a/sdks/client-side-mobile/features/open-tracking.mdx b/sdks/client-side-mobile/features/open-tracking.mdx new file mode 100644 index 00000000..f0c95f27 --- /dev/null +++ b/sdks/client-side-mobile/features/open-tracking.mdx @@ -0,0 +1,296 @@ +--- +title: Deep link open tracking +description: Track clicks on the client-side using query parameters +--- + +import DubAnalyticsParams from "/snippets/dub-analytics-params-react.mdx"; +import VerifyTrackClick from "/snippets/verify-track-click.mdx"; + +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: + + + + + +First, you'll need to [add a custom short link domain](https://dub.co/help/article/how-to-add-custom-domain) to your Dub workspace. You can use a domain you already own, or leverage our [free .link domain offer](https://dub.co/help/article/free-dot-link-domain) to register a custom domain like `yourcompany.link` for free. + +This is the domain that you'll use for your short links on Dub. + + + + + +Then, you'll need to allowlist your site's domain to allow the client-side click 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. + + + 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 [client-side SDK](/sdks/client-side/introduction) and initialize it with the domain you added in the previous step. + + + +```typescript React/Next.js +// install the package (e.g. npm install @dub/analytics) +import { Analytics as DubAnalytics } from "@dub/analytics/react"; + +export default function App() { + return ( + + + {/* Your app code here */} + + ); +} +``` + +```javascript Other Frameworks +// include this script tag in your HTML Head tag + +``` + + + +Here's the full list of parameters you can pass to the script: + + + + + + + + + +To avoid ad-blockers from blocking your click-tracking requests, we recommend setting up a reverse proxy. + +Refer to the [Reverse-proxy support](/sdks/client-side/features/reverse-proxy-support) guide to learn how to set one up. + + + + + +To verify that your click-tracking is working, run your website locally and append the URL with the unique key of your short link + +For example, if your short link is `https://go.example.com/abc123`, you'll need to append `?via=abc123` to the URL. + +Once you've done that, check if the following is true: + + + + + + + +## Automatically fetching partner and discount data + +If you're using [Dub Partners](/partners/quickstart) with [dual-sided incentives](https://dub.co/help/article/dual-sided-incentives), the script will automatically fetch the partner and discount data for you when someone lands on your site via a valid referral link. + +This data will be stored as a JSON-stringified object in the `dub_partner_data` cookie in the following format: + +```json +{ + "clickId": "xxx", // unique ID of the click event + "partner": { + "id": "pn_xxx", // unique ID of the partner on Dub + "name": "John Doe", // name of the partner + "image": "https://example.com/john.png" // avatar of the partner + }, + "discount": { + "id": "disc_xxx", // unique ID of the discount on Dub + "amount": 25, // discount amount (either a percentage or a fixed amount) + "type": "percentage", // type of the discount (either "percentage" or "fixed") + "maxDuration": 3, // maximum duration of the discount in months + "couponId": "XZuejd0Q", // Stripe coupon code + "couponTestId": "2NMXz81x" // Stripe test coupon ID + } +} +``` + +You can access partner and discount data in your application code using the `useAnalytics()` hook. If you’re working in a non-React environment, you can use the `DubAnalytics` object directly. + +Here is a quick example of how you can display a discount banner using the `useAnalytics()` hook: + + + +```typescript React/Next.js +// Display a banner that says: _"John referred you to Acme and gave you 25% off"_ +import { useAnalytics } from "@dub/analytics/react"; + +function DiscountBanner() { + const { partner, discount } = useAnalytics(); + + if (!partner || !discount) { + return null; + } + + return ( +
+ {partner.name} +

+ {partner.name} referred you to Acme and gave you {discount.amount}{" "} + {discount.type} off +

+
+ ); +} +``` + +```javascript Other Frameworks +// Display a banner that says: _"John referred you to Acme and gave you 25% off"_ +dubAnalytics("ready", function () { + if (DubAnalytics.partner && DubAnalytics.discount) { + const banner = document.createElement("div"); + + banner.innerHTML = ` +
+ ${DubAnalytics.partner.name} +

${DubAnalytics.partner.name} referred you to Acme and gave you ${DubAnalytics.discount.amount} ${DubAnalytics.discount.type} off

+
+ `; + document.body.appendChild(banner); + } +}); +``` + + + +Here's an example of how the discount banner will look like: + + + A screenshot of the Dub partner data example + + +## 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: + + + The domain of the short link (e.g. `getacme.link`) + + + + The short link slug (e.g. `john`) + + +Here's how you can use the `trackClick()` function in your application: + + + +```typescript React/Next.js +import { useAnalytics } from "@dub/analytics/react"; +import { useRouter } from "next/router"; + +function BookingPage() { + const router = useRouter(); + const { trackClick } = useAnalytics(); + + // Extract the key from the URL path (e.g., /john -> john) + const { slug: key } = router.query; + + useEffect(() => { + if (key) { + trackClick({ + domain: "getacme.link", + key, + }); + } + }, [key, trackClick]); + + return <>; +} +``` + +```javascript Other Frameworks +document.addEventListener("DOMContentLoaded", function () { + // Extract the key from the URL path (e.g., /john -> john) + const pathSegments = window.location.pathname.split("/"); + const key = pathSegments[1]; + + if (key) { + dubAnalytics.trackClick({ + domain: "getacme.link", + key, + }); + } +}); + +// This will track clicks for URLs like cal.com/john +``` + + + +## Differences from server-side click-tracking + +Server-side click-tracking is enabled by default for all Dub links and come with the following attributes: + +| Attribute | Type | Description | +| :----------- | :------ | :----------------------------------------------------------------------------------------------- | +| `timestamp` | string | The timestamp of the click event | +| `id` | string | The unique ID of the click event | +| `url` | string | The destination URL that the link resolved to – this can vary if geo/device-targeting is enabled | +| `continent` | string | The continent of the user who clicked the link | +| `country` | string | The country of the user who clicked the link | +| `city` | string | The city of the user who clicked the link | +| `device` | string | The device of the user who clicked the link | +| `browser` | string | The browser of the user who clicked the link | +| `os` | string | The operating system of the user who clicked the link | +| `referer` | string | The referrer of the user who clicked the link | +| `refererUrl` | string | The full referrer URL of the user who clicked the link | +| `qr` | boolean | Whether the click event was triggered by a QR code scan | +| `ip` | string | The IP address of the user who clicked the link (non-EU users only) | + +These events happen on the server-side and cannot be blocked by browser extensions or ad-blockers, which improves the accuracy of your analytics data. diff --git a/sdks/client-side-mobile/installation-guides/swift.mdx b/sdks/client-side-mobile/installation-guides/swift.mdx new file mode 100644 index 00000000..b475a8ef --- /dev/null +++ b/sdks/client-side-mobile/installation-guides/swift.mdx @@ -0,0 +1,37 @@ +--- +title: Swift +description: How to add the Dub iOS SDK to your Swift project +--- + +import DubSwiftInstall from "/snippets/dub-client-mobile-install.mdx"; +import DubAnalyticsParams from "/snippets/dub-analytics-params-react.mdx"; +import DubClientInstallVerify from "/snippets/dub-client-install-verify.mdx"; + +## Prerequisites + +Before you get started, make sure you have the following: + +1. Obtain your [publishable key](/api-reference/publishable-keys) (`DUB_PUBLISHABLE_KEY`) from your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and allowlist your site's domain (`DUB_DOMAIN`) to allow the client-side conversion events to be ingested by Dub. + +2. (Optional) If you plan to track conversions, follow the [Dub Conversions quickstart guide](/conversions/quickstart) to [enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links). + +## Quickstart + +This quick start guide will show you how to get started with Dub iOS SDK in your Swift project. + + + +## Examples + +Here are some open-source code examples that you can reference: + + + + See the full example on GitHub. + + diff --git a/sdks/client-side-mobile/introduction.mdx b/sdks/client-side-mobile/introduction.mdx new file mode 100644 index 00000000..724c578c --- /dev/null +++ b/sdks/client-side-mobile/introduction.mdx @@ -0,0 +1,40 @@ +--- +title: Introduction +description: Learn more about the the Dub client-side mobile SDKs. +--- + +import InstallationGuides from "/snippets/dub-client-mobile-installation-guides.mdx"; +import DubAnalyticsParams from "/snippets/dub-analytics-params.mdx"; + +Dub offers first-party, open-source, mobile SDKs to help you track [deep links](/concepts/deep-links/quickstart), [deferred deep links](/concepts/deep-links/deferred-deep-linking), and [deep link attribution](/concepts/deep-links/attribution) in your mobile applications. + +Currently, we support the following mobile SDKs: + +- [Dub iOS SDK](https://github.com/dubinc/dub-ios) + + + React Native and Android support are coming soon. If you'd like early access, please [contact + us](https://dub.co/contact/support). + + + +## Installation guides + +Dub currently supports the following client-side mobile SDKs: + + + +## Open-source examples + +Here are some open-source code examples that you can reference: + + + + See the full example on GitHub. + + diff --git a/sdks/overview.mdx b/sdks/overview.mdx index e47d5334..e766e314 100644 --- a/sdks/overview.mdx +++ b/sdks/overview.mdx @@ -33,6 +33,14 @@ Dub offers server-side SDKs for many popular programming languages: +## Client-side mobile SDKs + + + + Dub iOS SDK + + + ## Embedded Dashboards diff --git a/snippets/client-side-tracking-install.mdx b/snippets/client-side-tracking-install.mdx index b63863b1..831aabb6 100644 --- a/snippets/client-side-tracking-install.mdx +++ b/snippets/client-side-tracking-install.mdx @@ -1,49 +1,13 @@ +import GeneratePublishableKeyStep from "/snippets/steps/generate-publishable-key.mdx"; +import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; + ## 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! - - - + diff --git a/snippets/dub-client-mobile-install.mdx b/snippets/dub-client-mobile-install.mdx new file mode 100644 index 00000000..dd4c2189 --- /dev/null +++ b/snippets/dub-client-mobile-install.mdx @@ -0,0 +1,211 @@ + + + Before installing, ensure your environment meets these minimum requirements: + + **Build Tools:** + - Xcode 16+ + - Swift 6+ + + **Platforms:** + - iOS 16.0+ + - macOS 10.13 (Ventura)+ + + The Dub iOS SDK can be installed using the [Swift Package Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/). + + In Xcode, select **File** > **Add Package Dependencies** and add `https://github.com/dubinc/dub-ios` as the repository URL. Select the latest version of the SDK from the [release page](https://github.com/dubinc/dub-ios/releases). + + + + + + You must call `Dub.setup` with your publishable key and domain prior to being able to use the `dub` instance. + + + +```swift iOS (SwiftUI) +import SwiftUI +import Dub + +@main +struct DubApp: App { + // Step 1: Obtain your Dub domain and publishable key + private let dubPublishableKey = "" + private let dubDomain = "" + + init() { + // Step 2: Initialize the Dub SDK by calling `setup` + Dub.setup(publishableKey: dubPublishableKey, domain: dubDomain) + } + + var body: some Scene { + WindowGroup { + ContentView() + // Step 3: Expose the `dub` instance as a SwiftUI environment value + .environment(\.dub, Dub.shared) + } + } +} +``` + + + + + + Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events. + The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then + again with the `deepLink` parameter whenever the app is opened from a deep link. + + + +```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + @AppStorage("is_first_launch") private var isFirstLaunch = true + + var body: some View { + NavigationStack { + VStack { + // Your app content + } + .onOpenURL { url in + trackOpen(deepLink: url) + } + .onAppear { + if isFirstLaunch { + trackOpen() + isFirstLaunch = false + } + } + } + } + + private func trackOpen(deepLink: URL? = nil) { + Task { + do { + let response = try await dub.trackOpen(deepLink: deepLink) + + // Obtain the destination URL from the response + guard let url = response.link?.url else { + return + } + + // Navigate to the destination URL + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + + + + + + + + To track lead events, call `trackLead` on the `dub` instance with your customer's external ID, name, and email. Learn more about the [lead event attributes](/conversions/leads/introduction#lead-event-attributes). + + + +```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + var body: some View { + // ... your app content ... + } + + private func trackLead(customerExternalId: String, name: String, email: String) { + Task { + do { + let response = try await dub.trackLead( + eventName: "User Sign Up", + customerExternalId: customerExternalId, + customerName: name, + customerEmail: email + ) + + print(response) + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + + + + + + + To track sale events, call `trackSale` on the `dub` instance with your customer's user ID and purchase information. Learn more about the [sale event attributes](/conversions/sales/introduction#sale-event-attributes). + + ```swift iOS (SwiftUI) +// ContentView.swift +import SwiftUI +import Dub + +struct ContentView: View { + + @Environment(\.dub) var dub: Dub + + var body: some View { + // ... your app content ... + } + + private func trackSale( + customerExternalId: String, + amount: Int, + currency: String = "usd", + eventName: String? = "Purchase", + paymentProcessor: PaymentProcessor = .custom, + invoiceId: String? = nil, + metadata: Metadata? = nil, + leadEventName: String? = nil, + customerName: String? = nil, + customerEmail: String? = nil, + customerAvatar: String? = nil + ) { + Task { + do { + let response = try await dub.trackSale( + customerExternalId: customerExternalId, + amount: amount, + currency: currency, + eventName: eventName, + paymentProcessor: paymentProcessor, + invoiceId: invoiceId, + metadata: metadata, + leadEventName: leadEventName, + customerName: customerName, + customerEmail: customerEmail, + customerAvatar: customerAvatar + ) + + print(response) + } catch let error as DubError { + print(error.localizedDescription) + } + } + } +} +``` + + + + + + diff --git a/snippets/dub-client-mobile-installation-guides.mdx b/snippets/dub-client-mobile-installation-guides.mdx new file mode 100644 index 00000000..8510021d --- /dev/null +++ b/snippets/dub-client-mobile-installation-guides.mdx @@ -0,0 +1,10 @@ + + + + Add the Dub iOS SDK to your app (Swift) + + diff --git a/snippets/leads-intro.mdx b/snippets/leads-intro.mdx index 1d2e1799..81b9f74a 100644 --- a/snippets/leads-intro.mdx +++ b/snippets/leads-intro.mdx @@ -1,5 +1,5 @@ - Conversion tracking require a [Business plan](https://dub.co/pricing) + Conversion tracking requires a [Business plan](https://dub.co/pricing) subscription or higher. diff --git a/snippets/steps/allowlist-domains.mdx b/snippets/steps/allowlist-domains.mdx new file mode 100644 index 00000000..f6d7c5dc --- /dev/null +++ b/snippets/steps/allowlist-domains.mdx @@ -0,0 +1,27 @@ + + +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! + + + diff --git a/snippets/steps/generate-publishable-key.mdx b/snippets/steps/generate-publishable-key.mdx new file mode 100644 index 00000000..dbae8439 --- /dev/null +++ b/snippets/steps/generate-publishable-key.mdx @@ -0,0 +1,14 @@ + + +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 + + + diff --git a/snippets/steps/initialize-ios-sdk.mdx b/snippets/steps/initialize-ios-sdk.mdx new file mode 100644 index 00000000..2b93f0b4 --- /dev/null +++ b/snippets/steps/initialize-ios-sdk.mdx @@ -0,0 +1,29 @@ + + +You must call `Dub.setup` with your publishable key and domain prior to being able to use the `dub` instance. + +```swift iOS (SwiftUI) +import SwiftUI +import Dub + +@main +struct DubApp: App { + // Step 1: Obtain your Dub domain and publishable key + private let dubPublishableKey = "" + private let dubDomain = "" + + init() { + // Step 2: Initialize the Dub SDK by calling `setup` + Dub.setup(publishableKey: dubPublishableKey, domain: dubDomain) + } + + var body: some Scene { + WindowGroup { + ContentView() + // Step 3: Expose the `dub` instance as a SwiftUI environment value + .environment(\.dub, Dub.shared) + } + } +} +``` + diff --git a/snippets/steps/install-ios-sdk.mdx b/snippets/steps/install-ios-sdk.mdx new file mode 100644 index 00000000..517babaa --- /dev/null +++ b/snippets/steps/install-ios-sdk.mdx @@ -0,0 +1,16 @@ + +Before installing, ensure your environment meets these minimum requirements: + +**Build Tools:** +- Xcode 16+ +- Swift 6+ + +**Platforms:** +- iOS 16.0+ +- macOS 10.13 (Ventura)+ + +The Dub iOS SDK can be installed using the [Swift Package Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/). + +In Xcode, select **File** > **Add Package Dependencies** and add `https://github.com/dubinc/dub-ios` as the repository URL. Select the latest version of the SDK from the [release page](https://github.com/dubinc/dub-ios/releases). + + \ No newline at end of file From 77ea55e7b02845ef72b7e5b34000ced623992ddd Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Wed, 17 Sep 2025 17:03:37 -0400 Subject: [PATCH 04/13] Removes track client lead / sales endpoints --- api-reference/endpoint/track-client-lead.mdx | 10 ---------- api-reference/endpoint/track-client-sale.mdx | 11 ----------- 2 files changed, 21 deletions(-) delete mode 100644 api-reference/endpoint/track-client-lead.mdx delete mode 100644 api-reference/endpoint/track-client-sale.mdx diff --git a/api-reference/endpoint/track-client-lead.mdx b/api-reference/endpoint/track-client-lead.mdx deleted file mode 100644 index b601764c..00000000 --- a/api-reference/endpoint/track-client-lead.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -openapi: post /track/lead/client -sidebarTitle: Track a lead event on the client-side -og:title: "Track a lead event on the client-side with the Dub API" ---- - - - Conversions endpoints require a [Business plan](https://dub.co/pricing) - subscription or higher. - diff --git a/api-reference/endpoint/track-client-sale.mdx b/api-reference/endpoint/track-client-sale.mdx deleted file mode 100644 index e37f21b4..00000000 --- a/api-reference/endpoint/track-client-sale.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -openapi: post /track/sale/client -sidebarTitle: Track a sale event on the client-side -og:title: "Track a sale event on the client-side with the Dub API" ---- - - - Conversions endpoints require a [Business plan](https://dub.co/pricing) - subscription or higher. - - From bd25049226ff766dfbe1b215e47d63c3cb720f8a Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Wed, 17 Sep 2025 17:08:39 -0400 Subject: [PATCH 05/13] Removes unused feature files --- .../features/conversion-tracking.mdx | 51 --- .../features/open-tracking.mdx | 296 ------------------ 2 files changed, 347 deletions(-) delete mode 100644 sdks/client-side-mobile/features/conversion-tracking.mdx delete mode 100644 sdks/client-side-mobile/features/open-tracking.mdx diff --git a/sdks/client-side-mobile/features/conversion-tracking.mdx b/sdks/client-side-mobile/features/conversion-tracking.mdx deleted file mode 100644 index f03cc4fe..00000000 --- a/sdks/client-side-mobile/features/conversion-tracking.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -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: - - - A diagram showing how click events are tracked in the conversion funnel - - -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). - - - A diagram showing how lead events are tracked in the conversion funnel - - -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. - - - A diagram showing how sale events are tracked in the conversion funnel - - - - -## Client-side lead tracking - - - -## Client-side sale tracking - - diff --git a/sdks/client-side-mobile/features/open-tracking.mdx b/sdks/client-side-mobile/features/open-tracking.mdx deleted file mode 100644 index f0c95f27..00000000 --- a/sdks/client-side-mobile/features/open-tracking.mdx +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Deep link open tracking -description: Track clicks on the client-side using query parameters ---- - -import DubAnalyticsParams from "/snippets/dub-analytics-params-react.mdx"; -import VerifyTrackClick from "/snippets/verify-track-click.mdx"; - -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: - - - - - -First, you'll need to [add a custom short link domain](https://dub.co/help/article/how-to-add-custom-domain) to your Dub workspace. You can use a domain you already own, or leverage our [free .link domain offer](https://dub.co/help/article/free-dot-link-domain) to register a custom domain like `yourcompany.link` for free. - -This is the domain that you'll use for your short links on Dub. - - - - - -Then, you'll need to allowlist your site's domain to allow the client-side click 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. - - - 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 [client-side SDK](/sdks/client-side/introduction) and initialize it with the domain you added in the previous step. - - - -```typescript React/Next.js -// install the package (e.g. npm install @dub/analytics) -import { Analytics as DubAnalytics } from "@dub/analytics/react"; - -export default function App() { - return ( - - - {/* Your app code here */} - - ); -} -``` - -```javascript Other Frameworks -// include this script tag in your HTML Head tag - -``` - - - -Here's the full list of parameters you can pass to the script: - - - - - - - - - -To avoid ad-blockers from blocking your click-tracking requests, we recommend setting up a reverse proxy. - -Refer to the [Reverse-proxy support](/sdks/client-side/features/reverse-proxy-support) guide to learn how to set one up. - - - - - -To verify that your click-tracking is working, run your website locally and append the URL with the unique key of your short link - -For example, if your short link is `https://go.example.com/abc123`, you'll need to append `?via=abc123` to the URL. - -Once you've done that, check if the following is true: - - - - - - - -## Automatically fetching partner and discount data - -If you're using [Dub Partners](/partners/quickstart) with [dual-sided incentives](https://dub.co/help/article/dual-sided-incentives), the script will automatically fetch the partner and discount data for you when someone lands on your site via a valid referral link. - -This data will be stored as a JSON-stringified object in the `dub_partner_data` cookie in the following format: - -```json -{ - "clickId": "xxx", // unique ID of the click event - "partner": { - "id": "pn_xxx", // unique ID of the partner on Dub - "name": "John Doe", // name of the partner - "image": "https://example.com/john.png" // avatar of the partner - }, - "discount": { - "id": "disc_xxx", // unique ID of the discount on Dub - "amount": 25, // discount amount (either a percentage or a fixed amount) - "type": "percentage", // type of the discount (either "percentage" or "fixed") - "maxDuration": 3, // maximum duration of the discount in months - "couponId": "XZuejd0Q", // Stripe coupon code - "couponTestId": "2NMXz81x" // Stripe test coupon ID - } -} -``` - -You can access partner and discount data in your application code using the `useAnalytics()` hook. If you’re working in a non-React environment, you can use the `DubAnalytics` object directly. - -Here is a quick example of how you can display a discount banner using the `useAnalytics()` hook: - - - -```typescript React/Next.js -// Display a banner that says: _"John referred you to Acme and gave you 25% off"_ -import { useAnalytics } from "@dub/analytics/react"; - -function DiscountBanner() { - const { partner, discount } = useAnalytics(); - - if (!partner || !discount) { - return null; - } - - return ( -
- {partner.name} -

- {partner.name} referred you to Acme and gave you {discount.amount}{" "} - {discount.type} off -

-
- ); -} -``` - -```javascript Other Frameworks -// Display a banner that says: _"John referred you to Acme and gave you 25% off"_ -dubAnalytics("ready", function () { - if (DubAnalytics.partner && DubAnalytics.discount) { - const banner = document.createElement("div"); - - banner.innerHTML = ` -
- ${DubAnalytics.partner.name} -

${DubAnalytics.partner.name} referred you to Acme and gave you ${DubAnalytics.discount.amount} ${DubAnalytics.discount.type} off

-
- `; - document.body.appendChild(banner); - } -}); -``` - - - -Here's an example of how the discount banner will look like: - - - A screenshot of the Dub partner data example - - -## 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: - - - The domain of the short link (e.g. `getacme.link`) - - - - The short link slug (e.g. `john`) - - -Here's how you can use the `trackClick()` function in your application: - - - -```typescript React/Next.js -import { useAnalytics } from "@dub/analytics/react"; -import { useRouter } from "next/router"; - -function BookingPage() { - const router = useRouter(); - const { trackClick } = useAnalytics(); - - // Extract the key from the URL path (e.g., /john -> john) - const { slug: key } = router.query; - - useEffect(() => { - if (key) { - trackClick({ - domain: "getacme.link", - key, - }); - } - }, [key, trackClick]); - - return <>; -} -``` - -```javascript Other Frameworks -document.addEventListener("DOMContentLoaded", function () { - // Extract the key from the URL path (e.g., /john -> john) - const pathSegments = window.location.pathname.split("/"); - const key = pathSegments[1]; - - if (key) { - dubAnalytics.trackClick({ - domain: "getacme.link", - key, - }); - } -}); - -// This will track clicks for URLs like cal.com/john -``` - - - -## Differences from server-side click-tracking - -Server-side click-tracking is enabled by default for all Dub links and come with the following attributes: - -| Attribute | Type | Description | -| :----------- | :------ | :----------------------------------------------------------------------------------------------- | -| `timestamp` | string | The timestamp of the click event | -| `id` | string | The unique ID of the click event | -| `url` | string | The destination URL that the link resolved to – this can vary if geo/device-targeting is enabled | -| `continent` | string | The continent of the user who clicked the link | -| `country` | string | The country of the user who clicked the link | -| `city` | string | The city of the user who clicked the link | -| `device` | string | The device of the user who clicked the link | -| `browser` | string | The browser of the user who clicked the link | -| `os` | string | The operating system of the user who clicked the link | -| `referer` | string | The referrer of the user who clicked the link | -| `refererUrl` | string | The full referrer URL of the user who clicked the link | -| `qr` | boolean | Whether the click event was triggered by a QR code scan | -| `ip` | string | The IP address of the user who clicked the link (non-EU users only) | - -These events happen on the server-side and cannot be blocked by browser extensions or ad-blockers, which improves the accuracy of your analytics data. From 2cff6c0d42a4d2c3bbd1a567b98a3299313b78b9 Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Wed, 17 Sep 2025 17:16:12 -0400 Subject: [PATCH 06/13] Cleans up attribution doc --- concepts/deep-links/attribution.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/concepts/deep-links/attribution.mdx b/concepts/deep-links/attribution.mdx index 86dcdb19..6f7272ff 100644 --- a/concepts/deep-links/attribution.mdx +++ b/concepts/deep-links/attribution.mdx @@ -121,7 +121,9 @@ struct ContentView: View { If the deep link was successfully resolved and correlated to the original click, the `response` object will contain the destination URL, which you can use to navigate the user to the appropriate screen. -It will also contain the `clickId`, which you can use to [track conversion events server-side](/conversions/quickstart#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) if you wish. +It will also contain the `clickId`, which the `dub` instance will persist internally. +If you wish to use [server-side conversion tracking](/conversions/quickstart#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) you will have to send the `clickId` to your server. +You may access it any time by calling the `clickId` property on the `dub` instance. ## Step 3: Track conversion events @@ -199,7 +201,7 @@ struct ContentView: View { -Alternatively, you can track conversion events server-side for [lead events](/conversions/leads/introduction) and [sale events](/conversions/sales/introduction) by sending the `clickId` resolved from the deep link to your backend and then calling off to either: +Alternatively, you can [track conversion events server-side](/conversions/quickstart#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) for [lead events](/conversions/leads/introduction) and [sale events](/conversions/sales/introduction) by sending the `clickId` resolved from the deep link to your backend and then calling off to either: - [`POST /track/lead`](https://dub.co/docs/api-reference/endpoint/track-lead) - [`POST /track/sale`](https://dub.co/docs/api-reference/endpoint/track-sale) From b9baf995ad9e4e0807be2643b269014a2bcff42f Mon Sep 17 00:00:00 2001 From: Ian MacCallum Date: Fri, 19 Sep 2025 09:13:38 -0400 Subject: [PATCH 07/13] Conversion tracking (it) requires --- snippets/sales-intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snippets/sales-intro.mdx b/snippets/sales-intro.mdx index bcaebcb8..a061d54a 100644 --- a/snippets/sales-intro.mdx +++ b/snippets/sales-intro.mdx @@ -1,5 +1,5 @@ - Conversion tracking require a [Business plan](https://dub.co/pricing) + Conversion tracking requires a [Business plan](https://dub.co/pricing) subscription or higher. From 92d83c000f831eb479566aefc3a818b4f3981465 Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 15:49:43 -0700 Subject: [PATCH 08/13] fix --- conversions/leads/client-side.mdx | 2 +- conversions/sales/client-side.mdx | 2 +- snippets/client-side-tracking-install.mdx | 2 -- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/conversions/leads/client-side.mdx b/conversions/leads/client-side.mdx index d6518ccc..9c974815 100644 --- a/conversions/leads/client-side.mdx +++ b/conversions/leads/client-side.mdx @@ -1,5 +1,5 @@ --- -title: Client-side tracking (web) +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 --- diff --git a/conversions/sales/client-side.mdx b/conversions/sales/client-side.mdx index de4754f0..f8a4094b 100644 --- a/conversions/sales/client-side.mdx +++ b/conversions/sales/client-side.mdx @@ -1,5 +1,5 @@ --- -title: Client-side tracking (web) +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 --- diff --git a/snippets/client-side-tracking-install.mdx b/snippets/client-side-tracking-install.mdx index f6be0b1f..7a8c5fdc 100644 --- a/snippets/client-side-tracking-install.mdx +++ b/snippets/client-side-tracking-install.mdx @@ -1,8 +1,6 @@ import GeneratePublishableKeyStep from "/snippets/steps/generate-publishable-key.mdx"; import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; -## Quickstart - Then, you'll need to install the Dub client-side script and set up the necessary configuration for client-side conversion tracking: From e00bc409048f31875630c5a746501ba0c1e24c65 Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 15:58:07 -0700 Subject: [PATCH 09/13] finalize docs --- conversions/leads/appwrite.mdx | 4 +- conversions/leads/auth0.mdx | 4 +- conversions/leads/better-auth.mdx | 2 +- conversions/leads/clerk.mdx | 4 +- conversions/leads/deferred.mdx | 2 +- conversions/leads/google-tag-manager.mdx | 4 +- conversions/leads/introduction.mdx | 4 +- conversions/leads/next-auth.mdx | 4 +- conversions/leads/segment.mdx | 4 +- conversions/leads/supabase.mdx | 4 +- snippets/client-side-lead-tracking.mdx | 4 +- snippets/dub-client-mobile-install.mdx | 137 ++++++++++-------- ...ads-attributes.mdx => lead-attributes.mdx} | 0 13 files changed, 95 insertions(+), 82 deletions(-) rename snippets/{leads-attributes.mdx => lead-attributes.mdx} (100%) diff --git a/conversions/leads/appwrite.mdx b/conversions/leads/appwrite.mdx index 15e3ba7b..297ff496 100644 --- a/conversions/leads/appwrite.mdx +++ b/conversions/leads/appwrite.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with Appwrite and Dub" import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -233,7 +233,7 @@ Next, configure Appwrite to track lead conversion events during the sign up proc - + ## Example App diff --git a/conversions/leads/auth0.mdx b/conversions/leads/auth0.mdx index a3eba0ae..2daeb606 100644 --- a/conversions/leads/auth0.mdx +++ b/conversions/leads/auth0.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with Auth0 and Dub" import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -63,6 +63,6 @@ export default handleAuth({ }); ``` - + diff --git a/conversions/leads/better-auth.mdx b/conversions/leads/better-auth.mdx index bab58cd8..d3fea613 100644 --- a/conversions/leads/better-auth.mdx +++ b/conversions/leads/better-auth.mdx @@ -8,7 +8,7 @@ description: "Learn how to track lead conversion events with Better Auth and Dub import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; diff --git a/conversions/leads/clerk.mdx b/conversions/leads/clerk.mdx index a5055175..83949fe9 100644 --- a/conversions/leads/clerk.mdx +++ b/conversions/leads/clerk.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with Clerk and Dub" import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -233,7 +233,7 @@ Here's a quick summary of the steps: - + ## Example App diff --git a/conversions/leads/deferred.mdx b/conversions/leads/deferred.mdx index 2a8f5151..d9d9a05f 100644 --- a/conversions/leads/deferred.mdx +++ b/conversions/leads/deferred.mdx @@ -6,7 +6,7 @@ description: Learn how to track a deferred lead conversion event with Dub import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; diff --git a/conversions/leads/google-tag-manager.mdx b/conversions/leads/google-tag-manager.mdx index 0e39a490..4852c754 100644 --- a/conversions/leads/google-tag-manager.mdx +++ b/conversions/leads/google-tag-manager.mdx @@ -7,7 +7,7 @@ og:image: https://assets.dub.co/cms/gtm-integration.jpeg import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -209,7 +209,7 @@ Under the **Triggering** section, configure when the tag should fire: - **Value**: "Sign Up" - Name the trigger "Dub Lead Event Trigger" and save it - + ## Testing your setup diff --git a/conversions/leads/introduction.mdx b/conversions/leads/introduction.mdx index f7b5b109..456a1007 100644 --- a/conversions/leads/introduction.mdx +++ b/conversions/leads/introduction.mdx @@ -8,7 +8,7 @@ description: Learn how to track lead conversion events with Dub using server-sid import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; import AuthProviders from "/snippets/auth-providers.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -167,5 +167,5 @@ if ($dubId) { - + diff --git a/conversions/leads/next-auth.mdx b/conversions/leads/next-auth.mdx index 8e68a84c..a455b9de 100644 --- a/conversions/leads/next-auth.mdx +++ b/conversions/leads/next-auth.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with NextAuth.js and Dub import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -108,7 +108,7 @@ export const getOptions = (req: NextApiRequest): NextAuthOptions => ({ `callback`](https://next-auth.js.org/configuration/callbacks) instead. - + ## Create a NextAuth.js Route Handler diff --git a/conversions/leads/segment.mdx b/conversions/leads/segment.mdx index 8b9985b2..c94d9363 100644 --- a/conversions/leads/segment.mdx +++ b/conversions/leads/segment.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with Segment and Dub" import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -133,7 +133,7 @@ Next, configure [Segment Dub (Actions)](https://app.segment.com/goto-my-workspac - + ## Example App diff --git a/conversions/leads/supabase.mdx b/conversions/leads/supabase.mdx index 01e78339..93333106 100644 --- a/conversions/leads/supabase.mdx +++ b/conversions/leads/supabase.mdx @@ -7,7 +7,7 @@ description: "Learn how to track lead conversion events with Supabase and Dub" import LeadsIntro from "/snippets/leads-intro.mdx"; import ConversionTrackingPrerequisites from "/snippets/conversion-tracking-prerequisites.mdx"; -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; import LeadsOutro from "/snippets/leads-outro.mdx"; @@ -137,7 +137,7 @@ export default async function handler( - + ## Example App diff --git a/snippets/client-side-lead-tracking.mdx b/snippets/client-side-lead-tracking.mdx index 0b3eb062..6df8e920 100644 --- a/snippets/client-side-lead-tracking.mdx +++ b/snippets/client-side-lead-tracking.mdx @@ -1,4 +1,4 @@ -import LeadsAttributes from "/snippets/leads-attributes.mdx"; +import LeadAttributes from "/snippets/lead-attributes.mdx"; Once the analytics script is installed, you can start tracking lead events in your application on the client-side. @@ -85,7 +85,7 @@ export function SignUpForm() { - + **When to track leads** diff --git a/snippets/dub-client-mobile-install.mdx b/snippets/dub-client-mobile-install.mdx index dd4c2189..c6b44bad 100644 --- a/snippets/dub-client-mobile-install.mdx +++ b/snippets/dub-client-mobile-install.mdx @@ -1,24 +1,29 @@ +import LeadAttributes from "/snippets/lead-attributes.mdx"; +import SaleAttributes from "/snippets/sale-attributes.mdx"; + Before installing, ensure your environment meets these minimum requirements: - **Build Tools:** - - Xcode 16+ - - Swift 6+ +**Build Tools:** - **Platforms:** - - iOS 16.0+ - - macOS 10.13 (Ventura)+ +- Xcode 16+ +- Swift 6+ + +**Platforms:** + +- iOS 16.0+ +- macOS 10.13 (Ventura)+ + +The Dub iOS SDK can be installed using the [Swift Package Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/). + +In Xcode, select **File** > **Add Package Dependencies** and add `https://github.com/dubinc/dub-ios` as the repository URL. Select the latest version of the SDK from the [release page](https://github.com/dubinc/dub-ios/releases). - The Dub iOS SDK can be installed using the [Swift Package Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/). - - In Xcode, select **File** > **Add Package Dependencies** and add `https://github.com/dubinc/dub-ios` as the repository URL. Select the latest version of the SDK from the [release page](https://github.com/dubinc/dub-ios/releases). - - You must call `Dub.setup` with your publishable key and domain prior to being able to use the `dub` instance. +You must call `Dub.setup` with your publishable key and domain prior to being able to use the `dub` instance. @@ -46,18 +51,19 @@ struct DubApp: App { } } ``` - + + - + Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events. The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then again with the `deepLink` parameter whenever the app is opened from a deep link. -```swift iOS (SwiftUI) +```swift iOS (SwiftUI) expandable // ContentView.swift import SwiftUI import Dub @@ -108,13 +114,13 @@ struct ContentView: View { - + - To track lead events, call `trackLead` on the `dub` instance with your customer's external ID, name, and email. Learn more about the [lead event attributes](/conversions/leads/introduction#lead-event-attributes). +To track lead events, call `trackLead` on the `dub` instance with your customer's external ID, name, and email. -```swift iOS (SwiftUI) +```swift iOS (SwiftUI) expandable // ContentView.swift import SwiftUI import Dub @@ -147,64 +153,71 @@ struct ContentView: View { ``` + + + + + - + - To track sale events, call `trackSale` on the `dub` instance with your customer's user ID and purchase information. Learn more about the [sale event attributes](/conversions/sales/introduction#sale-event-attributes). + To track sale events, call `trackSale` on the `dub` instance with your customer's user ID and purchase information. - ```swift iOS (SwiftUI) +```swift iOS (SwiftUI) expandable // ContentView.swift import SwiftUI import Dub struct ContentView: View { - @Environment(\.dub) var dub: Dub - - var body: some View { - // ... your app content ... - } - - private func trackSale( - customerExternalId: String, - amount: Int, - currency: String = "usd", - eventName: String? = "Purchase", - paymentProcessor: PaymentProcessor = .custom, - invoiceId: String? = nil, - metadata: Metadata? = nil, - leadEventName: String? = nil, - customerName: String? = nil, - customerEmail: String? = nil, - customerAvatar: String? = nil - ) { - Task { - do { - let response = try await dub.trackSale( - customerExternalId: customerExternalId, - amount: amount, - currency: currency, - eventName: eventName, - paymentProcessor: paymentProcessor, - invoiceId: invoiceId, - metadata: metadata, - leadEventName: leadEventName, - customerName: customerName, - customerEmail: customerEmail, - customerAvatar: customerAvatar - ) - - print(response) - } catch let error as DubError { - print(error.localizedDescription) - } - } - } + @Environment(\.dub) var dub: Dub + + var body: some View { + // ... your app content ... + } + + private func trackSale( + customerExternalId: String, + amount: Int, + currency: String = "usd", + eventName: String? = "Purchase", + paymentProcessor: PaymentProcessor = .custom, + invoiceId: String? = nil, + metadata: Metadata? = nil, + leadEventName: String? = nil, + customerName: String? = nil, + customerEmail: String? = nil, + customerAvatar: String? = nil + ) { + Task { + do { + let response = try await dub.trackSale( + customerExternalId: customerExternalId, + amount: amount, + currency: currency, + eventName: eventName, + paymentProcessor: paymentProcessor, + invoiceId: invoiceId, + metadata: metadata, + leadEventName: leadEventName, + customerName: customerName, + customerEmail: customerEmail, + customerAvatar: customerAvatar + ) + + print(response) + } catch let error as DubError { + print(error.localizedDescription) + } + } + } } ``` - + + + diff --git a/snippets/leads-attributes.mdx b/snippets/lead-attributes.mdx similarity index 100% rename from snippets/leads-attributes.mdx rename to snippets/lead-attributes.mdx From c819902dd311d2e0c4168087fe1288c943e043e1 Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 16:33:23 -0700 Subject: [PATCH 10/13] finalize docs --- api-reference/publishable-keys.mdx | 6 +- concepts/deep-links/attribution.mdx | 66 +++++++++---------- concepts/deep-links/quickstart.mdx | 3 +- partners/quickstart.mdx | 6 +- .../google-tag-manager.mdx | 2 +- sdks/client-side/introduction.mdx | 4 +- sdks/client-side/variants.mdx | 2 +- .../client-side-click-tracking-addendum.mdx | 4 +- snippets/dub-analytics-install.mdx | 4 +- snippets/steps/generate-publishable-key.mdx | 2 +- 10 files changed, 46 insertions(+), 53 deletions(-) diff --git a/api-reference/publishable-keys.mdx b/api-reference/publishable-keys.mdx index 590c8903..bc942336 100644 --- a/api-reference/publishable-keys.mdx +++ b/api-reference/publishable-keys.mdx @@ -6,8 +6,8 @@ description: "Learn how publishable keys work on Dub." import GeneratePublishableKeyStep from "/snippets/steps/generate-publishable-key.mdx"; import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; -Publishable keys on Dub allow you to safely embed authentication in client-side applications. -These keys are specifically designed to be used with Dub's client-side SDKs for features like conversion tracking. +Publishable keys on Dub allow you to safely embed authentication in client-side applications. +These keys are specifically designed to be used with [Dub's client-side SDKs](/sdks/client-side/introduction) for features like [conversion tracking](/sdks/client-side/features/conversion-tracking). Unlike [API keys](/api-reference/api-keys) which must be kept secret, publishable keys can be safely exposed in your frontend code since they have limited capabilities. @@ -29,4 +29,4 @@ You can create a publishable key by following these steps: You can now use your publishable key to authenticate client-side requests in your application. Usage will depend on the client-side SDK you are using. - \ No newline at end of file + diff --git a/concepts/deep-links/attribution.mdx b/concepts/deep-links/attribution.mdx index 6f7272ff..027faac2 100644 --- a/concepts/deep-links/attribution.mdx +++ b/concepts/deep-links/attribution.mdx @@ -4,6 +4,9 @@ og:title: "How to set up deep link attribution with Dub" description: "Learn how to use deep link attribution to track conversions events with Dub." --- +import EnableConversionTracking from "/snippets/enable-conversion-tracking.mdx"; +import GeneratePublishableKeyStep from "/snippets/steps/generate-publishable-key.mdx"; +import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; import InstallationGuides from "/snippets/dub-client-mobile-installation-guides.mdx"; import InstallIosSdkStep from "/snippets/steps/install-ios-sdk.mdx"; import InitializeIosSdkStep from "/snippets/steps/initialize-ios-sdk.mdx"; @@ -16,11 +19,6 @@ import ViewConversions from "/snippets/view-conversions.mdx"; Dub's powerful [attribution platform](https://dub.co/analytics) lets you understand how well your deep links are translating to actual users and revenue dollars inside your app. - - This feature is currently only available for iOS (Swift). React Native and Android support are coming soon. If you'd like early access, please [contact - us](https://dub.co/contact/support). - - + + This feature is currently only available for iOS (Swift). React Native and + Android support are coming soon. If you'd like early access, please [contact + us](https://dub.co/contact/support). + ## Prerequisites -Before you get started, make sure you have the following: + -1. Obtain your [publishable key](/api-reference/publishable-keys) (`DUB_PUBLISHABLE_KEY`) from your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and allowlist your site's domain (`DUB_DOMAIN`) to allow the client-side conversion events to be ingested by Dub. -2. [Enable conversion tracking for your links](/conversions/quickstart#step-1%3A-enable-conversion-tracking-for-your-links) +Then, you'll need generate a [publishable key](/api-reference/publishable-keys) from your Dub workspace to track conversions on the client-side. -In this guide, we'll walk you through the steps to get started tracking conversions through your deep links. +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. -1. [Install the client-side Mobile SDK](#step-1%3A-install-the-client-side-mobile-sdk) -2. [Track deep link and deferred deep link events](#step-2%3A-track-deep-link-and-deferred-deep-link-events) -3. [Track conversion events](#step-3%3A-track-conversion-events-in-your-app) -4. [View your conversions](#step-4%3A-view-your-conversions) + + Enabling conversion tracking for a workspace + + +Once these are set up, we can start tracking conversion events for your deep links. ## Step 1: Install the client-side Mobile SDK -Install the [Dub iOS SDK](/sdks/client-side-mobile/installation-guides/swift) and initialize it with your publishable key and domain. +Install the [Dub iOS SDK](/sdks/client-side-mobile/installation-guides/swift) and initialize it with your publishable key and short link domain. - + - + - -## Step 2: Track deep link and deferred deep link events +## Step 2: Track deep link open events Once the SDK has been initialized, you can start tracking deep link and deferred deep link events. -Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events. -The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then -again with the `deepLink` parameter whenever the app is opened from a deep link. +Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events. The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then again with the `deepLink` parameter whenever the app is opened from a deep link. -```swift iOS (SwiftUI) +```swift iOS (SwiftUI) expandable // ContentView.swift import SwiftUI import Dub @@ -120,10 +123,9 @@ struct ContentView: View { -If the deep link was successfully resolved and correlated to the original click, the `response` object will contain the destination URL, which you can use to navigate the user to the appropriate screen. -It will also contain the `clickId`, which the `dub` instance will persist internally. -If you wish to use [server-side conversion tracking](/conversions/quickstart#step-3%3A-install-the-dub-server-side-sdk-%2B-track-conversion-events) you will have to send the `clickId` to your server. -You may access it any time by calling the `clickId` property on the `dub` instance. +If the deep link was successfully resolved and correlated to the original click, the `response` object will contain the destination URL, which you can use to navigate the user to the appropriate screen. + +It will also contain the `clickId`, which the `dub` instance will persist internally. ## Step 3: Track conversion events @@ -131,7 +133,7 @@ You may track conversion events directly in your app with the `trackLead` and `t -```swift iOS (SwiftUI) +```swift iOS (SwiftUI) expandable // ContentView.swift import SwiftUI import Dub @@ -148,7 +150,7 @@ struct ContentView: View { Task { do { let response = try await dub.trackLead( - eventName: "User Sign Up", + eventName: "Sign Up", customerExternalId: customerExternalId, customerName: name, customerEmail: email @@ -166,10 +168,6 @@ struct ContentView: View { amount: Int, currency: String = "usd", eventName: String? = "Purchase", - paymentProcessor: PaymentProcessor = .custom, - invoiceId: String? = nil, - metadata: Metadata? = nil, - leadEventName: String? = nil, customerName: String? = nil, customerEmail: String? = nil, customerAvatar: String? = nil @@ -181,10 +179,6 @@ struct ContentView: View { amount: amount, currency: currency, eventName: eventName, - paymentProcessor: paymentProcessor, - invoiceId: invoiceId, - metadata: metadata, - leadEventName: leadEventName, customerName: customerName, customerEmail: customerEmail, customerAvatar: customerAvatar diff --git a/concepts/deep-links/quickstart.mdx b/concepts/deep-links/quickstart.mdx index ab517660..3e8efad7 100644 --- a/concepts/deep-links/quickstart.mdx +++ b/concepts/deep-links/quickstart.mdx @@ -186,7 +186,7 @@ When a user opens your app from a deep link, you need to handle two main scenari ### Scenario 1: User has your app installed -When your app is already installed, the deep link will open your app directly. +When your app is already installed, the deep link will open your app directly. You may handle the deep link manually or with the supported mobile SDKs. **Option 1**: Handle the deep link using a supported [Dub Mobile SDK](/sdks/client-side-mobile/introduction) (iOS only) @@ -257,7 +257,6 @@ func handleDeepLink(url: URL) { - **Option 2**: Handle the deep link manually diff --git a/partners/quickstart.mdx b/partners/quickstart.mdx index da7f8782..99ee324d 100644 --- a/partners/quickstart.mdx +++ b/partners/quickstart.mdx @@ -39,14 +39,14 @@ This script detects the `dub_id` query parameter and storing it as a first-party 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) +- lets you [track clicks on the client-side](/sdks/client-side/features/click-tracking) using query parameters (e.g. `?via=john`) +- [automatically fetch the partner and discount data](/sdks/client-side/features/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) -Once the script is installed, make sure to verify that [client-side click tracking](/sdks/client-side/features/client-side-click-tracking) is working as expected by checking if the following is true: +Once the script is installed, make sure to verify that [client-side click tracking](/sdks/client-side/features/click-tracking) is working as expected by checking if the following is true: diff --git a/sdks/client-side/installation-guides/google-tag-manager.mdx b/sdks/client-side/installation-guides/google-tag-manager.mdx index 37451a26..ae1e22f5 100644 --- a/sdks/client-side/installation-guides/google-tag-manager.mdx +++ b/sdks/client-side/installation-guides/google-tag-manager.mdx @@ -47,7 +47,7 @@ This guide will walk you through the process of integrating Dub Analytics with G - 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). + 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/click-tracking). ```js ``` -Read the [client-side click-tracking guide](/sdks/client-side/features/client-side-click-tracking) for more information. +Read the [client-side click-tracking guide](/sdks/client-side/features/click-tracking) for more information. diff --git a/snippets/dub-analytics-install.mdx b/snippets/dub-analytics-install.mdx index ea6455bd..d5385657 100644 --- a/snippets/dub-analytics-install.mdx +++ b/snippets/dub-analytics-install.mdx @@ -50,7 +50,7 @@ - If you're using [Dub Partners](/partners/quickstart) for affiliate management, you will also need to set up the `domainsConfig.refer` property to enable [client-side click-tracking](/sdks/client-side/features/client-side-click-tracking). + If you're using [Dub Partners](/partners/quickstart) for affiliate management, you will also need to set up the `domainsConfig.refer` property to enable [client-side click-tracking](/sdks/client-side/features/click-tracking). ```jsx app/layout.tsx import { Analytics as DubAnalytics } from '@dub/analytics/react'; @@ -71,7 +71,7 @@ } ``` - Read the [client-side click-tracking guide](/sdks/client-side/features/client-side-click-tracking) for more information. + Read the [client-side click-tracking guide](/sdks/client-side/features/click-tracking) for more information. diff --git a/snippets/steps/generate-publishable-key.mdx b/snippets/steps/generate-publishable-key.mdx index dbae8439..871de215 100644 --- a/snippets/steps/generate-publishable-key.mdx +++ b/snippets/steps/generate-publishable-key.mdx @@ -1,6 +1,6 @@ -Before you can track conversions on the client-side, you need to generate a publishable key from your Dub workspace. +Before you can track conversions on the client-side, you need to generate a [publishable key](/api-reference/publishable-keys) 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. From e5e6f1ba4b208452d8a5563f4212ed1e1083b4f0 Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 16:55:26 -0700 Subject: [PATCH 11/13] fix regressions --- api-reference/{api-keys.mdx => tokens.mdx} | 0 docs.json | 27 +++++----------------- 2 files changed, 6 insertions(+), 21 deletions(-) rename api-reference/{api-keys.mdx => tokens.mdx} (100%) diff --git a/api-reference/api-keys.mdx b/api-reference/tokens.mdx similarity index 100% rename from api-reference/api-keys.mdx rename to api-reference/tokens.mdx diff --git a/docs.json b/docs.json index f2d76a1d..57c7938d 100644 --- a/docs.json +++ b/docs.json @@ -9,14 +9,7 @@ }, "favicon": "/logos/favicon.png", "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "cursor", - "vscode" - ] + "options": ["copy", "view", "chatgpt", "claude", "cursor", "vscode"] }, "navigation": { "tabs": [ @@ -25,9 +18,7 @@ "groups": [ { "group": "Getting Started", - "pages": [ - "introduction" - ] + "pages": ["introduction"] }, { "group": "Links", @@ -106,10 +97,7 @@ }, { "group": "Dub Partners", - "pages": [ - "partners/quickstart", - "partners/embedded-referrals" - ] + "pages": ["partners/quickstart", "partners/embedded-referrals"] }, { "group": "Integrations", @@ -128,10 +116,7 @@ }, { "group": "Open source", - "pages": [ - "local-development", - "self-hosting" - ] + "pages": ["local-development", "self-hosting"] } ] }, @@ -142,7 +127,7 @@ "group": "Overview", "pages": [ "api-reference/introduction", - "api-reference/api-keys", + "api-reference/tokens", "api-reference/publishable-keys", "api-reference/rate-limits" ] @@ -502,4 +487,4 @@ "destination": "/api-reference/introduction#error-handling" } ] -} \ No newline at end of file +} From b5df04e46544b618708602db426187ce64c6eb9c Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 16:56:25 -0700 Subject: [PATCH 12/13] =?UTF-8?q?revert=20api-keys=20=E2=86=92=20tokens?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-reference/introduction.mdx | 4 ++-- api-reference/publishable-keys.mdx | 2 +- conversions/leads/google-tag-manager.mdx | 2 +- conversions/sales/google-tag-manager.mdx | 2 +- data-model.mdx | 2 +- integrations/quickstart.mdx | 4 ++-- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 44a79c2f..9e773e93 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -16,7 +16,7 @@ https://api.dub.co ## Authentication -Authentication to Dub's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word `Bearer` followed by your [API key](/api-reference/api-keys) in your requests like so: +Authentication to Dub's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word `Bearer` followed by your [API key](/api-reference/tokens) in your requests like so: ```bash Terminal Authorization: Bearer dub_xxxxxx @@ -87,7 +87,7 @@ $links = $client->links->list(); -Learn more about [how to get your API key](/api-reference/api-keys). +Learn more about [how to get your API key](/api-reference/tokens). ## Native SDKs diff --git a/api-reference/publishable-keys.mdx b/api-reference/publishable-keys.mdx index bc942336..48ee173c 100644 --- a/api-reference/publishable-keys.mdx +++ b/api-reference/publishable-keys.mdx @@ -9,7 +9,7 @@ import AllowlistDomainsStep from "/snippets/steps/allowlist-domains.mdx"; Publishable keys on Dub allow you to safely embed authentication in client-side applications. These keys are specifically designed to be used with [Dub's client-side SDKs](/sdks/client-side/introduction) for features like [conversion tracking](/sdks/client-side/features/conversion-tracking). -Unlike [API keys](/api-reference/api-keys) which must be kept secret, publishable keys can be safely exposed in your frontend code since they have limited capabilities. +Unlike [API keys](/api-reference/tokens) which must be kept secret, publishable keys can be safely exposed in your frontend code since they have limited capabilities. Publishable keys on Dub follow the format: diff --git a/conversions/leads/google-tag-manager.mdx b/conversions/leads/google-tag-manager.mdx index 4852c754..95f1ac44 100644 --- a/conversions/leads/google-tag-manager.mdx +++ b/conversions/leads/google-tag-manager.mdx @@ -179,7 +179,7 @@ This will open up the tag configuration page. Under **Tag Configuration**, selec Make sure your tag configuration is set to the following: -- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/api-keys) (starts with `dub_`) +- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`) - **Event**: Select "Track lead" from the dropdown - **Click ID**: `clickId` from the Dub Server Client event data - **Customer External ID**: `customerExternalId` from the event data diff --git a/conversions/sales/google-tag-manager.mdx b/conversions/sales/google-tag-manager.mdx index 092576cd..2edb9fc5 100644 --- a/conversions/sales/google-tag-manager.mdx +++ b/conversions/sales/google-tag-manager.mdx @@ -212,7 +212,7 @@ This will open up the tag configuration page. Under **Tag Configuration**, selec Make sure your tag configuration is set to the following: -- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/api-keys) (starts with `dub_`) +- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`) - **Event**: Select "Track sale" from the dropdown - **Customer External ID**: `customerExternalId` from the event data - **Amount**: `amount` from the event data (in cents) diff --git a/data-model.mdx b/data-model.mdx index cd7a148f..dbb76ef2 100644 --- a/data-model.mdx +++ b/data-model.mdx @@ -14,7 +14,7 @@ Within Dub, all data belongs to a [**Workspace**](#workspace). Within a workspac - [Tags](#tags) - [Domains](#domains) -When interacting with Dub's API, you'll also need to create a [workspace API key](/api-reference/api-keys) to authenticate your requests. +When interacting with Dub's API, you'll also need to create a [workspace API key](/api-reference/tokens) to authenticate your requests. ## Links diff --git a/integrations/quickstart.mdx b/integrations/quickstart.mdx index f8d61228..a7cffe8a 100644 --- a/integrations/quickstart.mdx +++ b/integrations/quickstart.mdx @@ -216,7 +216,7 @@ Dub supports the following scopes for OAuth 2.0: | `analytics.read` | Read access to analytics. | | `domains.read` | Read access to domains. | | `domains.write` | Write access to domains. | -| `folders.read` | Read access to folders. | +| `folders.read` | Read access to folders. | | `folders.write` | Write access to folders. | | `user.read` | Read access to user information. This scope is included by default. | @@ -237,4 +237,4 @@ Dub supports the following scopes for OAuth 2.0: Dub also supports API key authentication; however, it is **not recommended** for building integrations. It should only be used for internal integrations or personal projects that do not require user consent. -Learn more about [API Keys](/api-reference/api-keys). +Learn more about [API Keys](/api-reference/tokens). From a29d69dc5dd4996069dd305927aab7ab96f45343 Mon Sep 17 00:00:00 2001 From: Steven Tey Date: Mon, 22 Sep 2025 16:58:12 -0700 Subject: [PATCH 13/13] fix broken links --- conversions/leads/client-side.mdx | 2 +- conversions/sales/client-side.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/conversions/leads/client-side.mdx b/conversions/leads/client-side.mdx index 9c974815..9ad28e67 100644 --- a/conversions/leads/client-side.mdx +++ b/conversions/leads/client-side.mdx @@ -29,7 +29,7 @@ Client-Side Conversion Tracking Limitations: - **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](/docs/conversions/leads/introduction) +For more accurate conversion tracking, consider using [server-side conversion tracking](/conversions/leads/introduction) diff --git a/conversions/sales/client-side.mdx b/conversions/sales/client-side.mdx index f8a4094b..866eed76 100644 --- a/conversions/sales/client-side.mdx +++ b/conversions/sales/client-side.mdx @@ -31,7 +31,7 @@ Client-Side Conversion Tracking Limitations: - **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](/docs/conversions/sales/introduction) +For more accurate conversion tracking, consider using [server-side conversion tracking](/conversions/sales/introduction)