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.
Singular may receive event data from Segment over the Singular Server-to-Server (S2S) REST APIs for iOS and Android Mobile activity. This is referred to as a "Cloud-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 into your app. |
To use this integration, you must be using Segment's Mobile Analytics SDKs. This integration is NOT compatible with Non-Mobile event data. Server or Web Events are not supported.
- Basic Install Attribution
- Apple Search Ads Attribution
- Custom In-App Event Tracking
- Revenue tracking
- Custom User ID
- SkAdNetwork Support
- META Install Referrer Attribution
- Deep linking
- Limited Data Sharing Support
If you need S2S support for the "Full Feature Functionality" offered by Singular, you must implement the Singular S2S REST APIs independently from Segment. See the Server-to-Server (S2S) Integration Guide 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".
Note: For the "Cloud-Mode" integration, you will ONLY input the API Key(SDK Key) value.
Leave the "Secret" blank.
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
Apple Search Ads Attribution Support
Note: If you are using the Device-Based Destination, there’s no need to implement the code below, as the data is already collected automatically.
To get attribution data into Singular, you must include the analytics-ios-iads-attribution dependency and version 3.6.0 or higher of the Analytics SDK.
To install it, simply add the following line to your Podfile:
pod "Analytics"
pod "Analytics-iAds-Attribution"
Then import the header and initialize the configuration:
#import <Analytics-iAds-Attribution/SEGADTracker.h>
// Initialize the configuration as you would normally.
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration
configurationWithWriteKey:@"YOUR_WRITE_KEY"];
...
// Configure the client with the iAD middleware to attach iAd properties.
configuration.middlewares = @[ [SEGADTracker middleware] ];
[SEGAnalytics setupWithConfiguration:configuration];
import Analytics-iAds-Attribution
// Initialize the configuration as you would normally.
var configuration = SEGAnalyticsConfiguration(writeKey: "WriteKey")
...
// Configure the client with the iAD middleware to attach iAd properties.
configuration.middlewares = [SEGADTracker.middleware()]
SEGAnalytics.setup(with: configuration)
When iAd information is available, the attribution information is transformed to Segment context this way:
[analytics track:@"Application Installed",
properties: nil,
options: @{
@"context" : @{
@"campaign" : @{
@"provider" : @"Apple",
@"click_date" : attributionInfo[@"iad-click-date"],
@"conversion_date" : attributionInfo[@"iad-conversion-date"],
@"source" : @"iAd",
@"name" : attributionInfo[@"iad-campaign-name"],
@"content" : attributionInfo[@"iad-keyword"],
@"ad_creative" : attributionInfo[@"iad-org-name"],
@"ad_group" : attributionInfo[@"iad-adgroup-name"],
@"id" : attributionInfo[@"iad-campaign-id"],
@"ad_group_id" : attributionInfo[@"iad-adgroup-id"]
}
}
}];
Singular has explicitly mapped the Application Installed lifecycle event to provide the iAd Information.
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.
Notes:
- We highly recommend passing event names and attributes in English to guarantee compatibility with third-party partners and analytics solutions if you plan to use them.
- Event names are limited to 32 ASCII characters. Strings in non-ASCII characters have to be under 32 bytes once converted to UTF-8.
- Attributes and values are limited to 500 ASCII characters.
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];