Singular SDK/S2S FAQ for Project Managers – Singular Help Center

Use this FAQ to learn about the Singular SDK and help plan your integration.

For a step-by-step guide to onboarding to Singular's attribution service, including planning, implementing, and testing the SDK integration, see How to Get Started with Singular Attribution.

How does the Singular SDK/S2S work to trigger app attribution?

The main function of the SDK is to enable mobile app attribution by notifying Singular about user sessions.

The Importance of Sessions

In apps that have the Singular SDK/S2S integration, whenever the app is opened, the SDK sends a session to the Singular server.

Singular checks the device information and proceeds appropriately:

If this is the first session for this device, Singular recognizes a new app install and triggers the install attribution process (see Understanding Singular Mobile App Attribution).
If the session matches the definition of a re-engagement session, Singular triggers the re-engagement attribution process (see the Re-engagement-FAQ?navigation_side_bar=true">Re-engagement FAQ).
Otherwise, the session is used to measure user retention.

For more about Singular's attribution process, see Understanding Singular Mobile App Attribution.

What devices and platforms are supported?

You can integrate Singular into your app using one of the available SDK versions or through a server-to-server (S2S) integration:

Supported Devices	Supported Platforms	Supported Development Platforms	SDK Languages
Android 4.0.1+ iOS 8+	Android 14+ Amazon iOS (Xcode 6+) Unity v5+ Browser In-App	Android Studio Xcode 6+ Unity v5+	Android - Java iOS - Objective-C Swift - w/ Obj-C bridge Unity - C#

Which device/user/other identifier(s) does the SDK use for attribution?

To perform attribution, Singular uses the device's advertising ID to match the device the app is installed on to the device from which an ad was viewed or clicked on.

The advertising ID used is IDFA for iOS devices or GAID (AIFA) for Android devices.

If LimitedAdTracking is enabled and the advertising ID is not available to Singular, a backup identifier is IDFV (identifierForVendor) for iOS and ANDI (Android ID) for Android.

Note: If your app allows users to log in with a user ID, such as a username or email, you can configure the SDK to send that user ID to Singular. However, this ID is not used for mobile attribution (for ways to use the user ID to track users across devices, see Introduction to Singular's Cross-Device Attribution).

How does the SDK manage user sessions?

We recommend using Singular's automatic session management. You can override the default 60-second session timeout.

Notes:

In Android, automatic session management requires Android API 14 or above. If you're using an older API you have to handle sessions manually.
The Unity SDK handles session management automatically regardless of the device version.
The S2S integration handles session tracking by calling the Launch event on every app open.

How does the SDK track in-app events?

The Singular SDK/S2S includes methods to track any event that occurs inside the app. Event tracking is entirely customizable and depends on which KPIs you want to measure.

Some common events are:

Registration
Level up
Product view
Add to cart

You can give events custom names and pass any arguments to add more detail to Singular reports. For example, if you are tracking a product view event, you can add the product ID, category, etc.

In addition, you can configure the SDK to send a user ID to Singular, whether it's a username, an email address, or an internal identifier you use in your app. The user ID will then be attached to every event you send from that point onward - until the app is uninstalled or you change or unset the user ID.

How does the SDK track revenue?

The Singular SDK provides methods for sending revenue events to Singular. These are a special type of events that are associated with a revenue amount and currency.

We highly recommend passing the device platform's transaction receipt to Singular. This gives Singular all the transaction details, which Singular will use to enrich your reports with data. In addition, the transaction receipt is used to validate the transaction and to analyze and prevent fraud attempts.

The alternative is to send revenue events by specifying a revenue amount, currency, and optional additional transaction details (e.g., the product details).

Note: You can give revenue events custom names to tell them apart in reports. Otherwise, they show up by default as "__iap__" (for In-App Purchase).

How do we test the SDK integration?

For some customers and implementations, it's easier to test the SDK integration after every step of development (for example, implement sessions and test them, then implement revenue events and test them). Other customers prefer to test the integration after it's done.

Regardless, to test your integration, you or your engineering team will be running the app on a test device and triggering sessions, purchases, and other user events. You will use Singular's Testing Console (a testing tool available inside the Singular platform) to make sure the SDK is reporting events to the Singular servers properly.

For full instructions, see our SDK integration testing guides.