How to Create Custom Web Device Mode Integrations

This guide lists the steps to set up a custom web device mode destination in RudderStack and the necessary SDK configuration required to send events correctly.

Prerequisites

Before you start creating custom device mode integrations, make sure you have:

• A JavaScript source set up in your RudderStack workspace and integrated with your website
• Access to your third-party tool’s API, documentation, and SDK

Connection compatibility

Destination Information
Status: Generally Available Supported sources: Web Refer to it as Custom Device Mode in the Integrations object.

Connection Modes
Source	Cloud mode	Device mode	Hybrid mode
Web

Supported Message Types
Source	Identify	Page	Track	Screen	Group	Alias	Record	AudienceList
Device mode
Web

1. Dashboard setup

Create a custom device mode destination in your RudderStack dashboard by following these steps:

1. Navigate to the JavaScript source set up in your RudderStack dashboard.
2. In the Overview tab, click Add Destination > Create new destination.

3. Select Custom Device Mode from the list of destinations and click Continue.
4. Configure the following settings:

5. Configure the other optional settings as per your requirements:

6. Save your destination and note the Destination ID — you will need this for the JavaScript SDK integration.

2. Add your custom integration to the JavaScript SDK

Use the addCustomIntegration API to register your custom integration with the RudderStack JavaScript SDK.

The addCustomIntegration API connects your custom code to the Custom Device Mode destination set up in the RudderStack dashboard.

Basic syntax

rudderanalytics.addCustomIntegration('<destination_id>', {
  // Your integration implementation
});

See the detailed addCustomIntegration API reference for more information on the following:

• Integration structure
• Function parameters
• Event data structure

3. Implement the integration functions

This section covers the functions you need to implement to correctly create your custom web device mode integration.

Your implementation determines the supported event types and how the integration handles them.

Initialize the third-party SDK

Use the init function to load and configure your third-party SDK:

init: (destinationConfig, analytics, logger) => {
  logger.debug('Loading third-party SDK');
  
  // Dynamically load the SDK script
  const script = document.createElement('script');
  script.src = 'https://cdn.your-sdk.com/sdk.js';
  script.onload = () => {
    // Initialize the SDK once loaded
    window.YourSDK.init({
      apiKey: destinationConfig.apiKey,
      // Add other configuration options
    });
  };
  document.head.appendChild(script);
}

Check integration readiness

Note that isReady is the only required function — it tells RudderStack when your integration is ready to receive events:

isReady: (analytics, logger) => {
  // Check if your third-party SDK is loaded and initialized
  return window.YourSDK && window.YourSDK.initialized === true;
}

If isReady doesn’t return true within 11 seconds, RudderStack will time out and skip your integration.

Handle events

Make sure to implement only the event types your integration supports:

track: (analytics, logger, rsEvent) => {
  try {
    // Extract event data
    const eventName = rsEvent.message.event;
    const properties = rsEvent.message.properties;
    
    // Send to your third-party tool
    window.YourSDK.track(eventName, properties);
    
    logger.debug('Track event sent successfully');
  } catch (error) {
    logger.error('Failed to send track event:', error);
  }
}

4. Test the integration

After implementing your custom integration, verify it works correctly by following these steps:

1. Open your browser’s developer console.
2. Look for any debug messages (after configuring the required log levels in the JavaScript SDK) from your integration.
3. Check that events are being sent to your tool.
4. Test different event types (track, page, identify) to ensure they’re handled properly.

Troubleshooting

See more

• How to Implement Custom Web Device Mode Integrations
• JavaScript SDK Reference
• Client-side Events Filtering
• Consent Management