SESSION Endpoint API Reference
Server-to-Server Use Case
The Singular REST API enables direct server-to-server integration as an alternative to the SDK. The LAUNCH or Session Endpoint enables session tracking in your applications. When your app forwards device-specific data to your server, which then transmits the data to Singular's servers, the Singular platform then processes this information for: Install Attribution, ReEngagement Attribution, and Retention Metrics. This processed data automatically populates your reports, export logs, and configured postbacks, providing comprehensive analytics for your marketing campaigns.
While the SDK automatically collects device and app data, the S2S approach requires you to:
- Collect required data points from your app
- Forward this data to your server
- Send it to Singular via REST API
- Pass the Singular response back to the app
Key Points
- Flexibility: Full control over data collection and transmission
- Feature Parity: Supports all SDK functionality when proper data is provided
- Integration Path: Client → Your Server → Singular API
- Real-time processing: One request at a time, no batch processing
- Sequential data flow: Events must be processed in chronological order
- Data Deduplication: Singular does not deduplicate received data. It is recommended to send one(1) successful Request and save logs in the event a Request should be replayed.
- Data Validation: Device-level data is permanent and cannot be deleted once ingested. Implement thorough data validation before sending data to Singular to ensure accuracy.
Session Management
The LAUNCH endpoint is used to notify Singular of an App Open event for a new User Session.
-
Session initialization (launch request) required for:
- Fresh app installations
- App launches from terminated state
- App returning to foreground from background
- Session must be established before any event tracking
- Invalid session order will result in data inconsistencies
- It is recommended to implement a Session timeout and only send Singular the SESSION notification if the App has not been used within the last 1 min. If a user backgrounds the App, and then Foregrounds the App within 1 min or less, this should not trigger a Singular SESSION, but if they Foreground in greater than 1 minute this should trigger a SESSION.
- In order to support deep linking, a Session must always be sent for the App Open with the openURL in the 'open_uri' parameter.
Getting Started
The Session endpoint documentation provides:
Be sure to review the advanced options of Singular's Server-to-Server (S2S) integration which require the Session Notification Endpoint to include additional parameters. Learn about the Advanced Options here.
Reporting Sessions
The most basic integration with Singular involves notifying Singular when a User session occurs, allowing Singular to trigger several internal processes:
- If it's the first session for the app on the specific device, Singular recognizes a new install and triggers the install attribution process.
- If the session qualifies as a re-engagement session, Singular triggers the re-engagement attribution process (learn more in the Re-engagement FAQ).
- Otherwise, Singular marks it as a session, which is used to track user activity and retention metrics.
The timing of a session request and subsequent event requests to the Singular servers is critical:
-
A single session must be received prior to any events.
For example, the Singular SDK will trigger a session on the App Open when a user starts using the app, then in-app events may be sent following the session. If the user places the app in the background for an extended period of time (greater than 1 minute) the session would time-out. Another session would be sent when the app is brought back to the foreground. It is recommended to use App lifecycle events and a timer to help manage your session management and regulate the session requests to Singular. - Events occuring in the app must be sent in real-time and after their respective session.
Session API Endpoint
HTTP Method and Session Endpoint
GET https://s2s.singular.net/api/v1/launchRequired Parameters
The following table lists the required parameters that this endpoint supports. All of the parameters listed are query parameters.
GET /api/v1/launch?param1=value1¶m2=value2
- All required parameters must be included in SESSION API requests
- Parameters should follow specified format and data types
| Required Parameters | |
|---|---|
| API Key | |
| Parameter | Description |
|
The a parameter specifies the Singular SDK Key. Retrieve the SDK Key from the Singular UI, under Developer Tools in the Main Menu. Note: Do not use the reporting API Key as this will result in rejected data. Example Value: |
| Device Identifier Parameters | |
| Parameter | Description |
Supported Platforms:
|
The idfa parameter specifies the Identifier for Advertisers (IDFA) which helps advertisers track and attribute user actions (e.g., ad clicks, app installs) to specific campaigns, enabling precise ad targeting and campaign optimization. Starting with iOS 14.5, users must opt-in via the App Tracking Transparency (ATT) framework before apps can access the IDFA. If users do not opt-in to IDFA then the IDFA will be unavailable resulting in limiting tracking capabilities.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The idfv parameter specifies the Identifier for Vendors (IDFV), a unique identifier assigned by Apple to a device, which is specific to a particular vendor or developer. It remains consistent across all apps from the same vendor on a given device, allowing the vendor to track user behavior and interactions across their app ecosystem without identifying the user personally.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The aifa parameter specifies the Google Advertising Identifier (GAID), also known as AIFA in Singular or Android Advertising ID (AAID). This identifier is a unique, user-resettable identifier assigned to Android devices. It helps advertisers and app developers track and attribute user actions (e.g., ad clicks, app installs) across apps to specific campaigns, enabling precise ad targeting and campaign optimization, while maintaining user privacy.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The asid parameter specifies the Android App Set ID. The ASID provides a way for developers to track users across their own apps in a privacy-conscious manner. It is particularly useful for analytics and fraud prevention but cannot be used for advertising purposes such as personalized ads or measurement.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The amid parameter specifies the Advertising ID is a user-resettable, unique identifier that helps protect the privacy of the user. If you collect information about a user’s behavior to display interest-based ads, or to generate analytics, you must use the Advertising ID; no other identifier or tracking method may be used. Users can reset the Advertising ID or opt out of interest-based ads altogether.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The oaid parameter specifies Open Advertising Identifier (OAID). The OAID is a unique, anonymous identifier used for advertising purposes on Android devices, particularly those manufactured in China. It was introduced by the Mobile Security Alliance (MSA) as an alternative to Google's Advertising ID (GAID) for devices where Google Play Services are unavailable or not supported, such as in the Chinese market. The OAID is primarily used for advertising attribution and user tracking in environments where Google Play Services are restricted, allowing advertisers and developers to track user behavior while maintaining anonymity. OAID is available on most Chinese-manufactured Android devices, including those from brands like Huawei, Xiaomi, and others. It can be accessed using the MSA SDK or Huawei Mobile Services (HMS).
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The andi parameter specifies the Android ID which is a unique 64-bit identifier generated by the Android operating system when a device is first set up. It is designed to be persistent across the lifetime of the device, but it can be reset under certain conditions such as a factory reset. The Android ID is unique to each device and, starting from Android 8.0 (Oreo), it is scoped per app and per user. This means that different apps on the same device will receive different Android IDs unless they share the same signing key. The Android ID remains constant unless the device undergoes a factory reset or if an app is uninstalled and reinstalled after an OTA (over-the-air) update.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The sdid parameter specifies the Singular Device ID. This value is a client-side generated UUIDv4 representing a unique app install. This is the only device identifier used for PC and Console Applications. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The sing parameter is restricted to Enterprise customers and specifies a Client defined identifier. Only used in special uses where all other identifiers are not available. This identifier must be enabled by Singular Solution Engineer on an App-by-App bases. Example Value: |
| Device Parameters | |
| Parameter | Description |
|
The p parameter specifies the platform of the App. The following list contains the allowed case-sensitive parameter values:
Example Value: |
| Parameter | Description |
|
The ip parameter specifies the public (IPV4) IP Address of the device. IPV6 is not supported. Example Value: |
| Parameter | Description |
|
The ve parameter specifies the OS Version of the device at session time. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The ma parameter specifies the Make of the device hardware, typically the consumer-facing name. This parameter must be used with the model parameter. How to retrieve the Device Make Examples: |
| Parameter | Description |
Supported Platforms:
|
The mo parameter specifies the Model of the device hardware. This parameter must be used with the make parameter. How to retrieve the Device Model Examples: |
| Parameter | Description |
Supported Platforms:
|
The lc parameter specifies the IETF locale tag for the device, using two-letter language and country code separated by an underscore. How to retrieve the Device Locale Example Value: |
| Parameter | Description |
Supported Platforms:
|
The bd parameter specifies the Build of the device, URL-encoded. How to retrieve the Device Build Example Value: |
| Application Parameters | |
| Parameter | Description |
|
The i parameter specifies the App Identifier. This is the Package Name for Android or the Bundle ID for iOS or of your application. case-sensitive parameter values:
Example Value: |
| Parameter | Description |
|
The app_v parameter specifies the Application Version. Examples: |
| Parameter | Description |
|
The install parameter specifies if this Session represents the first Session after an Install or Re-Install. Pass 'true' if the session was the first after installing the app or 'false' if the app is already installed and this is a subsequent session or app open. This parameter is required for Reinstall tracking capabilities. Examples: |
| Parameter | Description |
Supported Platforms:
|
The install_time parameter specifies the time of the first app install as UNIX time. To retrieve this value, use the link on the platform. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The update_time parameter specifies the time of the last app update as UNIX time. To retrieve this value, use the link on the platform. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The att_authorization_status parameter specifies the App Tracking Transparency(ATT) status code. Starting with iOS 14.5, the App Tracking Transparency (ATT) prompt is required in order to access the IDFA identifier. Note: Even if you don't implement the ATT prompt, we require that you pass the ATT authorization status with the value '0', indicating "undetermined". Supported values are:
Examples: |
| Fraud Parameters | |
| Parameter | Description |
Supported Platforms:
|
The install_source parameter specifies the Install Source Package Name on Android. The recommended values for the install source on PC is the installing store. Supported Install Store Names for PC include:
Example for Android (Google Play Store): |
| Parameter | Description |
Supported Platforms:
|
The install_receipt parameter specifies the receipt received from the install. Learn how to retrieve it at iOS Install Receipt Example of a base64 encoded receipt string from iOS: |
| Deeplinking Parameters | |
| Parameter | Description |
Supported Platforms:
|
The openuri parameter specifies if the app opened via any deep link, iOS Universal Link, or Android App Link and you should provide the URL-encoded open URL value. Open URL:Example Value: |
| Parameter | Description |
Supported Platforms:
|
The ddl_enabled parameter specifies if the app is enabled to support Deferred deep links. Pass 'true' if the server expects a deferred deep link URL to be returned or 'false' otherwise. Example Value: Example Response: |
| Parameter | Description |
Supported Platforms:
|
The singular_link_resolve_required parameter is used to resolve a Singular short link. Must be sent with value in the 'openuri' that is a Singular short link. Pass 'true' if the server expects the expanded short link (long link) to be returned or 'false' otherwise. See Short Link handling. Example Value: Example Response: |
| Advanced Attribution Parameters | |
| Parameter | Description |
Supported Platforms:
|
The install_ref parameter specifies if the Google Install Referrer Information. The install referrer contains information about who sent a user to the Google Play Store. When the install referrer is available to Singular, it provides the most accurate way to attribute installs. Retrieve this value and pass it along to Singular on the first session notification call. It is required for some important Singular features, such as receiving Facebook data in our User-Level Exports, sharing it with Data Destinations, and sending postbacks. Google Play collects referrer information when a user arrives at the store. If the user later installs the app they were directed to, Google Play makes the information available to the app. For more information, see Google's developer documentation. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The meta_ref parameter specifies the "Meta Referrer" which is an Android-specific measurement solution introduced by Facebook to allow advertisers access to granular user-level attribution data for Android app installs (see Facebook's data policies). It is comprised of implementing both "Google Play Install Referrer" (see "Passing Google Install Referrer") and "Meta Install Referrer" technologies for app install measurement. Read more about Meta Referrer in the FAQ on the topic. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The attribution_token parameter specifies the Apple Search Ads attribution token retrieved on iOS 14.3+ via the AdServices framework. Retrieve the attribution token using attributionToken() as soon the app initializes for the first time after an install or reinstall. Example Value: |
Request Body
Do not provide a request body when calling this method. The request must be sent using the GET method with query parameters.
Request Examples
The following code samples may not represent all supported parameters. When implementing the request be sure to include all required parameters as listed above, and validate that the correct values are being passed before sending data from a production instance. It is advised to uses a unique `i` parameter (application identifier) for development and testing.
PYTHON
import requests
params = {
'a': 'sdk_key_here',
'p': 'Android',
'i': 'com.singular.app',
'ip': '10.1.2.3',
've': '9.2',
'ma': 'samsung',
'mo': 'SM-G935F',
'lc': 'en_US',
'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
'install': 'true',
'n': 'MyCoolAppName',
'bd': 'Build/13D15',
'app_v': '1.2.3',
'openuri': 'myapp://home/page?queryparam1=value1',
'ddl_enabled': 'true',
'install_source': 'com.android.vending',
'install_time': 1510040127,
'update_time': 1510090877
}
response = requests.get('https://s2s.singular.net/api/v1/launch', params=params)
print(response.json())CURL
curl -G "https://s2s.singular.net/api/v1/launch" \
--data-urlencode "a=sdk_key_here" \
--data-urlencode "p=Android" \
--data-urlencode "i=com.singular.app" \
--data-urlencode "ip=10.1.2.3" \
--data-urlencode "ve=9.2" \
--data-urlencode "ma=samsung" \
--data-urlencode "mo=SM-G935F" \
--data-urlencode "lc=en_US" \
--data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
--data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
--data-urlencode "install=true" \
--data-urlencode "n=MyCoolAppName" \
--data-urlencode "bd=Build/13D15" \
--data-urlencode "app_v=1.2.3" \
--data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
--data-urlencode "ddl_enabled=true" \
--data-urlencode "install_source=com.android.vending" \
--data-urlencode "install_time=1510040127" \
--data-urlencode "update_time=1510090877"HTTP
GET /api/v1/launch
?a=sdk_key_here
&p=Android
&i=com.singular.app
&ip=10.1.2.3
&ve=9.2
&ma=samsung
&mo=SM-G935F
&lc=en_US
&aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
&asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
&install=true
&n=MyCoolAppName
&bd=Build%2F13D15
&app_v=1.2.3
&openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
&ddl_enabled=true
&install_source=com.android.vending
&install_time=1510040127
&update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json
JAVA Example
// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/launch";
// Parameters
Map < String, String > params = new HashMap < > ();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");
// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');
for (Map.Entry < String, String > entry: params.entrySet()) {
if (urlBuilder.length() > baseUrl.length() + 1) {
urlBuilder.append('&');
}
urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");
// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(conn.getInputStream())
);
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in .readLine()) != null) {
response.append(inputLine);
} in .close();
// Check application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
// Disconnect
conn.disconnect();
Optional Parameters
The following table lists the optional parameters that this endpoint supports. All of the parameters listed are query parameters.
| Optional Parameters | |
|---|---|
| Timestamp Parameters | |
| Parameter | Description |
|
The utime parameter specifies the Time of the session in 10 digit UNIX time.
Example Value: |
| Parameter | Description |
|
The umilisec parameter specifies the of Time of the session in milliseconds 13 digit UNIX time.
Example Value: |
| Device & Network Parameters | |
| Parameter | Description |
|
The global_properties parameter accepts a URL-encoded JSON object containing up to 5 key-value pairs. Each key and value can be a maximum length of 200 characters. The JSON Object must be:
Example Value: |
| Parameter | Description |
|
The use_ip parameter tells Singular to extract the IP Address from the HTTP request instead of the 'ip' parameter. Pass 'true' to use this feature.
Example Value: |
| Parameter | Description |
|
The country parameter should contain the ISO 3166-1 alpha-2 two-letter country code of the user at the time of the session execution. This parameter is required only when:
Example Value: |
| Parameter | Description |
|
The ua parameter specifies the User Agent of the device. The value must be URL-encoded.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The c parameter specifies the Network Connection type 'wifi' or 'carrier'.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The cn parameter specifies the Carrier name of the internet provider.
Example Value: |
| Uninstall Tracking Support | |
| Parameter | Description |
Supported Platforms:
|
The apns_token parameter specifies the Apple Push Notification Service (APNS) Device Token.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The fcm parameter specifies the Firebase Cloud Messaging Device Token.
Example Value: |
| Data Privacy | |
| Parameter | Description |
|
The data_sharing_options parameter specifies the end-user's consent to share information. If set, this value must be persisted and passed on every subsequent 'SESSION' and 'EVENT' request for the user.
The value must be a URL-encoded JSON String.
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The dnt parameter specifies the status of Do Not Track. Pass 1 if do not track is enabled or 0 if do not track is disabled. Example Value: |
| Parameter | Description |
Supported Platforms:
|
The dntoff parameter specifies if Do Not Track is Off. Pass 0 if "do not track" is enabled or 1 if "do not track" is disabled. Example Value: |
| Cross Device Support | |
| Parameter | Description |
|
The custom_user_id parameter specifies your internal User ID.
Example Value: |
| iOS SkAdNetwork Support | |
| Parameter | Description |
Supported Platforms:
|
The skan_conversion_value parameter specifies the latest SKAdNetwork conversion value at the time of this session notification (learn more about SKAdNetwork implementation).
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The skan_first_call_timestamp parameter specifies the Unix timestamp of the first call to the underlying SkAdNetwork API (learn more about SKAdNetwork implementation).
Example Value: |
| Parameter | Description |
Supported Platforms:
|
The skan_last_call_timestamp parameter specifies the Unix timestamp of the latest call to the underlying SkAdNetwork API at the time of this session notification (learn more about SKAdNetwork implementation).
Example Value: |
Session Testing
After integrating the server-to-server integration, it is essential to verify that Singular receives data before you go live with a product instance. Refer to our testing guide for more details. At a high level the following steps should be followed:
- Obtain your test device Advertising ID and add the ID in the Singular SDK Console.
- Open the Singular SDK Console and add the device identifier to start capturing data.
- Override the App Identifier with a development App Identifier (com.singular.app.dev) to keep test data and events separate from production data.
- Build or Open the App from a terminated state
- Validate the App Open is sent to your server with all required Singular data points
- Validate your server triggers the Session Notification to the Singular 'launch' endpoint with all required data points.
- After a few seconds, the Session event should be displayed in the Singular SDK Console.
- Repeat the test, to validate that the App Open triggers the Session from every App entry or “Foreground” operation.
Confirm that the Session Event occurs on App Open or to Foreground and before the Event is received.
If you see the Session in the SDK Console, you have completed an end-to-end test of SESSION handling!