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!
- Basic Install Attribution
- SkAdNetwork 3 Support (SKAN 3.0)
- Apple Search Ads Attribution
- Custom In-App Event Tracking
- Revenue tracking
- Custom User ID
- SkAdNetwork 4 Support (SKAN 4.0)
- META Install Referrer Attribution
- Deep linking
- 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
- From the Segment web app, click "Catalog" under the "Connections" menu.
- Search for "Singular" in the Catalog, select it, and click the "Add Destination" button.
- Select the sources to connect the destination to and click "Next".
- Name the destination, and click "Create destination"
- 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".
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:
- 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.
- Add the Singular Segment integration pod to your app's podfile as follows:
pod 'Segment-Singular'
- Import the Singular Library in your file:
#import <Segment-Singular/SEGSingularIntegrationFactory.h>
- Finally, register the Singular with the Segment SDK
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];let configuration = AnalyticsConfiguration(writeKey: "<SEGMENT_WRITE_KEY>")
// Enable this to record certain application events automatically!
configuration.trackApplicationLifecycleEvents = true
// Enable this to record screen views automatically!
configuration.recordScreenViews = true
// Add any of your Device-mode destinations. configuration.use(SingularIntegrationFactory.instance())
Analytics.setup(with: configuration) - [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:
[SingularIntegation setSKANOptions:YES isManualSkanConversionManagementMode: NO withWaitForTrackingAuthorizationWithTimeoutInterval:@0 withConversionValueUpdatedHandler:^(NSInteger conversionValue) { NSLog(@"Your SKAN handler %ld",conversionValue); }];
SingularIntegation.setSKANOptions(
true,
isManualSkanConversionManagementMode: false,
withWaitForTrackingAuthorizationWithTimeoutInterval: NSNumber(value: 0), withConversionValueUpdatedHandler: { conversionValue in print(String(format: "Your SKAN handler %ld", conversionValue)) })
- Add the Singular Segment integration dependency to your app's build.gradle file:
compile 'net.singular.segment.integration:singular_segment_sdk:+'
- 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" />
- After adding the dependency, you must import the integration
import net.singular.segment.integration.SingularIntegration;
- 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:
[[SEGAnalytics sharedAnalytics] track:@"simple event"];
Analytics.with(this).track("event_name");
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.
[[SEGAnalytics sharedAnalytics] track:@"segment revenue event" properties:@{@"currency": @"USD", @"revenue":@20}];
Analytics.with(this).track("purchase", new Properties().putRevenue(2.5).putValue("currency","USD"));
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.
[[SEGAnalytics sharedAnalytics] identify:@"segment custom user id"];
Analytics.with(context).identify("myUserId");
In order to unset the Custom User ID, call the reset method.
[[SEGAnalytics sharedAnalytics] reset];