# RudderStack-Singular Integration Setup Approaches


This guide explains the different approaches for setting up the Singular integration with RudderStack. It also provides recommendations to help you select the most suitable configuration.

## Setup overview

The following table summarizes the available integration setup approaches to help you identify the right one for your use case:

| Aspect | [Singular SDK + cloud mode](#1-singular-sdk-with-rudderstack-cloud-mode) | [RudderStack cloud mode only](#2-rudderstack-cloud-mode-only-no-singular-sdk) | [RudderStack device mode](#3-rudderstack-device-mode) |
| :---- | :---- | :---- | :---- |
| Singular SDK usage | Initialized separately, outside of RudderStack | Not used | Wrapped and initialized by RudderStack |
| Session management | Singular SDK (automatic) — you must **NOT** configure the **Session Event Name** [connection setting]({{< ref "destinations/streaming-destinations/singular/setup-guide.md#connection-settings" >}}) | Self-managed — you must configure the **Session Event Name** [connection setting]({{< ref "destinations/streaming-destinations/singular/setup-guide.md#connection-settings" >}}) | Singular SDK (automatic) |
| Identifier used | Singular device ID (SDID), if available in the events. Otherwise, platform-specific identifiers | Singular device ID (SDID), if available in the events. Otherwise, platform-specific identifiers | Singular SDK manages this internally |
| Best for | Using Singular SDK for session tracking while sending events via RudderStack | Sending all events (including sessions) through RudderStack  | Letting the Singular SDK handle all event tracking automatically |

The following flowchart summarizes all the integration setup approaches covered in this guide and helps you choose the most suitable approach for your use case:

{{< image src="images/event-stream-destinations/singular/integration-setup-approaches.webp" >}}

## 1. Singular SDK with RudderStack cloud mode

In this approach, you initialize the Singular SDK separately (outside of RudderStack) in your app. The Singular SDK manages session tracking automatically.

{{< warning >}}
**Important consideration**

- Do not configure the **Session Event Name** in the [connection settings]({{< ref "destinations/streaming-destinations/singular/setup-guide.md#connection-settings" >}}) while setting up the Singular destination in RudderStack. As the Singular SDK already manages session events, configuring this setting will result in duplicate session events.
- Do not explicitly send the following events via RudderStack:

    - `Application Installed`
    - `Application Opened`
    - `Application Updated`
{{< /warning >}}

You then send all other events to Singular via RudderStack in [cloud mode]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md" >}}) (either from the client-side or the server-side SDKs). The identifier you choose determines which Singular API version RudderStack uses:

{{< details "**Singular device ID (SDID)**" >}}
<br />

- The Singular SDK generates the [Singular Device ID (SDID)](https://support.singular.net/hc/en-us/articles/4411780525979-Types-of-Device-IDs)
- [Pass the Singular device ID (SDID)]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md#pass-singular-device-id" >}}) in all [custom events]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md#custom-events" >}}) instrumented with RudderStack
- RudderStack uses [Singular's API v2](https://support.singular.net/hc/en-us/articles/31496864868635-Server-to-Server-EVENT-Endpoint-API-Reference#API_Endpoint_Selection) and ignores any platform-specific identifiers like `idfa`, `andi`, `idfv`, and `aifa` present in the event properties

{{< /details >}}

{{< details "**Platform-specific identifiers**" >}}
<br />

- RudderStack's SDKs automatically retrieve platform-specific device identifiers (like `idfa`, `andi`, `idfv`, and `aifa`) and pass them in all events
- RudderStack uses [Singular's API v1](https://support.singular.net/hc/en-us/articles/31496864868635-Server-to-Server-EVENT-Endpoint-API-Reference#API_Endpoint_Selection) to send the events
{{< /details >}}

## 2. RudderStack cloud mode only (no Singular SDK)

In this approach, you don't use the Singular SDK at all. All events (including session events) are sent to Singular via RudderStack in [cloud mode]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md" >}}).

{{< warning >}}
**Important consideration**

Since the Singular SDK is not managing sessions, you must configure the **Session Event Name** in the [connection settings]({{< ref "destinations/streaming-destinations/singular/setup-guide.md#connection-settings" >}}) so RudderStack can send session events to Singular on your behalf.
{{< /warning >}}

The identifier you choose determines which Singular API version RudderStack uses:

{{< details "**Singular device ID (SDID)**" >}}
<br />

- **It is your responsibility** to maintain a  Singular device ID (SDID)([client-generated UUIDv4](https://support.singular.net/hc/en-us/articles/31496864868635-Server-to-Server-EVENT-Endpoint-API-Reference#V2_Endpoint_Identifiers)) for the lifetime of the app install
- [Pass the Singular device ID (SDID)]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md#pass-singular-device-id" >}}) in all [custom events]({{< ref "destinations/streaming-destinations/singular/cloud-mode.md#custom-events" >}}) instrumented via RudderStack
- RudderStack uses [Singular's API v2](https://support.singular.net/hc/en-us/articles/31496864868635-Server-to-Server-EVENT-Endpoint-API-Reference#API_Endpoint_Selection) and ignores any platform-specific identifiers like `idfa`, `andi`, `idfv`, and `aifa` present in the event properties

{{< /details >}}

{{< details "**Platform-specific identifiers**" >}}
<br />

- RudderStack's SDKs automatically retrieve platform-specific device identifiers (like `idfa`, `andi`, `idfv`, and `aifa`)
- All events (including session events) are sent to Singular with these identifiers
- RudderStack uses [Singular's API v1](https://support.singular.net/hc/en-us/articles/31496864868635-Server-to-Server-EVENT-Endpoint-API-Reference#API_Endpoint_Selection) to send the events
{{< /details >}}

## 3. RudderStack device mode

When sending events to Singular in [device mode]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}}), RudderStack automatically wraps and initializes the Singular SDK.

The Singular SDK manages device identification and event tracking internally — so no session events are sent via RudderStack.

## Next steps

See the [Singular Destination Setup Guide]({{< ref "destinations/streaming-destinations/singular/setup-guide.md" >}}) for more information on setting up the Singular destination in RudderStack