Segment S2S Integration

Singular's integration with Segment is based on a server-to-server implementation. To integrate with Segment, follow the steps below.

Getting Started

  1. Get your Singular API Key from the Singular platform under Developer Tools > API Keys.
  2. In the Segment Destinations page, click Add Destination.
  3. Search for "Singular" in the Destinations Catalog and confirm the source you'd like to connect to.
  4. In Segment Settings, add your Singular API Key.

What's supported

  • Install Attribution
  • Apple Search Ads Attribution
  • Custom Event Tracking
  • Revenue tracking
  • Custom User ID

Install Attribution

Enable automatic tracking of lifecycle events (Application Opened, Application Installed, Application Updated) via 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 are including the events above.

Apple Search Ads Attribution

To get iAD 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, add the following line to your Podfile:

pod "Analytics"
  pod "Analytics-iAds-Attribution"

Then import the header and initialize the configuration:

iOS (Obj-C):

#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];
    

iOS (Swift):

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.

Tracking Custom Events

Review the Track method documentation. An example call (in Android):

Analytics.with(context).track("Signup")
    Analytics.with(context).track("Level9Passed")

These calls are sent to Singular and processed as custom post-install events. They are then available in reporting and 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 iso3 code). The default currency is USD.

Android example:

Analytics.with(context).track("Order Completed", new Properties().putRevenue(1.99));

Custom User ID

Singular has mapped the Custom User ID to the Segment User ID value. Follow the steps here to configure for: iOS, Android.

"Install" Postbacks

Requires the Native Singular SDK:

Singular can provide attribution information to Segment from the App Install using Singular's Global Properties [iOS][Android]. 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 object:

iOS (Objective-C):


  - (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;}

iOS (Swift):


  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 }

Android (Java):


       // (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);


You will need to enable Segment in the Partner Configuration page:

segment_partner_config.png