RadiumOne Mobile Analytics Event Tracker Endpoint  (API)

Introduction

RadiumOne currently has two mechanisms in order to track in-App mobile data and allow segmentation of that data into our DMP:

  • RadiumOne RadiumOne Mobile Analytics SDK (iOS, Android)
  • RadiumOne Event Tracker EndPoint

If for some reason you cannot use the RadiumOne RadiumOne Mobile Analytics SDK, this Endpoint provides an alternative path to integrate either directly from your app or server to server.

This endpoint accepts data that is formatted in a JSON format with well-defined parameters. 

Registering your application in RadiumOne RadiumOne Mobile Analytics

In order to be able to track your application and make use of it, you need to register it in RadiumOne RadiumOne Mobile Analytics. It is easy to do.

You access RadiumOne RadiumOne Mobile Analytics here: connect.radiumone.com

Once you are registered, you can create a new app through the RadiumOne Mobile Analytics process. Then you can access the information that you will need from the settings view.

You will want to retrieve the application id field, as it is necessary for data to be processed. The format of the application id is a GUID and it will look like this: 8E19B036-3848-4AB7-A21A-536B70A5C0A6

Please note that the previous value is an example.

Endpoint information

In order to pass information to RadiumOne, you need to use the following endpoint:

Staging: https://rp-stg.gwallet.com/r1t/evt3/#{application_id}?v=2

Production: https://rp.gwallet.com/r1t/evt3/#{application_id}?v=2

{application_id} is the value that RadiumOne RadiumOne Mobile Analytics has assigned to you through the UI. All calls should be made to this dynamic endpoint. This will allow the data to flow into the system.

All data should be passed as POST and should be sent as HTTPS.

Responses

If the data passed via the POST query is correct, you will receive a 200 response with the message “Well done” or else you will see “Bad Request”

Event details

The system has several events that are defined by default. Any system put in place should replicate these events.

Here are the automatic events that the SDK supports:

  • Launch- emitted when the app starts
  • First Launch- emitted when the app starts for the first time
  • First Launch After Update- emitted when the app starts for the first time after a version upgrade
  • Application Opened- This event is very useful for push notifications and can measure when your app is opened after a message is sent.

Similarly, it is possible to create your own events based on the event data structure.

Each of these events will be detailed in Appendix A to explain how they should actually be filled. 

Pre-conditions and System setup

Before you send any data, please ensure the following,

  • Utilize persistent HTTPS connections
  • Limit 1,000 QPS or 250 Mbps per connection 
  • Combine multiple events from a given device into a single HTTPS POST message (up to 1MB in size)

·      The endpoint can support in the range of 50,000 QPS

·      Currently we do not support event de-duplication on the logger side, so it depends on how duplicate events are handled on the data processing side.

 

Rules for posting data

 

  • App UUID must be valid and the app must be active
  • “source” field is required
  • “event_info” - at least one event must be present
  • “event_info.event_name” must be non-empty
  • “device_info.id_info” - at least one device ID must be present
  • “event_info.transaction_id” is required
  • “event_info.timestamp” is required
  • “event_info.key_value.key” is required (if “event_info.key_value” is present)

RadiumOne Mobile Analytics Key Name

Type

Sample Value

Default behavior

Description

Mandatory

application_id

String
application_name (bundle_name)
If (null) ERROR

Combination of application name and bundle name

Y

application_name

String

MYAPP

null

This is the name of the application

Y

application_version

String

3.0.9.1

Null

This is the version number for your application

Y

bundle_name

String

com.bundlename

null

This is the name of the bundle

Y

carrier_country

String

fr

null

This is the ISO 3166-1 Alpha 2 code

Y

carrier_name

String

Free

null

This is the name of the cell phone carrier

Y

conn_type

String

WIFI

null

This is the type of data connection

N

device_info

JSON Object

 

null

This is the device information structure. The structure will be explained further down

N

event

JSON Object

 

null

This is the list of events that you are sending

N

screen_resolution

String

1024x768

null

This is the screen resolution of the device

N

sdk_version

String

partner ID value

null

This is the version of your SDK

Y

source

String

ADVERTISER_SDK

"ADVERTISER_SDK"

This is the source of the information contained in the payload. This parameter is MANDATORY

Y

user_language

String

fr

