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 offers many features that are not available through the standard "Device-Mode" or "Cloud-Mode" integration options.

Integrating through a hybrid methodology is recommended when using Segment with Singular to take advantage of all the Singular features and functionality.

The Hybrid approach consists of:

Implementing the Singular SDK independently of Segment, allowing for the Singular SDK to handle Session tracking, addition support for SDK Frameworks (React Native, Unity, etc.), SkAdNetwork, deep link and deferred deep links, and advanced features.
Enabling the "Cloud-Mode" option in Segment for a Singular Destination. This allows for all Segment mobile track events to be sent to the Singular's Destination.

The instructions below illustrate how to configure a Singular Hybrid implementation with Segment.

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

To use this integration, you must be using Segment's Mobile Analytics SDKs.

What's Supported

The Singular SDK will provide support for:

Install Attribution
SkAdNetwork Support
Google Install Referrer Support
META Install Referrer Support
Apple Search Ads Attribution
Custom In-App Event Tracking
Revenue tracking
Custom User ID
Global Properties Support
Privacy options

The Segment "Cloud-Mode" integration will provide support for Mobile post install events (Web Events are not supported):

Custom In-App Event Tracking
Revenue tracking
Custom User ID

What's NOT Supported

Android AppSetId (MORE)
The Android AppSetId is utilized by Singular's SDK as a fallback identifier to track SDK activity when the Google Advertising ID is unavailable. Although this Identifier is not used for attribution purposes, it plays a role in recognizing the device and associating in-app events to said device.

Segment does not capture the Android AppSetId, and therefore Segment will be unable to send any event to the Singular "Cloud-Mode" Destination when the user's device does not have the Google Advertising Identifier.

If Segment sends an event to Singular with a different Identifier than what the Singular SDK has associated with the same device, a discrepancy will result. An Organic attribution to the unknown identifier from the S2S event and a possible misattributed revenue event.

Please speak with a Singular Solutions Engineer if you have any questions about this edge case.

Hybrid Configuration

Integrate the Singular SDK
Implement the Singular SDK independently from Segment. See the SDK Options and Frameworks HERE.
Enable the Segment - Singular Destination (Cloud-Mode)
Follow the Guide HERE.

Recommended Additional Setup

When using a Hybrid Methodology, it is recommended to pass the Segment AnonymousId and the Segment User ID to Singular's SDK.

Take special note and care to implement these optional features from the SDK documentation. Steps may vary slightly depending on the framework you are using.

Implement Global Properties

Pass the Segment AnonymousId into a Singular Global Property. This will associate the Segment AnonymousId to device-level data from the SDK. Providing this value to Singular in the Singular Config object at the time of the Singular SDK Initialization will also allow Singular to send an Install postback to Segment when the UserId is unknown.

Singular can ONLY provide the attribution information to Segment from the App Install using the Segment AnonymousId and/or Segment UserId value. Reference Singular's Global Properties [iOS][Android] as examples of how this is configured.

The Global Property should be configured when initializing the Singular SDK with the key: segment_anonymous_id and the value of the Segment anonymousId retrieved from the Segment SDK. The Segment AnonymousID can be sourced from the Segment SDK using this method.

Analytics.with(context).getAnalyticsContext().traits().anonymousId()

Example Singular SDK Config


func getConfig() -> SingularConfig? { 
   // (Optional) Get 3rd-party identifiers to set in Global Properties: 
   // If 3rd-party SDKs are providing any identifiers to Singular, the
   // respective SDK must be initialized before Singular. 
   
   let thirdPartyKey = "segment_anonymous_id" 
   let thirdPartyValue = SEGAnalytics.shared().getAnonymousId()
   
   // Singular Config Options 
   guard let config = SingularConfig(apiKey: Constants.APIKEY, 
      andSecret: Constants.SECRET)
      else { 
         return nil
      }
   ... 
   // Using Singular Global Properties feature to capture third party identifiers
   config.setGlobalProperty(thirdPartyKey, 
      withValue:thirdPartyValue, overrideExisting: true) 
   ...
   
return config}


- (SingularConfig *)getConfig { 
   // Get the 3rd-party identifiers to set in Global Properties: 
   // If 3rd-party SDKs are providing any identifiers to Singular, the
   // respective SDK must be initialized before Singular.
   
   NSString* thirdPartyKey = @"segment_anonymous_id";
   NSString* thirdPartyValue = [[SEGAnalytics sharedAnalytics] getAnonymousId];
   
   // Singular Config Options 
   SingularConfig* config = [[SingularConfig alloc] 
      initWithApiKey:APIKEY andSecret:SECRET];
   ...
   // Using Singular Global Properties feature to capture 3rd-party identifiers 
   [config setGlobalProperty:thirdPartyKey 
      withValue:thirdPartyValue overrideExisting:YES];
   ...
   
   return config;}

// (Optional) Get 3rd-party identifiers to set in Global Properties:
// If 3rd-party SDKs are providing any identifiers to Singular, the
// respective SDK must be initialized before Singular.

String thirdPartyKey = new String("segment_anonymous_id");
String thirdPartyValue = new String(Analytics.with(context).getAnalyticsContext().traits().anonymousId());

// Singular Config Options
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
   .withGlobalProperty(thirdPartyKey, thirdPartyValue, true);

Implement Custom User ID

Pass the Segment UserId into the Singular Custom User ID method. This will associate the Segment UserId to device-level data from the SDK. Providing this value to Singular in the Singular Config object at the time of the Singular SDK Initialization will also allow Singular to send the UserId on the Install postback to Segment. Read More for the SDK Framework documentation you are using for the Singular integration. Example of [iOS][Android]

Additionally, the UserID will be associated with any in-app event triggered natively from the Singular SDK.

For the "Cloud-Mode" events received, Singular has mapped the Custom User ID to the Segment User ID value. Be sure to follow the steps here to configure for: iOS, Android.

Configure the Singular Partner Configuration

You will need to enable Segment in the Partner Configuration page to pass Install data back to Segment.

In the Singular Platform:

Navigate to "Attribution > Partner Configuration" and click the "Add Partner" button.
Search for Segment
Select the App and Site
Click Save

FAQ and Troubleshooting

Why are installs from Meta (Facebook) Ads showing as "Unattributed" in Segment integration despite being correctly attributed in Singular's reports?

Facebook imposes restrictions on data access and user-level data, which can hinder the accurate transmission of attribution data to Segment.

When installs are sent to Segment through the "Install" event, Facebook's restrictions may prevent the passage of user-level data accurately. You can review their data policy here As a result, while these same installs may appear attributed to Facebook in Singular's aggregated reports, they may be classified as "Unattributed" in Segment.