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

Getting Started

Get your Singular API Key from the Singular web app under Developer Tools > API Keys.
In the Segment Destinations page, click Add Destination.
Search for "Singular" in the Destinations Catalog and confirm the source you'd like to connect to.
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 Attributed" Postback to Segment (Requires Singular SDK)

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.

Enabling the "Install Attributed" Segment Event

Requires the Native Singular SDK:

In order for Singular to provide attribution data back to Segment for the Install Attributed Event, Singular must receive the Segment anonymousId and/or userId. The userId is by default captured and provided to Segment, if available at the time of the install. In cases where the userId is not available, Singular needs the anonymousId from Segment. To support this functionality, the Singular SDK must be integrated to send a Custom SDK Event named "Install Attributed". This event must be sent to Singular immediately after the SDK is initialized with the anonymousId as the value for the attribute s_anonymous_id. The Segment anonymousId can be sourced from the Segment SDK using this method.

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

Example SDK Event to be sent immediately after Singular Initialization:

Be sure to pass in the appropriate value for the userId and anonymousId.

iOS (Objective-C):

NSString *userId = @"myUserId";
    NSString *anonymousId = [[SEGAnalytics sharedAnalytics] getAnonymousId];
    [Singular eventWithArgs:@"Install Attributed",
    @"s_user_id",userId,
    @"s_anonymous_id",anonymousId, nil];