Tracking Ad Revenue API Reference
Server-to-Server Use Case
Singular enables tracking ad revenue via the EVENT API. By forwarding impression-level revenue details from your mediation platform(s) to your server using paid event handlers, Singular processes this data for seamless integration into reports, export logs, and postbacks. The platform also supports automatic currency conversion aligned with your organization’s preferred settings.
The Singular REST API enables direct server-to-server integration as an alternative to the SDK. While the SDK automatically collects device and app data, the S2S approach requires you to:
- Collect required EVENT API data points from your app
- Collect relevant mediation platform data points
- Forward this data to your server
- Send the '__ADMON_USER_LEVEL_REVENUE__' Event to Singular via REST API
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.
Prerequisites
- A Session must be established before any event tracking is received
- Invalid session order will result in data inconsistencies
- Collect Mediation Platform data attributes directly from the Mediation SDK. For implementation details and required data points, refer to our SDK Guide and platform-specific Mediation documentation.
Getting Started
The EVENT endpoint documentation provides:
This server-side approach gives you more control over your integration while maintaining all SDK capabilities.
Event API Endpoint
HTTP Method and Event Endpoint
GET https://s2s.singular.net/api/v1/evt
Required Parameters
The table below lists the required parameters for sending Ad Monetization Revenue events via the Event API. These parameters should be included as query parameters.
GET /api/v1/evt?param1=value1¶m2=value2
- All required parameters must be included in EVENT 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:
|
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 event time. Example Value:
|
Application Parameters | |
Parameter | Description |
|
The i parameter specifies the App Identifier. This is a case-sensitive value:
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:
|
Event Parameters | |
Parameter | Description |
|
The n parameter specifies the Name of the event being tracked.
|
Parameter | Description |
|
The e parameter specifies custom event attributes in JSON format. The only required attribute is the 'ad_platform'. All other attributes are optional. The possible attributes are:
Note: Attributes without values should be omited.
Example Value:
|
Parameter | Description |
|
The is_admon_revenue parameter specifies whether the event is an Ad Monetization revenue event and should be used for Ad Revenue Metrics.
Example Value:
|
Parameter | Description |
|
The is_revenue_event parameter specifies whether the event is a revenue event and should be used for Revenue Metrics.
Example Value:
|
Parameter | Description |
|
The amt parameter specifies the currency amount.
Example Value:
|
Parameter | Description |
|
The cur parameter specifies the uppercase ISO 4217 three-letter currency code.
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 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',
'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
'n': '__ADMON_USER_LEVEL_REVENUE__',
'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
'is_admon_revenue':'true',
'is_revenue_event':'true',
'amt':0.00782,
'cur':'USD'
}
response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())
CURL
curl -G 'https://s2s.singular.net/api/v1/evt' \
--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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
--data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
--data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
--data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
--data-urlencode "is_admon_revenue=true" \
--data-urlencode "is_revenue_event=true" \
--data-urlencode "amt=0.00782" \
--data-urlencode "cur=USD"
HTTP
GET /api/v1/evt
?a=sdk_key_here
&p=Android
&i=com.singular.app
&ip=10.1.2.3
&ve=9.2
&aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
&asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
&n=__ADMON_USER_LEVEL_REVENUE__
&e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
&is_admon_revenue=true
&is_revenue_event=true
&amt=0.00782
&cur=USD HTTP/1.1
Host: s2s.singular.net
Accept: application/json
JAVA Example
// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";
// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");
// 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 | |
---|---|
Device & Network Parameters | |
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 event execution. This parameter is required only when:
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:
|
Cross Device Support | |
Parameter | Description |
|
The custom_user_id parameter specifies your internal User ID. Example Value:
|
Event Testing
After integrating the server-to-server integration, it is essential to verify that Singular receives data before you go live with a production 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.
- Proceed to triggering an Event in the App.
- Validate that the Event is sent to your server with all required Singular data points
- Validate your server triggers the Event Notification to the Singular 'evt' endpoint with all required data points.
- After a few seconds, the Event should be displayed in the Singular SDK Console.
- Repeat the test, to validate all events are sent as expected and with the expected values.
Important Verifications
- Confirm that the Session Event occurs on App Open or to Foreground and before the Event is received.
- Confirm that the Event required data points, match the Session data points.
- Confirm the correct Mediation Platform details are passed in the Event Arguments
- Confirm the correct Revenue Amount and Currency
If you see your Events in the SDK Console, you have completed an end-to-end test of Event handling!