Get your Singular SDK Key

In your Singular account, go to "Developer Tools > SDK Integration > SDK Keys" and copy your SDK Key and Secret.

Add Singular as an mParticle Output

1. In your mParticle account, go to Setup > Outputs and click Add Event Output.
2. Select Singular from the dropdown list.
3. In the Event Configuration window, enter a name for the configuration and enter the Singular key and secret you copied in the previous step.
4. Click Save.

Install the Singular SDK

To install the Singular SDK:

1. In your app, add AdServices.framework in Link Binary With Libraries and mark it as Optional (only available for devices with iOS 14.3 and higher).

2. Add the Singular MParticle pod to your app's podfile:

   pod 'mParticle-Singular'

3. In the podfile's directory, run 'pod install'.

Import the Singular Library

To import the Singular library, add the following line of code:

#import "MPKitSingular.h"

Initialize the Singular SDK

The SDK initialization code should be called every time the app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular (sessions are used to calculate user retention).

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //initialize mParticle 
    MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
    [[MParticle sharedInstance] startWithOptions:options]; 
    return YES; 
}

[OPTIONAL] Track Events

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs.

Depending on your application, you may want to track events such as user logins, registrations, tutorial completions, or leveling up in a game.

The following sample code reports an event called "event_name" to Singular, with two custom attributes. You'll be able to see counts of "event_name" occurrences in your Singular reports.

MPEvent *event = [[MPEvent alloc] initWithName:@"event_name"
    type:MPEventTypeTransaction];
event.customAttributes = @{@"category":@"Destination Intro",
    @"title":@"Paris"};
[[MParticle sharedInstance] logEvent:event];

[OPTIONAL] Track Revenue

Singular can collect data about revenue gained through the app to help analyze the performance and ROI of your campaigns.

Singular will make the data available to you in reports, log export, and postbacks.

To track revenue, report revenue events to Singular as in the following example. This example reports an in-app purchase of a product, giving the product name, SKU, quantity, and price.

// 1. Create the products
MPProduct *product = [[MPProduct alloc] initWithName:@"product_name" sku:@"product_sku" quantity:@10     
                                              price:@100.00];
// 2. Summarize the transaction
MPTransactionAttributes *attributes = [[MPTransactionAttributes alloc] init];
attributes.transactionId = @"ransaction_id";
attributes.revenue = @400.00;
attributes.tax = @10.00;

// 3. Log the purchase event
MPCommerceEventAction action = MPCommerceEventActionPurchase;
MPCommerceEvent *revenueEvent = [[MPCommerceEvent alloc] initWithAction:action product:product];
revenueEvent.transactionAttributes = attributes;
[[MParticle sharedInstance] logEvent:revenueEvent];

[OPTIONAL] Add SKAdNetwork Support

SKAdNetwork is Apple's new framework for determining mobile install attribution without compromising the end user's privacy.

SKAdNetwork lets you measure the performance of your app marketing campaigns without sharing the user's personally identifiable information.

Singular SKAdNetwork solution, SKAN, allows you to implement SKAdNetwork with minimal engineering effort. Once you initialize SKAN, every event you report to Singular is automatically processed on the server side to update the conversion value based on your predefined conversion model. The new conversion value is then sent back to the app. This process repeats itself until the measurement period is over and the app sends the latest conversion value to SKAdNetwork.

For more information, see Introduction to Singular's SKAdNetwork Solution and How to Get Started with SKAdNetwork.

The following sample code enables SKAN following a 60-second wait for ATT consent (see Singular iOS SDK: Handling AppTrackingTransparency Consent).

[MPKitSingular setSKANOptions:YES isManualSkanConversionManagementMode:NO 
    withWaitForTrackingAuthorizationWithTimeoutInterval:@60.0 
    withConversionValueUpdatedHandler:^(NSInteger conversionValue) {
                  NSLog(@"conversion value %ld", conversionValue);
}];

[OPTIONAL] Handle Deep Links

Deep links are links that lead into specific content inside an app. When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep linking as well as deferred deep linking (see our Deep Linking FAQ and the Singular Links FAQ for more information).

Notes:

• Singular uses iOS Universal Links for deep linking.
• To enable Universal Links, follow the instructions in Singular Links Prerequisites.
• The deep link destinations for your app need to be set up on the Apps page in Singular (see Configuring Deep Link URLs).

Handling Deep Links Using AppDelegate:

Add a call to the SDK initialization method, including onAttributionComplete:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //initialize mParticle 
    MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
    options.proxyAppDelegate = NO; 
    [[MParticle sharedInstance] startWithOptions:options]; 
    return YES; 
}

Also add a call mParticle's continueUserActivity method in AppDelegate's continueUserActivity:

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
}

