What's in a mPulse Beacon? (Mobile Apps)

What’s in a mPulse Beacon? (Mobile Apps)

Documentation on the mPulse Native SDKs can be found here:

When active, the mPulse Native SDKs send Beacons, which are are invisible network requests that contain performance data and other device characteristics.

In this document, we will describe the various parameters collected via the mPulse Native SDK beacons as well as how they are mapped to other parts of mPulse such as S3 and Snowflake.

Top Level Fields

Field S3 Snowflake Examples Description
Beacon ID id beaconId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Beacon GUID
Batch ID batch xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Batch ID
Domain ID domainid appid 123 Registered domain ID
Timestamp timestamp timestamp 1512086400000 Server timestamp when beacon arrived (Unix epoch)
IP remote_ip remoteip 1.2.3.4 IP Address of the end user (or the proxy they are connected through)
API Key key XXXXX-XXXXX-XXXXX-XXXXX-XXXXX mPulse API Key assigned to this domain
Beacon HTTP Method http_method GET POST HTTP Request method used to send the beacon (for internal use only)
Beacon HTTP Version http_version HTTP/1.1 HTTP Version used to send the beacon (for internal use only)
Beacon IPv6 ipv6 ipv6 true Set to true if the beacon was sent using IPv6 (for internal use only)
Beacon Type beacon_type beacontypename client_batch api_custom_metric api_custom_timer
api_network_request app_action
Type of beacon
Page Group / View Group page_group pagegroupname Home Orders PDP (No Page Group) View Group
A/B Test name ab_test abtestname A B If the app uses A/B Testing, this variable specifies the test bucket the user was in when they sent the beacon
Site/App Version site_version siteversionname 1.0 30.0.0 Version of the app installed on the user’s device.
Warnings warnings warnings ["clock:askew"] Array of warnings added by the collector when parsing this beacon
SSL ssl ssl true If SSL was used to send the beacon (for internal use only)
API Status api true Always true for mobile apps
Compression Types compression_types gzip Compression types supported by the remote device
Mobile Connection Type mobile_connection_type mobileConnectionType Ethernet WiFi 2G 3G 4G LTE Mobile connection type

Session

The following fields live under the session: {} object in S3.

Session S3 Snowflake Examples Description
Session ID ID sessionid xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-nnnnnn Session ID generated by mPulse.

The first five chunks are a UUID, while the last chunk is the base36 representation of the session start time based on the user’s clock.
Session Start Time start sessionstart 1512086400000 Session start time (Unix epoch) based on the device’s clock.

This clock may not be in sync with the server clock, so only compare it with other device timestamps.
Session Latest Time latest sessionlatest 1512086400000 The timestamp (Unix epoch) of the current beacon based on the user’s device’s clock.

It is not the timestamp of the latest beacon in the session.

To find out actual session duration, look at MAX(latest) - MIN(start) across all beacons grouped by Session ID.
Session Length
(in Beacons)
pages sessionpages 10 The number of beacons in this session up to and including the current beacons, but not including any beacons sent after this one in the same session.

To find out actual Session Length in beacons, look at MAX(pages) across all beacons grouped by Session ID.

If MAX(pages) == 1, then the session is considered a bounce.
Uncounted pages oboPages sessionobopages 0 The number of beacons in the session for which we were unable to calculate a load time.
Total Load Time totalLoadTime sessiontotalloadtime 2000 The sum of load times (in milliseconds) of all beacons within the session where we calculated load time.

The average load time of a session is MAX(totalLoadTime) / (MAX(pages) - MAX(oboPages)).
Unload flag isUnload sessionisunload true or missing false for all mobile beacons

User Agent Fields

The following fields come from the mobile device.

The following fields live under the user_agent: {} object in S3.

