# 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]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/" >}}) 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-config >}}

## 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**.

{{< image src="images/event-stream-destinations/add-new-destination.webp" alt="Add new destination in RudderStack dashboard" >}}

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

| Setting | Description |
| :----| :-----|
| Name | Assign a name to uniquely identify the destination in RudderStack. |
| Connection mode | Device mode is selected by default, as this is a web device mode-only integration. |

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

| Setting | <div style="width:300px">Description</div>  |
| :----| :-----|
| Consent management settings | Configure the consent management settings for the specified source by choosing the **Consent management provider** from the dropdown and entering the relevant consent category IDs. <br /><br />See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) for more information on this feature. |
| Client-side Events Filtering | This setting lets you specify which `track` events should be blocked or allowed to flow through to the custom integration.<br /><br />See [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}) for more information. |

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

{{< image src="images/event-stream-destinations/custom-integrations/destination-id.webp" alt="Destination ID for Custom Device Mode destination" >}}

## 2. Add your custom integration to the JavaScript SDK

Use the [`addCustomIntegration` API]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md" >}}) to register your custom integration with the RudderStack JavaScript SDK. 

{{< info >}}
The `addCustomIntegration` API connects your custom code to the **Custom Device Mode** destination [set up in the RudderStack dashboard](#1-dashboard-setup).
{{< /info >}}

### Basic syntax

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

See the detailed [`addCustomIntegration`]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md" >}}) API reference for more information on the following:

- [Integration structure]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md#integration-structure" >}})
- [Function parameters]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md#function-parameters" >}})
- [Event data structure]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md#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.

{{< info >}}
Your implementation determines the [supported event types](#integration-structure) and how the integration handles them.
{{< /info >}}

### Initialize the third-party SDK

Use the [`init` function]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md#integration-structure" >}}) to load and configure your third-party SDK:

```javascript
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`]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md#integration-structure" >}}) is the only required function — it tells RudderStack when your integration is ready to receive events:

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

{{< warning >}}
If `isReady` doesn't return `true` within 11 seconds, RudderStack will time out and skip your integration.
{{< /warning >}}

### Handle events

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

```javascript
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

| Issue | Solution |
|-------|----------|
| Integration not initializing | Make sure to call `addCustomIntegration()` before `rudderanalytics.load()`. |
| Events not being sent | Check that `isReady` returns `true`. |
| Third-party SDK not loading | Verify the script URL and check for console errors. |
| Configuration not available | Ensure your destination is properly configured in the RudderStack dashboard. |

## See more

- [How to Implement Custom Web Device Mode Integrations]({{< ref "destinations/custom-web-device-mode-integrations/implement-custom-integration.md" >}})
- [JavaScript SDK Reference]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/" >}})
- [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}})
- [Consent Management]({{< ref "data-governance/consent-management/overview.md" >}})