> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/analytics/singular.md).

# Singular

Step-by-step guide to send your event data from RudderStack to Singular

[Singular](https://www.singular.net/) is a marketing intelligence platform to transform your marketing data into accurate, granular, and actionable insights that drive growth.

RudderStack supports Singular as a destination to which you can seamlessly send your event data.

## Getting started

Before configuring Singular as a destination in RudderStack, verify if the source platform is supported by Singular, by referring to the table below:

| **Connection Mode** | **Web** | **Mobile**    | **Server** |
| ------------------- | ------- | ------------- | ---------- |
| **Device mode**     | -       | **Supported** | -          |
| **Cloud mode**      | -       | -             | -          |

To know more about the difference between cloud mode and device mode in RudderStack, refer to the [RudderStack Connection Modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

Once you have confirmed that the source platform supports sending events to Singular, follow these steps:

1. From your [RudderStack dashboard](https://app.rudderstack.com/), add the source. Then, from the list of destinations, select **Singular**.
2. Assign a name to your destination and click on **Next**.

### Connection settings

To successfully configure Singular as a destination, you need to configure the following settings:

![Singular connection settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-5bd13c00670a35f832f016188231495ddfa92096%2Fsingular-connection-settings.png?alt=media)

* **API Key**: Enter your Singular API key here. This is a mandatory field.
* **Secret**: Enter your Singular secret. This is a mandatory field and is required for the device mode integrations with the RudderStack iOS and Android SDKs.

For more information on obtaining the Singular API key and secret, refer to the [FAQ](#faq) section below.

When sending events via the device mode, RudderStack also lets you specify which events should be discarded or allowed to flow through. For more information, refer to the [Client-side Event Filtering](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/event-filtering/).

## Adding device mode integration

To add Singular to your application, follow the steps below depending on your platform of integration.

iOS Android React Native Cordova To add Singular to your iOS app, follow these steps:

1. In your `Podfile`, add the following dependencies:

   ```ruby
   pod 'Singular-SDK', '11.0.4'
   pod 'Rudder-Singular', '1.0.0'
   ```
2. After adding the dependencies followed by `pod install` command, add the following imports to your `AppDelegate.m` file:

   ```objectivec
   #import <Rudder/Rudder.h>
   #import <RudderSingularFactory.h>
   ```
3. Then, initialize your `RSClient`, as shown:

   ```objectivec
   RSConfigBuilder *configBuilder = [[RSConfigBuilder alloc] init];
   [configBuilder withDataPlaneUrl:<DATA_PLANE_URL>];
   [configBuilder withFactory:[RudderSingularFactory instance]];
   RSClient *rudderClient = [RSClient getInstance:<WRITE_KEY> config:[configBuilder build]];
   ```
4. For more information, refer to the [Singular iOS documentation](https://support.singular.net/hc/en-us/articles/360037950591-iOS-SDK-Basic-Integration?navigation_side_bar=true).

To add Singular to your Android app, follow these steps :

1. Open your `app/build.gradle` (Module: `app`) file, and add the following under the `dependencies` section :

   ```groovy
   implementation 'com.rudderstack.android.sdk:core:[1.0,2.0)'
   implementation 'com.rudderstack.android.integration:singular:1.0.0'
   implementation 'com.google.code.gson:gson:2.8.6'
   ```
2. Then, add the Singular Maven plugin to your build script. To do this, add the following snippet into the `Gradle Scripts` section of your root `build.gradle`:

   ```groovy
   buildscript {
       repositories {
           google()
           mavenCentral()
           maven {
             url 'https://maven.singular.net/' 
           }
       }
       dependencies {
           classpath 'com.android.tools.build:gradle:7.1.2'
           classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
       }
   }
   allprojects {
       repositories {
           google()
           mavenCentral()
           maven {
             url 'https://maven.singular.net/' 
           }
       }
   }
   ```
3. Add the following permissions(if not present already) to your `AndroidManifest.xml`:

   ```markup
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   ```
4. Finally, initialize the RudderStack SDK in your `Application` class' `onCreate()` method, as shown:

   ```kotlin
   // initializing Rudder SDK
   val rudderClient = RudderClient.getInstance(
     this,
     <WRITE_KEY>,
     RudderConfig.Builder()
             .withDataPlaneUrl(<DATA_PLANE_URL>)
             .withFactory(SingularIntegrationFactory.FACTORY)
             .build()
     )
   ```
5. For more information, refer to the [Singular Android documentation](https://support.singular.net/hc/en-us/articles/360037581952-Android-SDK-Basic-Integration?navigation_side_bar=true).

To add Singular to your React Native app, follow these steps:

1. Add the RudderStack-Singular module to your app by running the following command:

   ```bash
   npm install @rudderstack/rudder-integration-singular-react-native
   // OR //
   yarn add @rudderstack/rudder-integration-singular-react-native
   ```
2. Open your project-level `android/build.gradle` file and add the following snippet:

   ```groovy
   repositories {
     maven {
       url "https://maven.singular.net/"
     }
   }
   ```
3. Then, import the above module and add it to your SDK initialization, as shown:

   ```typescript
   import rudderClient from "@rudderstack/rudder-sdk-react-native"
   import singular from "@rudderstack/rudder-integration-singular-react-native"
   const config = {
   	dataPlaneUrl: <DATA_PLANE_URL>,
   	trackAppLifecycleEvents: true,
   	withFactories: [singular],
   }
   rudderClient.setup(<WRITE_KEY>, config)
   ```

To add Singular to your Cordova app, follow these steps:

1. Navigate to the root folder of your application and run the following command:

   ```bash
   cordova plugin add rudder-integration-singular-cordova
   ```
2. Then, add the following code in the `onDeviceReady()` function of your app's home page to initialize the SDK, as shown:

   ```javascript
   RudderClient.initialize(<WRITE_KEY>, {
     dataPlaneUrl: <DATA_PLANE_URL>,
     factories: [RudderSingularFactory]
   })
   ```
3. Make sure you use the `await` keyword with the `initialize` call.

## Implementing SKAdNetwork (SKAN) support

Add the following code before the initialization of the iOS SDK to give the control to Singular for your SKAdNetwork integration:

```objectivec
[RudderSingularIntegration setSKANOptions:YES
        isManualSkanConversionManagementMode:YES
withWaitForTrackingAuthorizationWithTimeoutInterval:@0
        withConversionValueUpdatedHandler:^(NSInteger conversionValue){
    // Receive a callback whenever the Conversion Value is updated
    NSLog(@"SKAN handler %ld",conversionValue);
}];
```

For more details, refer to the [iOS SDK: Adding SKAdNetwork Support](https://support.singular.net/hc/en-us/articles/360047454611) section of the Singular documentation.

## Identify

For device mode destinations, the Singular SDK uses the [`identify`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/identify/) method to map the RudderStack user ID to their custom user ID. RudderStack uses Singular's [`setCustomUserId`](https://support.singular.net/hc/en-us/articles/360037581952-Android-SDK-Basic-Integration#Optional_Setting_the_User_ID) method to forward the identified user ID to Singular.

A sample `identify` call for both the Android and iOS SDKs is shown below:

iOS Android

```objectivec
[[RSClient getInstance] identify:@"1hKOmRA4el9Zt1WSfVJIVo4GRlm"];
```

```kotlin
RudderClient.getInstance()?.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm")
```

## Track

The [`track`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/track/) call lets you capture any user actions and the properties associated with them. Each user action is considered to be an event.

### Tracking custom events

A custom `track` call lets you track custom events as they occur in your apps. RudderStack sends these calls to Singular where they are processed as custom post-install events and are made available in the relevant reports.

A sample custom `track` call for both the Android and iOS SDKs is shown below:

iOS Android

```objectivec
[[RSClient getInstance] track:@"Product Reviewed" properties:@{
        @"product_id" : @"345676543",
        @"review_id" : @"123454387"
    }];
```

```kotlin
RudderClient.getInstance()?.track("Product Reviewed",
    RudderProperty()
        .putValue("product_id", "345676543")
        .putValue("review_id", "123454387")
)
```

### Tracking revenue

Singular supports tracking revenue events. It implements revenue tracking whenever an event containing the `revenue` property is sent(including a zero value). Optionally, you can also pass the `currency` field as an [ISO code](https://www.iso.org/iso-4217-currency-codes.html).

The default currency is set to `USD`.

A sample `revenue` track call is shown below:

iOS Android

```objectivec
[[RSClient getInstance] track:@"Order Completed" properties:@{
        @"revenue" : @1251,
        @"currency" : @"INR"
    }];
```

```kotlin
RudderClient.getInstance()?.track("Order Completed",
    RudderProperty()
        .putValue("revenue", 1251)
        .putValue("currency", "INR")
)
```

## Screen

The [`screen`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/screen/) method allows you to record whenever a user sees the mobile screen, along with any associated optional properties. This call is similar to the `page` call for the web applications but exclusive to your mobile device.

A sample `screen` call for both the Android and iOS SDKs is shown below:

iOS Android

```objectivec
[[RSClient sharedInstance] screen:@"Home" properties:@{
    @"category" : @"launcher"
}];
```

```kotlin
RudderClient.getInstance()?.screen("Home",
    RudderProperty()
        .putValue("category", "launcher")
)
```

In the above snippet, RudderStack captures all the information related to the viewed screen, along with any additional info about the screen.

RudderStack sends the `screen` event to Singular as a custom event.

## Reset

The `reset` method resets the current user's identity and creates a new anonymous session. It should be called when a user logs out.

RudderStack calls Singular's [`unsetCustomUserId`](https://support.singular.net/hc/en-us/articles/360037581952-Android-SDK-Basic-Integration#Optional_Setting_the_User_ID) method to reset a user's identity.

A sample `reset` call for both the Android and iOS SDKs is shown below:

iOS Android

```objectivec
[[RSClient getInstance] reset];
```

```kotlin
RudderClient.getInstance()?.reset();
```

## FAQ

### Where can I find the Singular API key and secret?

To obtain your Singular API key and secret, log into your Singular dashboard and navigate to **Settings** > **SDK Keys**, as shown:

![Singular API key](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-c144afbbe758a54a18ef44293fc32a0cf051e34f%2Fsingular-api-key.png?alt=media)

## Contact us

For queries on any of the sections covered in this guide, you can [contact us](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.