null

This is the ISO 3166-1 Alpha 2 code

N

viewport_size

String

400x300

null

This is the actual size of the viewport of the app

N

device_type String Handheld | Tablet null Device Type accepts 3 enums [tablet, handheld, null] N
version String 2 2 Version Y

Device_info Mapping Table

Key Name

Type

Sample Value

Default value

Description

Mandatory

os

String

iPhone OS

null

This is the name of the OS running on the phone

Value MUST be "iOS",  "Android", or "Windows".

Y

Os_version

String

8.1.3

null

This is the version of the OS running on the phone

N

Os_language

String

fr

"en"

This is the ISO 3166-1 Alpha 2 code

N

Ip_v4

String

3.0.9.1

null

This is the ipv4 of the device

Y

Ip_v6

String

 

null

This is the ipv6 of the device

N

make

String

Apple

null

This is the name of the maker

Y

model

String

iPhone

null

This is the name of the device

Y

Timezone_offset

Integer

-25200

0

This is the timezone offset in seconds

N

country

String

fr

null

This is the ISO 3166-1 Alpha 2 code

Y

Id_info

JSON Object

 

null

This is the device information structure. The structure will be explained further down

Y

user_agent String "Mozilla/5.0 (iPad; CPU OS 9_1 like Mac OS X) " null This is a device user agent. N

ID_info Mapping Table

Key Name

Type

Sample Value

Default values

Description

Mandatory

Dpid

String

9AEF8C48-91F3-47A9-A400-B474621CFC0D

null

This is the device id of the device (either idfa, aid, wpid)

Y

 

Dpid_sha1

String

897a26ccf206628432d1667845e11b0cec0fee21

null

This is the sha1 value for dpid

Y

Dpid_md5

String

163fb576035dd3cfb9c01dd43f0e862c

null

This is the md5 value for dpid

Y

aid

String

 

null

This is the Google Advertising Identifier (sometimes called GAID in the industry)

Y

Adv_id

String

 

null

This is android advertising id.  Since Android ID is deprecated and the field is mandatory, most clients send GAID a second time.

Y

Idfa

String

9AEF8C48-91F3-47A9-A400-B474621CFC0D

null

This is the idfa value for Apple

Y

Idfv

String

EA8AA54A-8BDF-4D6F-B760-703CA1820BFB

null

This is the idfv value for Apple

Y

Opt_out

Boolean

false

false Tells the system whether the user has opted out of tracking or not.

N

Bluetooth_status

String

 

null

This is the status of the Bluetooth code

N

Locale

String

 En-US

En-US

This is the locale of the device

 

Event Mapping Table

Key Name

Type

Sample Value

Description

Mandatory

Event_name

String

MyEventName

This is the name of the event.

Y

Transaction_id

String

1222

This is the transaction id, must be unique per transaction.

Y

Timestamp

Long

1431582994837

Epoc timestamp (MUST BE MILLISECONDS)

Y

Key_value

 

 
JSON Array
{
key_value: "title",
string_value: "Intro to Analytics"
}

This is the structure used to pass extra parameters.

Y

Lat

Long

nul

This is the latitude of the device
OUTPUT = (lat X 1,000,000) 

N

Lon

Long

null

This is the longitude of the device
OUTPUT = (lon X 1,000,000)

N

Session_id

String

4E5C09B7-73E5-406F-8140-13751FB62B1B

This is the session id (GUID)

Y

Speed

String

null

This is the speed of the device

JSON payload structure

The JSON payload should have the following structure. Please note that some parameters are optional and dependent on the platform. The actual meaning of the parameters is explained later in a table. The JSON structure is also pretty complex and will be decomposed.

Actual examples will be provided as separate files with this document in order to make it clear. Here is the list of all elements at root level. Please note that when fields are not filled, they should be appearing with a null value. All parameters are also actual string except for one exception. Nested structures will be present in subsequent tables:

JSON format (example)

Comments after //, (M)= Mandatory fields, (O)= Optional fields

