Server-to-Server Tracking Ad Revenue API Reference

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:

  1. Collect required EVENT API data points from your app
  2. Collect relevant mediation platform data points
  3. Forward this data to your server
  4. 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&param2=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
a
string

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:
sdkKey_afdadsf7asf56
Device Identifier Parameters
Parameter Description
idfa

Supported Platforms:

  • iOS
string

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:
DFC5A647-9043-4699-B2A5-76F03A97064B
Parameter Description
idfv

Supported Platforms:

  • iOS
string

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:
21DB6612-09B3-4ECC-84AC-B353B0AF1334
Parameter Description
aifa

Supported Platforms:

  • Android
    (Google Play Devices)
string

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.

  • If the AIFA is unavailable then omit the parameter from the request.
  • Only required on Google Play Devices.
  • Omit the parameter on Non-Google Play devices.
  • Do not pass NULL or empty string in the request.
  • How to retrieve the AIFA Identifier

 

Example Value:
8ecd7512-2864-440c-93f3-a3cabe62525b
Parameter Description
asid

Supported Platforms:

  • Android
    (Google Play Devices)
string

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.

  • The ASID is required on all request for Google Play Devices, regardless of GAID/AIFA presence.
  • Omit the parameter on Non-Google Play devices.
  • Do not pass NULL or empty string in the request.
  • How to retrieve the ASID Identifier

 

Example Value:
edee92a2-7b2f-45f4-a509-840f170fc6d9
Parameter Description
amid

Supported Platforms:

  • Android
    (Amazon Devices without Google Play Services)
string

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.

  • The AMID is required on all request for Amazon Devices without Google Play Services.
  • Omit the parameter if AMID is unavailable.
  • Do not pass NULL or empty string in the request.
  • How to retrieve the AMID Identifier

 

Example Value:
df07c7dc-cea7-4a89-b328-810ff5acb15d
Parameter Description
oaid

Supported Platforms:

  • Android
    (Chinese-manufactured Devices without Google Play Services)
string

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).

  • The OAID is required on Chinese-manufactured Android devices without Google Play Services.
  • Omit the parameter if OAID is unavailable.
  • Do not pass NULL or empty string in the request.
  • How to retrieve the OAID Identifier

 

Example Value:
01234567-89abc-defe-dcba-987654321012
Parameter Description
andi

Supported Platforms:

  • Android
    (Non Google Play devices)
string

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.

  • The ANDI is prohibited for use on Google Play Devices. Use the AIFA and ASID identifiers mentioned above.
  • The ANDI may be sent to Singular only if no other identifiers are available, and the App is not hosted on Google Play Store.
  • Omit the parameter if other identifiers are available.
  • Do not pass NULL or empty string in the request.
  • How to retrieve the ANDI Identifier

 

Example Value:
fc8d449516de0dfb
Device Parameters
Parameter Description
p
string

The p parameter specifies the platform of the App.

The following list contains the allowed case-sensitive parameter values:

  • Android
  • iOS

 

Example Value:
Android
Parameter Description
ip
string

The ip parameter specifies the public (IPV4) IP Address of the device. IPV6 is not supported.

Example Value:
172.58.29.235
Parameter Description
ve
string

The ve parameter specifies the OS Version of the device at event time.

Example Value:
9.2
Application Parameters
Parameter Description
i
string

The i parameter specifies the App Identifier.

This is a case-sensitive value:

  • Package Name for Android
  • Bundle ID for iOS

Example Value:

com.singular.app
Parameter Description
att_authorization_status

Supported Platforms:

  • iOS
int

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:

  • 0 - Undetermined.
  • 1 - Restricted, the user disabled app tracking.
  • 2 - Denied, the user denied authorization.
  • 3 - Authorized, the user granted authorization.

Examples:

3
Event Parameters
Parameter Description
n
string

The n parameter specifies the Name of the event being tracked.

  • Supporting AdMon Revenue requires the Event Name to be a specific value.
  • Event Name must be ALL UPPERCASE with underscores.
Use the following Event Name:
__ADMON_USER_LEVEL_REVENUE__
Parameter Description
e
JSON URL-encoded string

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:

  • ad_platform -- REQUIRED
  • ad_mediation_platform
  • ad_type
  • ad_group_type
  • ad_impression_id
  • ad_placement_name
  • ad_unit_id
  • ad_unit_name
  • ad_group_id
  • ad_group_name
  • ad_group_priority
  • ad_placement_id

 

Note: Attributes without values should be omited.

{
   "ad_platform":"AdMob",
   "ad_mediation_platform":"admob.AdMobAdapter",
   "ad_unit_id":"ca-app-pub-6325336052\/44923540"
}

Example Value:

%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%5C%2F44923540%22%7D
Parameter Description
is_admon_revenue
string

The is_admon_revenue parameter specifies whether the event is an Ad Monetization revenue event and should be used for Ad Revenue Metrics.

  • Pass 'true' for this event.

 

Example Value:

true
Parameter Description
is_revenue_event
string

The is_revenue_event parameter specifies whether the event is a revenue event and should be used for Revenue Metrics.

  • Pass 'true' for this event.

 

Example Value:

true
Parameter Description
amt
double

The amt parameter specifies the currency amount.

  • This should be used in conjunction with the 'cur' parameter.

 

Example Value:

0.00782
Parameter Description
cur
string

The cur parameter specifies the uppercase ISO 4217 three-letter currency code.

  • This should be used in conjunction with the 'amt' parameter.

 

Example Value:

USD

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 CURL HTTP JAVA

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())

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
use_ip
string

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.

  • Using this parameter prevents Singular from geo-locating the device based on IP Address. You may supply the two-letter country code of the user in the optional 'country' parameter.
  • This parameter is mutually exclusive to the 'ip' parameter. DO NOT use this with the 'ip' parameter.
  • To avoid data rejection, you must supply either 'ip' or the 'use_ip' parameter on the request.

 

Example Value:

true
Parameter Description
country
string

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:

  • The 'ip' parameter is not available
  • If the 'ip' parameter is available, the country will be automatically determined from the IP address, and the 'country' parameter is not needed.

 

Example Value:

US
Data Privacy
Parameter Description
data_sharing_options
JSON URL-encoded string

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.

  • To indicate that the user consented (opted-in) to share their information pass 'false':
    {"limit_data_sharing":false}
  • If the user refused then pass 'true':
    {"limit_data_sharing":true}

The value must be a URL-encoded JSON String.

Example Value:

%7B%22limit_data_sharing%22%3Atrue%7D
Cross Device Support
Parameter Description
custom_user_id
string

The custom_user_id parameter specifies your internal User ID.

Example Value:

123456789abcd

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:

  1. Obtain your test device Advertising ID and add the ID in the Singular SDK Console.
  2. Open the Singular SDK Console and add the device identifier to start capturing data.
  3. Override the App Identifier with a development App Identifier (com.singular.app.dev) to keep test data and events separate from production data.
  4. Build or Open the App from a terminated state
  5. Validate the App Open is sent to your server with all required Singular data points
  6. Validate your server triggers the Session Notification to the Singular 'launch' endpoint with all required data points.
  7. After a few seconds, the Session event should be displayed in the Singular SDK Console.
  8. Proceed to triggering an Event in the App.
  9. Validate that the Event is sent to your server with all required Singular data points
  10. Validate your server triggers the Event Notification to the Singular 'evt' endpoint with all required data points.
  11. After a few seconds, the Event should be displayed in the Singular SDK Console.
    s2s_admon.png
  12. 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!