User Agent Fields S3 Snowflake Examples Description
OS Name os operatingsystemname Android iOS Operating System name
OS Version os_version operatingsystemversion 5.1.1 12.0.1 Operating System version
Model model devicename KFAUWI iPhone iPad Pro (12.9 inch, Wi-Fi) Device model
Manufacturer manufacturer devicemanufacturername Samsung LG Apple Device manufacturer
Device Type type devicetypename Mobile Tablet Device type

Geo Information

The following fields come from doing a MaxMind GeoIP lookup on the source IP address.

The following fields live under the geo: {} object in S3.

Geo Information S3 Snowflake Examples Description
Country cc countrycode US The user’s country (L1 geo info)
Region/State/Territory rg regioncode DC The user’s region, state, province, or territory (L2 geo info)
City city geocity Washington The user’s city (L4 geo info)
Postal Code postalcode geopostalcode 20009 The user’s postal/zip code
Latitude lat geolat 38.89791778 The user’s approximate latitude
Longitude lon geolon -77.03636593 The user’s approximate longitude
Organization org geoorg Comcast Cable Verizon Wireless The user’s organization, if connected over a corporate/university network
ISP isp geoisp Comcast Cable Virgin Media The user’s ISP
Network speed netspeed conntypename Cellular Ethernet Cable/DSL The advertised network grade of the user’s internet connection
Overwritten Location ovr true false Whether the mobile device’s location API was used to determine location (rather than the source IP address)

Timers

All timers are in milliseconds unless otherwise specified.

The following fields live under the timers: {} object in S3 unless otherwise specified.

Network Request Timers

Timers S3 Snowflake Examples Description
Request time t_done pageloadtime 100 Request fetch time

Custom Timers

Custom Timers are configured via the mPulse App config dialog, and may be sent by the Native SDKs.

S3 Snowflake Examples Description
custom[0-9] customtimer[0-9] 100 Custom Timer #[n]

Custom Metrics

Custom metrics are defined in the mPulse App config dialog, and may be sent via the Native SDKs.

In the S3 logs, these metrics are all numerically indexed. Example:

...
custom_metrics: {
    "0": 10,
    "5": 1
},
...

Metric values are always numeric.

S3 Snowflake Examples Description
0 custommetric[0-9] 1 Custom Metric #[n]

Custom Dimensions

Custom dimensions are defined in the mPulse App config dialog, and may be sent via the Native SDKs.

In the S3 logs, these dimensions are in the custom_dimensions array indexed by their dimension number. Dimensions that aren’t set may be null or missing (if no dimensions follow). Example:

...
custom_dimensions: [
    {
        "Region": "us",
        "alias": "United States"
    },
    null,
    {
        "Logged In": false,
        "alias": "False"
    }
],
...

Dimension values may be numeric, string or boolean.

S3 Snowflake Examples Description
(index 0) customdimension[0-9]value { "Region": "us", "alias": "United States" } Custom Dimension #[n]

Network Request Beacons

The following data applies to Network Request beacons.

The following fields live under the params: {} object in S3.

Field S3 Snowflake Examples Description
Resource URL u paramsu http://example.com/api/foo/bar Resource URL
HTTP Error Code http.errno networkerrorcode 404 Status code of the network request

Action Beacons

The following data applies to Action beacons.

Resources fetched during an Action are included on the params.restiming field. The compression is described at .

The following fields live under the params: {} object in S3, unless specified.

Field S3 Snowflake Examples Description
Action Name action_name (root) Login Action Name
Aborted State action.aborted false Whether or not the Action was aborted
Resource Data restiming see example Resource Data

Debugging Info and Timestamps

Other timestamps and related information, mainly used for debugging.

All timestamps are in (Unix epoch) unless otherwise specified.

The following fields live under the params: {} object in S3.

Debugging Info and Timestamps S3 Snowflake Examples Description
mPulse Native SDK Version v boomerangversionname 1.500.0 mPulse Native SDK version
Start Time rt.tstart paramsrttstart 1512086400000 Timestamp of start of the event, i.e. Network Request or Action
End Time rt.end paramsrtend 1512086400000 The timestamp when the t_done timer ended