{

    "application_id": "9E7662CA-2E05-41AB-8E4C-50E9F626FF49", // This is the ID available on Settings page on the Portal (M)

    "application_name": "MyApp",                                                           // This is the name of your App (O)

    "application_user_id": "",                                                                     // This can be null (O)

    "application_version": null,                                                                  // This is the version of your App if available, or else null (O)

    "bundle_name": "testbundle",                                                            // Please add the bundle id of your app or leave as test (O)

    "carrier_country": null,                                                                          // Please add carrier country if available, else null (O)

    "carrier_name": null,                                                                            // Please add carrier name if available, else null (O)

    "conn_type": "WIFI",                                                                             //  Please add connection type if available, else null (O)               

    "device_info": {   

        "country": "US",                                                                                 // Please add the country of the App download (M)

        "id_info": {       

            "adv_id": null,                                                                                 // Please add Android advertiser ID if Android, else null (O)

            "aid": null,                                                                                        // Please add Android ID if Android, else null (O)

            "dpid": "9B445DD3-8510-46C2-A534-4552F07BF942",        // Please add IDFA if iOS, aid or Adv_id if Android (M)

            "dpid_md5": null,                                                                          // Please add md5 hash of dpid (O needed for Install Tracking)

            "dpid_sha1": null,                                                                         // Please add sha1 hash of dpid (O needed for Install Tracking)

            "idfa": "9B445DD3-8510-46C2-A534-4552F07BF942",        // Please add IDFA if iOS (O)

            "idfv": null,                                                                                     // Please add IDFV if iOS and Opt out is true (O)

            "opt_out": false,                                                                            // Please add condition of user for tracking (M)

            "production_live": null,                                                               // null for S2S

            "r1_daid": null                                                                              // null for S2s

        },

        "ip_v4": null,                                                                                      // Please add of IPv4 Address (O)

        "make": null,                                                                                       // Please add make of device (O)

        "model": null,                                                                                    //  Please add model of device (O)

        "os": "iPhone OS",                                                                           // Please add OS of device (M)       

        "os_language": "en",                                                                       // Please add OS Language of device (M)

        "os_version": null,                                                                           // Please add OS version of device (O)

        "timezone_offset": null                                                                  // Please add timezone offset (O)

    },

    "device_type": "HANDHELD",                                                           // Please add device type (O)

    "event_info": [

        {

            "event_name": "Application Opened",                                    // Please add event name (M)

            "key_value": [

                {

                    "key": "Engagement Type",                                                 // Please add key of custom attribute qualifying event (O)

                    "string_value": "Super High "                                            // Please add value of custom attribute qualifying event (O)

                },                                                                                                    // Use string_value if string, else double_value if double format            

                {

                    "key": "network_name",                                                 // The name of the ad network that drove the user's install.  This is required to be able to segment by attribution but can otherwise be left out.

                    "string_value": "RadiumOne"                                            // Replace this with the name of the DSP, network, or exchange.   This is required to be able to segment by attribution but can otherwise be left out.

                },

                {

                    "key": "tracker_name",                                                 // The name of the campaign that this user's install was attributed to.  This is required to be able to segment by attribution but can otherwise be left out.

                    "string_value": "Campaign name here"                                            //  This is required to be able to segment by attribution but can otherwise be left out.

                },

                {

                    "key": "site_id",                                                 // The name of the website or app where the ad that the end user clicked on before installing was placed. This is required to be able to segment by attribution but can otherwise be left out.

                    "string_value": "Site name here"                                            // This is required to be able to segment by attribution but can otherwise be left out.

                }

            ],                                       

            "lat": 340043,                                                                              // Please add latitude if available (multiplied by 10000) (O)          

            "lon": -1184324,                                                                        // Please add longitude if available (multiplied by 10000) (O)

            "session_id": "AA",                                                                     // Please add non null value for session id (M)

            "timestamp": 1431579614885,                                                               // Please add epoch timestamp of client event generation (M)

            "transaction_id": "1439830721"                                                             // Please add a non null value for transaction id (M)

        }

    ],

    "sdk_version": "S2S",                                                                         // Please add sd_version as S2S always (M)   

    "source": "ADVERTISER_SDK",                                                         // Please add source as ADVERTISER_SDK always (M)

    "user_language": "en",                                                                       // Please add user language (O)

    "version": "2",                                                                                     // Please add version as 2 (M)

    "viewport_size": null                                                                          // Please add viewport_size if available, else null (O)

}

 

If you post the above event to the endpoint you will receive a 200 response with the message ‘well done!’

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk