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.
See also: Singular SDK and S2S developers guides.
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.
You can integrate Singular into your app using one of the available SDK versions or through a server-to-server (S2S) integration:
- Singular Android SDK
- Singular iOS SDK
- Singular Unity SDK
- Singular React Native SDK
- Singular Unreal Engine SDK
- Singular Website SDK
- Server-to-Server (S2S) Integrations
|Supported Devices||Supported Platforms||Supported Development Platforms||SDK Languages|
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).
We recommend using Singular's automatic session management. You can override the default 60-second session timeout.
- 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.
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:
- 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.
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).
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 web app) to make sure the SDK is reporting events to the Singular servers properly.
For full instructions, see our SDK integration testing guides.