Segment - Singular Destination (Device-Mode)

Segment is a customer data infrastructure (CDI) platform that helps businesses collect, clean, and route their customer data to various destinations. Similar to mParticle, Segment provides a single API to collect data from multiple sources, including websites, mobile apps, servers, and cloud services.

The Singular SDK is available as a plug-in for Segment, referred to as a "Device-Mode" Destination. The instructions below illustrate how to add the Singular Destination in Segment.

Guide for Engineering Teams
Prerequisites This article assumes you already have the Segment iOS or Android Analytics SDK integrated in your app.

To use this integration, you must be using Segment's Mobile Analytics SDK for: iOS (Native Obj-C or Swift), Android (Java or Kotlin). This integration is NOT compatible with any other framework, including Unity, Factual Engine, React Native, or Xamarin, etc!

What's Supported
  1. Basic Install Attribution
  2. SkAdNetwork 3 Support (SKAN 3.0)
  3. Apple Search Ads Attribution
  4. Custom In-App Event Tracking
  5. Revenue tracking
  6. Custom User ID
What's NOT Supported
  1. SkAdNetwork 4 Support (SKAN 4.0)
  2. META Install Referrer Attribution
  3. Deep linking
  4. Limited Data Sharing Support

If you need support for another Frameworks or would like "Full Feature Functionality" offered by the Singular SDK, you must implement the Singular SDK independently from Segment. See the SDK Options and Frameworks HERE.

Getting Started

  1. From the Segment web app, click "Catalog" under the "Connections" menu.
  2. Search for "Singular" in the Catalog, select it, and click the "Add Destination" button.
  3. Select the sources to connect the destination to and click "Next".
  4. Name the destination, and click "Create destination"
  5. Get your Singular "SDK KEY", found in the Singular Dashboard under "Developer Tools > SDK Integration > SDK Keys", and add it to the Segment "Connection Settings", under "API Key" and "Secret".

    mceclip0.png

Important: Be sure to use the Singular SDK Key for the API Key value in Segment. Do not use the Singular Reporting API Key. If the wrong key is used, Singular will not receive any data.

Additional Setup

To use native-only features of this integration, you'll need to include the Singular library by adding these lines to your dependency config:

For iOS

Segment Analytics for iOS

  1. Add AdServices.framework in Link Binary With Libraries and mark it as Optional (only available for devices with iOS 14.3 and higher). This is needed to support Apple Search Ads attribution.
  2. Add the Singular Segment integration pod to your app's podfile as follows:
    pod 'Segment-Singular' 
  3. Import the Singular Library in your file:
    #import <Segment-Singular/SEGSingularIntegrationFactory.h>
  4. Finally, register the Singular with the Segment SDK
    Obj-C Swift
    SEGAnalyticsConfiguration *configuration = 
    [SEGAnalyticsConfiguration configurationWithWriteKey:@”<SEGMENT_WRITE_KEY>”];
    
    // Enable this to record certain application events automatically!
    configuration.trackApplicationLifecycleEvents = YES;
    // Enable this to record screen views automatically!
    configuration.recordScreenViews = YES;
    // Add any of your Device-mode destinations.
    configuration use:[SingularIntegrationFactory instance]];
    [SEGAnalytics setupWithConfiguration:configuration];
  5. [OPTIONAL] Implement SKAN support

    The Singular SDK can control your SKAdnetwork integration. For details on how this works, see iOS SDK: Adding SKAdNetwork Support.

    To let Singular control your SKAdNetwork integration, add the following code before the initialization of the Segment SDK:

    Obj-C Swift
    [SingularIntegation setSKANOptions:YES
      isManualSkanConversionManagementMode: NO
      withWaitForTrackingAuthorizationWithTimeoutInterval:@0
      withConversionValueUpdatedHandler:^(NSInteger conversionValue) {
          NSLog(@"Your SKAN handler %ld",conversionValue);
      }];
For Android

Segment Analytics for Android

  1. Add the Singular Segment integration dependency to your app's build.gradle file:
    compile 'net.singular.segment.integration:singular_segment_sdk:+'
  2. Add the Required Permissions to the AndroidManifest.xml file. Include the following permissions:
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
  3. After adding the dependency, you must import the integration
    import net.singular.segment.integration.SingularIntegration;
  4. Finally, Add Code to Initialize the Singular SDK

    Add .trackApplicationLifecycleEvents() to send app open, app updated, and app installed events to Singular.

    static final String SEGMENT_WRITE_KEY = "<YOUR_KEY>";
    @Override protected void onCreate(Bundle savedInstanceState) {
    Analytics analytics = new Analytics.Builder(this , SEGMENT_WRITE_KEY) .use(SingularIntegration.FACTORY .logLevel(Analytics.LogLevel.VERBOSE) .recordScreenViews() .trackApplicationLifecycleEvents() .build(); Analytics.setSingletonInstance(analytics); }

Install Attribution

Enable automatic tracking of lifecycle events (Application Opened, Application Installed, Application Updated) using initialization config parameters (iOS, Android) to track installs and sessions in Singular. The Singular "session" will be sent automatically by the integration as long as you include the events above.

Tracking Custom Event

If you’re not familiar with the Segment Specs, take a look to understand what the Track method does.

Use the Segment track function to have events translated and sent to Singular:

iOS (Obj-C) Android (Java)
[[SEGAnalytics sharedAnalytics] track:@"simple event"];

Segment includes all the event properties as callback parameters on the Singular event.

The events will be available in reporting & user-level exports.

Revenue Tracking

Singular will receive revenue tracking when an event containing the revenue property is sent (including zero value). You can optionally pass the currency (as an ISO 4217 currency code code). The default currency is USD.

iOS (Obj-C) Android (Java)
[[SEGAnalytics sharedAnalytics] track:@"segment revenue event" properties:@{@"currency": @"USD", @"revenue":@20}];

Note: Pass currency as a three-letter ISO 4217 currency code, e.g., "USD," "EUR", "INR".

Custom User ID

You may send your Segment User ID to Singular using the Segment identify method.

Note: If you use Singular's Cross-Device solution, you must collect the same UserID across all platforms.

  • The User ID can be any identifier and should not expose PII (Personally Identifiable Information). For example, you should not use a User's email address, username, or phone number. Singular recommends using a hashed value unique only to your first-party data.
  • The User ID value passed to Singular should also be the same internal User ID you capture across all platforms (Web/Mobile/PC/Console/Offline).
  • Singular will include the User ID in user-level exports, ETL, and Internal BI postbacks (if configured). The User ID is first-party data, and Singular does not share it with other parties.
  • The User ID value, when set, will persist until it is unset using the Segment reset method or until the app is uninstalled. Closing or restarting the app does not unset the User ID.

Follow the steps here to configure for: iOS, Android.

iOS (Obj-C) Android (Java)
[[SEGAnalytics sharedAnalytics] identify:@"segment custom user id"];

In order to unset the Custom User ID, call the reset method.

[[SEGAnalytics sharedAnalytics] reset];