This is a premium feature that needs to be enabled manually by your Solution Engineer or Customer Success Manager. Reach out to us for more info.
The Testing Console API is an alternative to the Testing console page in the Singular app. Both tools let you test your Singular SDK or S2S integration by showing you what data is sent from your device (a registered test device on which you install your app) to the Singular servers.
If the Singular SDK/S2S is integrated properly in your app, the device should be sending user sessions and events to Singular with all the properties you implemented.
For more information, see:
- How to Test Your Singular SDK Integration
- Auditing Tool for SDK/S2S Integrations
- Testing Console FAQ and Troubleshooting
Quick Start Guide
1 | Call the Register Device Endpoint to register your test device. |
2 | Wait 5 seconds and call Check Device Registration to see if the device has been registered and is ready to be logged. |
3 |
Once the device is ready to be logged, use the device to execute the app events you want to test. For more details about how to test different features of your SDK/S2S integration, see How to Test Your Singular SDK Integration. Notes:
|
4 | Call the Retrieve Logs endpoint to see what the device sent to Singular. |
5 | Optionally, call Unregister Device. If you don't, the device registration automatically expires after an hour has passed from the Register Device call. |
API Endpoint Reference
Register Device Endpoint
POST | api.singular.net/api/event_logger/device |
Usage
Use this endpoint to register a device in order to start a new logging session. The logging session will automatically expire after 1 hour.
Sample Call
POST 'https://api.singular.net/api/event_logger/device?api_key=<api-key>'
Request body:
{
"device_id": "058000d94-1972-448b-8c08-32c0ccc81fa4",
"keyspace": "AIFA",
"platform": "Android"
}
Query Parameters
Parameter | Required? | Description |
api_key | Required (if not passed in authorization header) | To get your Singular API key, log into your Singular account and go to Settings > API. Click Show Key and then Copy Key. |
device_id | Required | The ID of the test device that you are registering, e.g., 058000d94-1972-448b-8c08-32c0ccc81fa4 |
keyspace | Required | The type of device ID given, e.g., AIFA |
platform | Required | The device platform, e.g., Android |
Expected Response
Note: Even if the response indicates a successful registration (status 200), the console may still not be ready to log events. We recommend waiting 1 second then calling the “Check Device Registration” endpoint.
{
"status": 0,
"log_session_info":
{
"session_expire_timestamp": 1647448055,
"session_start_timestamp": 1647444455,
"session_id": "eceece6f-ef54-4f1a-8fe9-d3da1563c05a"
},
"registered_devices_num": 2
}
Check Device Registration Endpoint
GET | api.singular.net/api/event_logger/device |
Usage
Use this endpoint to check if a given device is registered in the Testing console. If the device is registered, and the logger is ready to begin collecting information from the device, you can start executing events on the app on the device to test them.
Query Parameters
Parameter | Required? | Description |
api_key | Required (if not passed in authorization header) | To get your Singular API key, log into your Singular account and go to Settings > API. Click Show Key and then Copy Key. |
device_id | Required | The ID of the device you have registered, e.g., 058000d94-1972-448b-8c08-32c0ccc81fa4 |
keyspace | Required | The type of device ID given, e.g., AIFA |
platform | Required | The device platform, e.g., Android |
Possible Responses
Response | Meaning |
|
The device is registered and the console is ready to start logging events from the device. |
|
The device is registered but the console is not ready to log events. Wait the required number of seconds and check again. |
|
The device is not registered, or the registration has timed out. Call the Register Device endpoint again. |
Retrieve Logs Endpoint
GET | api.singular.net/api/event_logger/retrieve_logs |
Usage
Use this endpoint to retrieve all Singular recorded events for the device, for the current session.
Query Parameters
Parameter | Required? | Description |
api_key | Required (if not passed in authorization header) | To get your Singular API key, log into your Singular account and go to Settings > API. Click Show Key and then Copy Key. |
device_id | Required | The ID of the device you are testing with, e.g., 058000d94-1972-448b-8c08-32c0ccc81fa4 |
keyspace | Required | The type of device ID given, e.g., AIFA |
platform | Required | The device platform, e.g., Android |
Query Response
Success: HTTP 200
{
“status”:0,
“Message”:”Request OK”
“log_session_info”: [session_id, session_start_timestamp, session_expire_timestamp]
“event_details”: [payload]
}
Unregister Device Endpoint
DELETE | api.singular.net/api/event_logger/device |
Usage
Use this endpoint to stop a logging session for a registered device.
Query Parameters
Parameter | Required? | Description |
api_key | Required (if not passed in authorization header) | To get your Singular API key, log into your Singular account and go to Settings > API. Click Show Key and then Copy Key. |
device_id | Required | The ID of the device you have registered, e.g., 058000d94-1972-448b-8c08-32c0ccc81fa4 |
keyspace | Required | The type of device ID given, e.g., AIFA |
platform | Required | The device platform, e.g., Android |
Possible Responses
Success: HTTP 200
{
“status”:0,
“message”:”Device unregistered”
“open_sessions_num”,
“log_session_info”: [session_id, session_start_timestamp, session_expire_timestamp]
}
Error: HTTP 400
{
“status”:”1”,
“message”:”Invalid request, check required fields”
}
HTTP 204
{
“status”:”2”,
“message”:”Device not registered”
}
API Constraints and Limitations
The API will have the following limitation for each client (api-key):
- Each logging-session is expired after 1 hour, after that, all the data on the logging-session’s events will be deleted and new data won’t be tracked. You can send another Register Device request on an already registered device to delay the expiration of the session by an hour.
- There can be only 50 open logging-sessions (for 50 devices) at a time, per api-key. On successful Register Device and Unregister Device requests, an open_sessions_num will be sent to help you monitor the number of open sessions.
- The maximum number of logged events per device is 100. After the limitation is reached, the older events will be removed from the log, to make space for the new ones.
- The API can receive up to 20 requests per second.