Dub Cloud Mode Integration Beta

After you have successfully instrumented Dub as a destination in RudderStack, follow this guide to correctly send your events to Dub in cloud mode.

Business plan is required for conversion tracking

Dub’s conversion tracking feature requires a Business plan or higher. The Free, Pro, and Starter plans do not support conversion attribution.

How to use the integration

This section gives an overview of how to use the Dub cloud mode integration with RudderStack:

1. Dashboard setup: Set up the Dub destination in RudderStack.
2. Initialize the Dub client on your website: Add the @dub/analytics script to your website client on your website before initializing the RudderStack SDK.

• See the Dub documentation for more information on how to initialize the Dub script.

3. Initialize the RudderStack SDK: Initialize the RudderStack SDK after initializing the Dub client. While setting up the SDK, retrieve the clickId value from the cookies and use it to instrument your track events.

• See the Property mappings section for more information on how clickId property is mapped.

Track

The track call sends conversion events to Dub for attribution tracking. Use these events to:

• Track conversions back to specific campaign clicks
• Measure campaign performance and ROI
• Attribute sales and leads to marketing channels

A sample track call is shown below:

rudderanalytics.track('User Signed Up', {
    userId: 'abc123',
    firstName: 'John',
    lastName: 'Doe',
    customerAvatar: 'https://example.com/avatar.jpg'
  }, {
    dubClickId: 'ABC123',
    traits: {
      email: 'xyz@example.com'
    }
  }
);

rudderanalytics.track('Order Completed', {
  order_id: 'order_123',
  invoiceId: 'invoice_123',
  amount: 100,
  products: {
    product_id: 'prod_123',
    sku: 'sku_123',
    name: 'Product Name',
    quantity: 1
  },
  currency: 'USD',
  paymentProcessor: 'stripe'
});

RudderStack processes only events that have a valid clickId and are mapped to Dub conversion events in the dashboard settings before successfully sending them to Dub.

Events without a clickId or not configured in the event mapping will fail.

Mapping setup

Before sending track events, make sure to configure event mappings in your Dub destination settings to map RudderStack events to Dub conversion types.

An example is shown below — you can add these mappings based on your requirement:

Property mappings

This section explains the property mappings for the Lead and Sale conversion events.

Lead event

A Lead event occurs when a user performs an action that is not related to a revenue-generating conversion. For example, a user signing up for an account, adding a product to the cart, etc.

RudderStack maps the following properties in the track events (mapped to the LEAD_CONVERSION event in the dashboard settings) to the corresponding Dub fields:

RudderStack sets the mode to wait for the lead event.

See the Dub documentation for more information on this mode.

RudderStack discards any other fields in the traits object apart from the ones listed above.

Sale event

A Sale event occurs when a user performs an action that is related to a revenue-generating conversion. For example, subscribing to a paid plan, upgrading from one plan to another, etc.

RudderStack maps the following properties in the track events (mapped to the SALES_CONVERSION event in the dashboard settings) to the corresponding Dub fields:

RudderStack discards any other fields in the traits object apart from the ones listed above.

User identification

RudderStack sets the following hierarchy for identifying a user in Dub:

1. context.externalId with type customerExternalId
2. userId field from the event

RudderStack throws an instrumentation error if no customer identifier is found.

Custom properties

RudderStack automatically includes any additional properties from your track event as metadata in Dub:

rudderanalytics.track("Purchase Completed", {
  clickId: "clk_abc123def456",
  revenue: 149.99,
  currency: "USD",
  product_category: "Electronics",
  discount_code: "SAVE20",
  customer_segment: "Premium",
  campaign_source: "email_newsletter"
});

Event processing flow

When you send a track event, RudderStack:

1. Validates the required fields: Ensures clickId, revenue, and currency are present
2. Checks event mapping: Verifies the event name is configured in the destination mapping
3. Maps event data: Converts RudderStack format to Dub’s conversion event format
4. Handles amount conversion: Multiplies revenue by 100 if the Convert amount to cents setting is enabled
5. Sends the conversion event: Uses Dub’s conversion attribution API

RudderStack does not send the events if any validation fails. These events may appear as a failed event in your destination.

Rate limits

Dub enforces rate limits that vary by subscription plan:

If rate limits are exceeded, Dub returns a 429 Too Many Requests error. RudderStack automatically handles these errors with exponential backoff retry logic.

Event ordering

Dub requires strict event ordering for proper conversion attribution — the mandatory flow is Click > Lead > Sale. If events are processed out of order (for example, sale before lead), the conversion attribution chain will be broken and events may not be properly tracked.

RudderStack automatically handles this ordering requirement.

Error handling

This section covers common error scenarios and how RudderStack handles them:

Troubleshooting

Best practices

This section includes some best practices for correctly using the Dub integration with RudderStack.

Event naming

Use consistent, descriptive event names in your mappings:

// Good: Clear and specific
rudderanalytics.track("product_purchase_completed", {...});
rudderanalytics.track("demo_request_submitted", {...});
rudderanalytics.track("trial_signup_completed", {...});

// Avoid: Generic or unclear
rudderanalytics.track("event", {...});
rudderanalytics.track("action", {...});

Attribution timing

For accurate attribution, send conversion events as soon as possible after the conversion occurs. Delaying conversion tracking can impact attribution accuracy:

// Send conversion event immediately after purchase
rudderanalytics.track("Purchase Completed", {
  clickId: processedPurchase.clickId,
  revenue: processedPurchase.amount,
  currency: processPayment.currency
});

Metadata structure

Organize your conversion metadata in a logical structure:

rudderanalytics.track("Purchase Completed", {
  clickId: "clk_abc123def456",
  revenue: 99.99,
  currency: "USD",
  
  // Product information
  product_id: "prod_456",
  product_name: "Premium Plan",
  product_category: "SaaS Subscription",
  
  // Customer information
  customer_segment: "enterprise",
  customer_type: "existing",
  
  // Campaign data
  campaign_type: "email",
  campaign_name: "monthly_newsletter",
  utm_source: "email",
  utm_medium: "newsletter",
  utm_campaign: "product_launch"
});

See also

See the following Dub API documentation for more information:

• Dub API Overview
• Track Lead API
• Track Sale API
• API Authentication
• Error Handling