Handling Deep Links Using SceneDelegate:

Add a call to mParticle's continueUserActivity method in SceneDelegate's continueUserActivity and willConnectToSession:

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
options:(UISceneConnectionOptions *)connectionOptions {
    NSUserActivity* userActivity =
    [[[connectionOptions userActivities] allObjects] firstObject];
    [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
}

- (void)scene:(UIScene *)scene
    continueUserActivity:(NSUserActivity *)userActivity{
    [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
}

Get your Singular SDK Key

In your Singular account, go to "Developer Tools > SDK Integration > SDK Keys" and copy your SDK Key and Secret.

Add Singular as an mParticle Output

1. In your mParticle account, go to Setup > Outputs and click Add Event Output.
2. Select Singular from the dropdown list.
3. In the Event Configuration window, enter a name for the configuration and enter the Singular key and secret you copied in the previous step.
4. Click Save.

Install the SDK

1. Add Singular's Maven server to your buildscript as follows. This is a requirement of the Singular kit.

   repositories {
       maven { url "http://maven.singular.net"}
       ...
   }

2. Add the kit dependency to your app's build.gradle:

   dependencies {
       compile 'com.mparticle:android-singular-kit:5+'
   }

Initialize the SDK

The SDK initialization code should be called every time the app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular (sessions are used to calculate user retention). You'll be able to track sessions in the mParticle dashboard as well as Singular reports.

//import mParticle
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;

public class ExampleActivity extends Activity {
    @Override
    public void onCreate() {
        super.onCreate();
        MParticleOptions options = MParticleOptions.builder(this)
                .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                .build();
        MParticle.start(options);
    }
}

[OPTIONAL] Set the User ID

The Singular SDK can send a user ID from your app to Singular. This can be a username, email address, randomly generated string, or whichever identifier you use as a user ID.

Singular uses the user ID in user-level data exports and internal BI postbacks (if you configure such postbacks).

Once you set the user ID, it is sent along with any session and event. The user ID persists until you unset it or until the app is uninstalled. Closing/restarting the app does not unset the user ID.

IdentityApiRequest identityRequest = IdentityApiRequest.withEmptyUser()
        .email("foo@example.com")
        .customerId("123456")
        .build();
MParticle.getInstance().Identity().login(identityRequest);

[OPTIONAL] Track Events

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs.

Depending on your application, you may want to track events such as user logins, registrations, tutorial completions, or leveling up in a game.

The following sample code reports an event called "test_event" to Singular with additional information (customAttributes) in JSONObject format.

Map<String, String> customAttributes = new HashMap<String, String>();
          customAttributes.put("category", "event_category");
          MPEvent event = new MPEvent.Builder("test_event", MParticle.EventType.Navigation)
                 .customAttributes(customAttributes)
                 .build();
          MParticle.getInstance().logEvent(event);
        

[OPTIONAL] Track Revenue

Singular can collect data about revenue gained through the app by receiving Product.PURCHASE events from mParticle.

Event revenue is calculated as quantity * product_cost.

Product product = new Product.Builder("extra life", "extra-life", 100.00)
        .quantity(4.0)
        .build();
TransactionAttributes attributes = new TransactionAttributes("123123")
        .setRevenue(430.00)
        .setTax(30.00);

CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
        .transactionAttributes(attributes)
        .currency("USD")
        .build();

MParticle.getInstance().logEvent(event);

[OPTIONAL] Handle Deep Links

Deep links are links that lead into specific content inside an app. When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep linking as well as deferred deep linking (see our Deep Linking FAQ and the Singular Links FAQ for more information).

Notes:

• To enable deep links for your app, see Singular Links Prerequisites.
• The deep link destinations for your app need to be set up on the Apps page in Singular (see Configuring Deep Link URLs).

To handle deep links, implement AttributionListener as in the following example. Note that you need to implement AttributionListener in every main entrance activity.

public class ActivityDeeplink extends AppCompatActivity implements AttributionListener {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        MParticleOptions options = MParticleOptions.builder(this)
                .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                .attributionListener(this)
                .logLevel(MParticle.LogLevel.VERBOSE)
                .build();
        MParticle.start(options);
    }

    @Override
    public void onResult(@NonNull @NotNull AttributionResult attributionResult) {
        if (attributionResult.getServiceProviderId() == MParticle.ServiceProviders.SINGULAR) {
            String deeplink = attributionResult.getLink();
            JSONObject data = attributionResult.getParameters();
            String passthrough = data.optString("passthrough", null);
            // Deal with deep link
        }
    }

    @Override
    public void onError(@NonNull @NotNull AttributionError attributionError) {
        // Deal with error
    }
}