Testing Console API Reference [BETA]

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:

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:
  • The log will show up to 100 events. If you have more than 100 events to test, you will need to retrieve the logs multiple times.
  • The device registration expires after an hour. If you need more time to execute your events, call Register Device again (see API Constraints and Limitations).
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
HTTP 200

{
    “status”:0,
    “message”: “Device registered”,
    “log_session_info”: [session_id, session_start_timestamp, session_expire_timestamp]
}
The device is registered and the console is ready to start logging events from the device.
HTTP 307
            
Header: Retry After <delay seconds>
        
{
    “status”:1,
    “session_id”,
    “message”:”Device registration
in progress, retry after
x seconds” }
The device is registered but the console is not ready to log events. Wait the required number of seconds and check again.
HTTP 404
            
{
    “status”:”3”,
    "message”:”Device not registered”
}
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):

  1. 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.
  2. 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.
  3. 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.
  4. The API can receive up to 20 requests per second.