Swrve Events API payloads
You can add and send a custom event payload (swrve_payload) with every REST and SDK call to <app_id>.api.swrve.com (<app_id>.eu-api.swrve.com). This parameter is optional.
This feature enables graphing of low-cardinality data. For example, creating a histogram that shows the artist a user is currently listening to when a particular event is fired.
This associated payload should be a JSON object of key/value pairs. It is restricted to containing string or integers, and any values that use quotes (") need to have the quotes escaped (") to prevent errors in the QA device events log. For event payload examples, see the Swrve Events API guide.
Numeric bucketing
When displaying histograms for numeric values, it is assumed that those values map to a potentially very wide range, and therefore are not suitable for normal string-based bucketing. Swrve automatically buckets those values using the algorithm described below. This algorithm is applied to all payload values that can be parsed as numbers. The algorithm has the following features:
- It puts small integers in their own bins (to give clear low-cardinality histograms).
- It provides a reasonable bin around any possible data-point.
- The bins produced have round numbers as their edges.
The bucket edges the algorithm supports and the increments used between the edges are described below.
Small number bucketing algorithm
For numbers less than 10,000, the following algorithm applies:
| Input Range | Increments Used |
|---|---|
| >= 0, <0.01 | 0.001 |
| >= 0.01, < 0.1 | 0.01 |
| >= 0.1, < 1 | 0.1 |
| >= 1, < 50 | 1 |
| >= 50, < 100 | 5 |
| >= 100, < 200 | 10 |
| >= 200, < 500 | 50 |
| >= 500, <1,000 | 100 |
| >= 1,000, < 2,000 | 200 |
| >= 2,000, < 5,000 | 1,000 |
| >= 5,000, < 10,000 | 5,000 |
Negative numbers are binned in the same way, with negative buckets.
Large number bucketing algorithm
For numbers larger than 10,000, numbers are bucketed using the following algorithm:
For a number in scientific notation: XeY (that is, X * 10y)
- If x < 2: bucket is “1eY – 2eY”
- Elif x < 5: bucket is “2eY – 5eY”
- Else: bucket is “5eY – 1e(Y+1))”
Examples
Some sample input values and the buckets they would map to in this scheme are as follows (<input value> => <bucket>):
- 0.0000001 => 0
- 0.037 => 0.03 – 0.04
- 0.61 => 0.6 – 0.7
- 15 => 15
- 51 => 50 – 55
- 153 => 150 – 160
- 290.43 => 250 – 300
- 200503 => 200000 – 500000
- 2005030 => 2000000 – 5000000
- 1e20 => 100000000000000000000 – 200000000000000000000
Understanding the 500 key-value limit
There is a limit of 500 of unique payload key-value pairs per event.
Examples of this limit are as follows:
- One key with up to 500 values.
- Fifty (50) keys with up to 10 values each.
- One key with 400 values and a few other keys with a smaller number of values.
An example of four unique key/value pairs could be:
- colour:red,
- colour:blue,
- size:small,
- type: blue
These will count as four unique key-values towards the 500 key-value limit.
Avoiding numeric bucketing
Sometimes it is desirable to avoid bucketing numeric data. Swrve will bucket all data that can be numerically bucketed; for example:
- “height” : “251”,
- “height” : 274,
- “height” : 299
will all be bucketed as:
- “height” => “250 – 300”
If you want to avoid this numeric bucketing, you can add a non-numeric string prefix so that it’s treated as a string instead of a number. For example you could use “height”: “height-0251” instead of “height”: “251” or even simply “height”: “_0251”.
Payload limits
How many payloads can I send with an event?
See the Swrve Service Limits for details of the individual limits. You can send 10 payloads per event.
Limits on the payload key / value names
When you send a payload, the name of the key can have up to 255 characters, and the value can have up to 250 characters that are displayed in the dashboard. For example, for an event with a payload of ‘color’=’blue’, the key has a character count of five and the value has a character count of four, so both will be displayed without issue in the dashboard.
What happens if I send more than 500 unique key/value pairs?
After you exceed 499, subsequent payloads are dropped. Only the first 499 payloads are displayed in Swrve. The data is still available in raw event logs, but not in the dashboard histograms.
After the first 499 key value pairs, Swrve puts remaining pairs into the “other” bucket while continuing to increment the first 499. The only exception to this is if Swrve receives all of the different combinations within a few minutes of each other, in which case the combinations chosen may not be exactly the first 499.