In Summer 2023, we introduced a new major version of our iOS and Android collectors (v3). This doc describes the changes in this release.
Specific migration guides for each platform can be found here: iOS, Android
We wanted to improve our API in the following ways:
- Provide a clear separation of config and metadata
- Streamline collector behaviour in iOS and Android
- Use more intuitive field and method names
- Remove unnecessary configs and metadata fields
Each of these is described in more detail below.
Our v2 API lacked a clear separation of config and metadata. This made it cumbersome to use since the config doesn't change much over the lifetime of a collector but the metadata does. With v3 we've introduced a clear separation between metadata and config.
The config object
AnalyticsConfig contains the analytics license key and config fields that determine the collector behaviour. It doesn't contain any metadata to enrich analytics data itself.
Metadata is split into the objects
DefaultMetadata holds metadata that is source independent and doesn't change after creation of the collector (e.g.: customUserId, app version)
SourceMetadata holds source related metadata that is only relevant for a specific source (e.g.: title, videoId, genre)
Both have a
customData object which allows for arbitrary data to be collected together with each sample.
If the same field (e.g.
customData1) is specified in
SourceMetadata takes precedence. All
customData fields are merged on a field basis, with
SourceMetadata taking higher priority.
Our v2 API had some inconsistencies in field names and default behaviour when comparing iOS and Android.
For example, on iOS, ad tracking is disabled by default, while it's enabled by default on Android.
This behaviour was unified with v3.
API v2 has some confusing method names (e.g.:
setCustomDataOnce) which we tried to make easier to understand (e.g.:
sendCustomDataEvent). The same applies for some field names ( e.g.:
tryResendDataOnFailedConnection is now
API v2 has deprecated configs like
heartbeatInterval which are not part of the new
AnalyticsConfig to simplify setup.
With v3 we also removed some Metadata fields like
mpdUrl since they can be autodetected in most cases.
customData is specified in
SourceMetadata takes precedence. With the v3 API, this is done at the field level and not on the whole CustomData object anymore.
The example below illustrates how this works:
val customData1 = CustomData(customData1 = "appVersion1", customData2 = "exampleData")
val defaultMetadata = DefaultMetadata(customData = customData1)
val customData2 = CustomData(customData2 = "sourceData1", customData3 = "exampleGenre")
val sourceMetadata = SourceMetadata(title = "exampleTitle", customData = customData2)
// when the defaultMetadata is set and the sourceMetadata is active for the current source
// the resulting CustomData that is sent to the back end will look like this
CustomData(customData1 = "appVersion1", customData2 = "sourceData1", customData3 = "exampleGenre")
With API v2 only the
CustomData that was given as a parameter to the
setCustomDataOnce) method was sent to the backend.
Using the v3 API, the
CustomData that is specified as parameter is merged with the
CustomData that is sent with the current source. The specified
CustomData takes precedence and it's merged on a field-level.
The errorCodes reported are using the actual errorCodes as reported by ExoPlayer, instead of the error types. This allows for more specific error tracking and helps with debugging.
Updated 3 months ago