Radioplayer Developer Reference
Chromecast SDK
Technical reference for Radioplayer partner integrations.
This is the documentation for the Chromecast SDK, version 1.0.4.
General principles
The SDK allows the user to track events which will be collected by the Radioplayer Data Platform.
Babel Javascript preprocessor was employed to implement the automatic SDK. This approach includes the addition of tracking logic during the compilation phase of the application. The significance of this lies in the fact that the compilation takes place offline, so no additional performance overhead is incurred during application execution. By incorporating the tracking logic at the compilation stage, the solution ensures that the tracking elements seamlessly coexist with the application logic defined by the developer. This integration is crucial for maintaining a clean and coherent code base, allowing developers to articulate the application's functionality alongside the requisite tracking logic for comprehensive data collection. The Javascript pre-processor enables parsing of functions and classes, enabling the injection of tracking logic in tandem with the application's established logic. This ensures that tracking requirements are embedded alongside the intended functionality.
The SDK has been developed in accordance with the principles outlined in the Radioplayer Report – Automotive Tracking: SDK Principles v1.2 document.
Automatic code instrumentation
This section provides a comprehensive guide to automatically instrumenting code using the Chromecast SDK pre-processor to ensure a successful setup.
Supported development environments
Windows and Linux are officially supported as development environments. The SDK may work on MacOS but it is not officially supported yet.
The requirements for the self-instrumentation part are listed below:
Automatic code instrumentation dependencies
"@babel/core": "^7.16.0",
"@babel/generator": "^7.24.6",
"@babel/types": "^7.24.7",
"yargs": "^17.7.2",
"extensionless": "^1.9.9"
Run Time Dependencies
"@snowplow/browser-plugin-geolocation": "^3.20.0",
"@snowplow/browser-tracker": "^3.19.0",
"crypto-browserify": "^3.12.0",
Setup the SDK
- Place the
chromecast_rpsdkfolder in yoursource codefolder; - Move the
auto_instrumentationfolder from thechromecast_rpsdkpackage and place it at the top level of the target project you wish to instrument.
Environment Variables
The following environment variables have to be added to the .env file:
REACT_APP_API_URLREACT_APP_API_KEY
Command for Auto-Instrumentation
To automatically instrument your source code using the SDK, run the following command, after you have marked the application code, from the top level of the target project:
node --import=extensionless/register .\auto_instrumentation\AutoInstrumentation.min.js --input <input path> --outDir <output path>
Parameter Breakdown
--import=extensionless/register: Enables support for importing modules without requiring file extensions (e.g.,.js). This is necessary if your SDK or code uses extensionless imports.--input: Specifies the source directory that contains the application files to be instrumented.--outDir: Defines the output directory where the instrumented code will be written.
Code Marking Usage
Once you've identified a section of your application that requires tracking, import and use the Trackable class within the relevant JavaScript component. The Trackable class encapsulates all trackable events, their expected parameters, and the corresponding target functions, enabling consistent and structured code instrumentation.
import { RPSDKEVENTS } from "./chromecast_rpsdk/utils.min.js";
import { Callable } from "./chromecast_rpsdk/tracking_components/Callable.min.js";
import Trackable from "./chromecast_rpsdk/tracking_components/Trackable.min.js";
const AppTracking = new Trackable({
featureOrigin!: string,
Listening?:{
media_id!: string || Callable.<fieldName>,
media_type!: string || Callable.<fieldName>,
position!: string || Callable.<fieldName>,
output!: string || Callable.<fieldName>,
country_code!: string || Callable.<fieldName>,
catalog_media_id: string || Callable.<fieldName>,
targets!: [
{
event!: event,
callable!: {
identifier!: string,
path?: string
} || func(),
[specific fields based on the event]
}, ...
]
},
Error?:{
reason!: string || Callable.<fieldName>,
type!: string || Callable.<fieldName>,
source!: string || Callable.<fieldName>,
extra_info!: string,
targets!: [
{
event!: event,
callable!: {
identifier!: string,
path?: string
} || func(),
[specific fields based on the event]
}, ...
]
},
Action?:{
type!: string || Callable.<fieldName>,
subject!: string || Callable.<fieldName>,
targets!: [
{
event!: event,
callable!: {
identifier!: string,
path?: string
} || func(),
[specific fields based on the event]
}, ...
]
},
Mirroring?:{
type!: string || Callable.<fieldName>,
country_code!: string || Callable.<fieldName>,
targets!: [
{
event!: event,
callable!: {
identifier!: string,
path?: string
} || func(),
[specific fields based on the event]
}, ...
]
},
SetValue?:{
key!: string || Callable.<fieldName>,
value!: string || Callable.<fieldName>,
targets!: [
{
event!: event,
callable!: {
identifier!: string,
path?: string
} || func(),
[specific fields based on the event]
}, ...
]
}
})
The Trackable instance includes a set of required fields, marked in the code with an exclamation mark (!) to indicate their mandatory status. If any of these required fields are missing, the auto-instrumentation process will fail, and an error message will be displayed. Each field is associated with a specific data type that defines the accepted value format. If a field is specified as Callable.<fieldName>, it means the parameter should be passed dynamically at runtime by the target function within the UI component. If the target function does not accept this parameter, the auto-instrumentation process will be halted.
The featureOrigin parameter defines the point in tracking where an event is generated at a higher abstraction level than the Trackable.
The Trackable instance accepts as key the name of event class, each belonging to one of the following event classes:
ListeningActionSetValueMirroringError
These event classes define the type of interaction or behavior to be tracked.
Each event classes, as defined above, is associated with a set of mandatory attributes, the structure and content of which depend on the specific class (e.g., Listening, Action, SetValue, etc.). Mandatory attributes declared at the class level apply uniformly to all events of that class within the specific Trackable instance. These common parameters are reused across each event unless a specific override is provided at the individual event level.
In version 1.0, overwriting the mandatory fields shared across all Listening events is not supported. It is assumed that all events within a Trackable instance are associated with the same session initiated by the RPSDKEVENTS.Listening.fire_START_on event. As such, the fire_START_on event controls the values of these common parameters, which are then shared with all subsequent events.
This design simplifies configuration and ensures alignment across event definitions within the same class.
In addition, the configuration includes the target parameter, which defines the list of events to be tracked , along with their respective parameters and metadata related to the function being targeted by each specific event.
event– identifies the specific event to be tracked ( see here ) .callable– references the function or method to be linked when the event occurs ( see here ).
Event Parameter
The event field defines the name corresponding to the event to be tracked. The currently supported events include ( see here ):
RPSDKEVENTS.Listening.fire_START_onor'fire_START_on'RPSDKEVENTS.Listening.fire_PAUSE_onor'fire_PAUSE_on'RPSDKEVENTS.Listening.fire_STOP_onor'fire_STOP_on'RPSDKEVENTS.Listening.fire_ERROR_onor'fire_ERROR_on'RPSDKEVENTS.Listening.fire_SEEK_onor'fire_SEEK_on'RPSDKEVENTS.Listening.fire_SKIP_onor'fire_SKIP_on'RPSDKEVENTS.Listening.fire_START_STOP_onor'fire_START_STOP_on'RPSDKEVENTS.Error.fire_ERROR_onor'fire_ERROR_on'RPSDKEVENTS.SetValue.fire_CHANGE_onor'fire_CHANGE_on'RPSDKEVENTS.Action.fire_ACTION_onorfire_ACTION_on(for its specification see this section )RPSDKEVENTS.Mirroring.fire_START_onorfire_START_onRPSDKEVENTS.Mirroring.fire_STOP_onorfire_STOP_on
For each event, it is necessary to define a set of specific parameters , which may be either mandatory or optional , depending on the nature and requirements of the event ( see here ).
In addition, it is possible to override shared fields inherited from the event’s parent class. This allows for event-level customization when deviations from the class-level defaults are needed.
Overwriting a field is performed by assigning a new value to the designated field within the specific parameters section of an event. This modification is limited exclusively to the targeted event and can only be carried out by assigning the value to Callable.<field name>.
const AppTracking = new Trackable({
trackable: "AppTracking",
SetValue:{
key: Callable.key,
value: 'default value',
targets: [
{
event: RPSDKEVENTS.SetValue.fire_CHANGE_on,
callable: {
identifier: 'prova_SET_VALUE',
path: './customFunction.js'
},
value: Callable.value,
}
]
}
})
Callable Parameter
The callable parameter in each event identifies the target function for instrumentation, specifying where the tracking logic should be injected for that particular event.
There are two supported methods for defining a callable:
- Direct Function Reference
You can assign the field directly to a reference of the target function defined in the same file as the Trackable object, or to an imported function (as long as it is not encapsulated within a class).
const AppTracking = new Trackable({
trackable: "AppTracking",
featureOrigin: 'default features',
Listening: {
...
targets: [{
event: RPSDKEVENTS.Listening.fire_START_on,
callable: example_Start,
sync_info: Callable.sync_info
}
...]
}
}
...
export function example_Start(media_id, media_type, position, output, origin, sync_info, feature_origin) {
console.log('example_Start', media_id, media_type, position, output, origin, sync_info, feature_origin);
}
- Object-based Definition
Alternatively, you can define the field as an object in the following format:
callable:{ identifier: string, path?: string }
identifier: The name of the function to be targeted by the instrumentation.path: The relative path to the file where the function is defined, relative to the file containing theTrackableobject.
This method allows you to target functions that are:
- Imported from external modules
- Defined within external classes
The path field is optional. If omitted, it is assumed that the function is defined in the current file. For example, consider the following snippet in the example1.js file:
const AppTracking = new Trackable({
trackable: "AppTracking",
featureOrigin: 'default features',
Listening: {
...
targets: [{
event: RPSDKEVENTS.Listening.fire_START_on,
callable: {
identifier: 'example_Start',
path: <relative path to example2.js>
},
sync_info: Callable.sync_info
},
...
]
}
}
And assume the following function is implemented in a separate file, example2.js:
export function example_Start(media_id, media_type, position, output, origin, sync_info, feature_origin) {
console.log('example_Start', media_id, media_type, position, output, origin, sync_info, feature_origin);
}
In this case, by defining the Trackable as shown in the first snippet (example1.js), the system will correctly target and track the example_Start function defined in example2.js.
Targeting Functions within Other Classes
In addition to targeting functions the SDK also allows to target methods defined inside classes that can be defined either in the same file as the Trackable class or in a separate file.
The rules for populating the callable parameter into the Trackable object remain consistent with the guidelines described above. Since the method reference can’t be accessed outside the class where it’s defined, it is necessary to set the identifier parameter with the string representing the method’s name. If the class is defined in the same file as the Trackable, the path parameter is optional; otherwise, the relative path to the file must be specified. For example, consider the following snippets:
const AppTracking = new Trackable({
trackable: "AppTracking",
featureOrigin: 'default features',
Listening: {
...
targets: [{
event: RPSDKEVENTS.Listening.fire_START_on,
callable: {
identifier: 'example_Start',
path: <relative path to the file where 'example_path' is defined>
},
sync_info: Callable.sync_info
},
...
]
}
}
class ExampleClass {
example_Start(media_id, media_type, position, output, origin, sync_info, feature_origin) {
console.log('example_Start', media_id, media_type, position, output, origin, sync_info, feature_origin);
}
}
Checklist for Successful Instrumentation
To ensure proper auto-instrumentation, the following elements must be in place:
- In the Listening event section, at least one
Listening.fire_START_onand oneListening.fire_STOP_onevent must be present within the Listening trackable. - All mandatory fields must be defined as specified for each Event class.
- Missing
callablesection definitions or incomplete information for any event will result in instrumentation failure. - All required specific fields to an event must be present.
- The
targetsection must be defined (this contains event-specific details within a class). - Duplicate
Listening.fire_START_onevents with the sameCallabledefinition are not allowed.
Taking as an example the need to track the fire_START_on and fire_STOP_on events, we will define a Trackable as shown below, along with the corresponding functions to be targeted.
// import
const AppTracking = new Trackable({
trackable: "AppTracking",
featureOrigin: 'default features',
Listening: {
media_id: Callable.media_id,
media_type: Callable.media_type,
position: Callable.position,
output: Callable.output,
country_code: Callable.country_code,
catalog_media_id: Callable.catalog_media_id,
targets: [{
event: RPSDKEVENTS.Listening.fire_START_on,
callable: {
identifier: 'example_Start'
},
sync_info: Callable.sync_info
}, {
event: RPSDKEVENTS.Listening.fire_STOP_on,
callable: example_Stop
}
]}
})
export function example_Start(media_id, media_type, position, output, origin, sync_info, feature_origin) {
console.log('example_Start', media_id, media_type, position, output, origin, sync_info, feature_origin);
}
export function example_Stop(media_id, media_type, position, output, origin, feature_origin) {
console.log('example_Stop', media_id, media_type, position, output, origin, feature_origin);
}
After executing the command above, the code will be instrumented accordingly.
Specific event parameters
Some parameters are specific to certain events and are not common across all events within the same class. In fact, certain parameters can only be included for specific events. For example, if you need to indicate the direction of a player seek , this parameter is only relevant to the fire_seek event. An example of usage is provided below.
// import
const AppTracking = new Trackable({
trackable: "AppTracking",
featureOrigin: 'default features',
Listening: {
media_id: Callable.media_id,
media_type: Callable.media_type,
position: Callable.position,
output: Callable.output,
country_code: Callable.country_code,
catalog_media_id: Callable.catalog_media_id,
targets: [{
event: RPSDKEVENTS.Listening.fire_START_on,
callable: {
identifier: 'example_Start'
},
sync_info: Callable.sync_info
}, {
event: RPSDKEVENTS.Listening.fire_STOP_on,
callable: example_Stop
}, {
event: RPSDKEVENTS.Listening.fire_SEEK_on,
callable: example_Seek,
seek_type: Callable.seek_type
}
]}
})
export function example_Start(media_id, media_type, position, output, origin, sync_info, feature_origin) {
console.log('example_Start', media_id, media_type, position, output, origin, sync_info, feature_origin);
}
export function example_Stop(media_id, media_type, position, output, origin, feature_origin) {
console.log('example_Stop', media_id, media_type, position, output, origin, feature_origin);
}
export function example_Seek(media_id, media_type, position, output, origin, seek_type, feature_origin) {
console.log('example_Seek', media_id, media_type, position, output, origin, seek_type, feature_origin);
}
As with parameters specified in event tags, these parameters may or may not be mandatory. If a required parameter is not provided, a compilation error will occur. A comprehensive list of this parameters is provided below:
| Tag | Event | Param Name | Param Type | Required | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Listening | fire_START_on | sync_info | SYNCINFOS | false | ||||||
| Listening | fire_ERROR_on | reason | string | true | ||||||
| Listening | fires_SEEK_on | seek_type | ‘BACKWARD’ | ‘FORWARD’ | ‘DRAGGING’ | true | ||||
| Listening | fire_SKIP_on | skip_type | ‘PREVIOUS’ | ‘NEXT’ | ‘JUMP’ | ‘MEDIA_END’ | true | |||
| Listening | fire_SKIP_on | index | number | true |
Start and stop tracking
Once you have created all the Trackable instances and assigned them the correct attributes, in order actually track data from your application, you must explicitly start the tracking. To do this, you need to import and call the start_tracking function from rp_sdk/rpsdk.min and pass as parameter a configuration object (for its specification see this section)). Please note that once the start_tracking function is called and the data collection has started, you cannot restart it unless stop_tracking is called (consecutive calls to start_tracking without calling stop_tracking will be ignored).
Debug Mode
To activate the SDK debug mode you will simply call start_tracking setting the debug property of the conf object to true.
start_tracking({debug: true})
In the browser console, in addition to the possible warnings about listening and mirroring session handling, the following debug information will also be shown:
- Each tracked event, along with the collected parameters.
- Whether the events are received correctly by the Radioplayer dataplatform. In case of error, it will be reported and the error type will also be shown.
Default Event Params
Certain information must be associated with each event, regardless of its categorization. Specifically, this includes the catalog country code, the application name, the application name, the type of network to which the user is connected, the platform identifier, the product identifier and the network name. These parameters must be defined when initializing the SDK, as they form part of its configuration settings.
The values should be specified in the following manner:
start_tracking({
appName: 'RP-Chromecast-app',
appVersion: '1.0.1',
catalogCountryCode: '380',
networkInfo:{
name: 'UserMobile',
type: 'MOBILE'
},
platformID: 'GCR',
productID: 'RPWGCA'
}
- appName: Contains the name of the application
- appVersion: Contains the current version of the application.
- catalogCountryCode: Identify the numeric code representing the user's country, following the ISO 3166 numeric standard.
networkInfo: Contains details about the user’s network connection. If the field is _not provided_ during the configuration phase, it will be set by default to
{"name": null, "type": "UNKNOWN"}.- name: The name of the mobile network operator or service provider
- type: The type of network connection (
'WIRED','MOBILE', 'WIFI', 'UNKNOWN')
- platformID: Identify the receiver application. Example: set to GCR (Google Cast Receiver)
productID: Identifies the sender's application to the receiver at the start of a session
- RPWGCA for requests from _Google Assistant_
- RPWGCM for requests from internal _Mobile app_
- RPWGCW for requests from internal _Web app_
The platformId and productId parameters can either be set to _null_ or assigned one of the accepted values listed above. Otherwise, the event will be collected as _bad_ (schema violation) due to the use of unsupported values, and it will be ignored in the following data analysis steps.
The parameters appName, platformID and appVersion must remain constant throughout the execution of the application. However, catalogCountryCode, productID and networkInfo can be modified at any time after initialization by using updateCatalogCountryCode, updateProductID and updateNetworkInfo respectively. Below is an example for each function.
updateCatalogCountryCode("250")
updateProductID('RPWGCM')
updateNetworkInfo({type: "WIRED", name: "RP-WIRED"})
Please note that for the updateNetworkInfo function, both type and name must always be specified. If either or both are missing, the SDK will store a null value for these parameters. Additionally, type can only accept the following predefined values ['WIRED', 'MOBILE', 'WIFI', 'UNKNOWN'].
The string passed to updateCatalogCountryCodefunction must be a valid ISO 3166 numeric catalog country code: it must comply with the format of the standard and be associated with an existing nation.
If the debug mode is active the SDK will alert the developer if there are errors with these parameters values.
User Action Tracking
The Action event class should be used to track user interactions within the application. Specifically, it allows tracking only predefined types of user actions, which can be specified via the type parameter. Each action type is associated with its own set of parameters, which can be provided through the subject parameter. This parameter must be an object where the list of allowed fields and corresponding data types is determined by the type parameter. The complete list of possible actions is presented below.
| Action Type | Action Type Params | Param Type |
|---|---|---|
| search | value | string |
| shareRequest | mediaId | string |
| mediaType | MEDIATYPE | |
| sleepTimer | mediaId | string |
| mediaType | MEDIATYPE | |
| timerType | TIMERTYPE | |
| favourite | mediaId | string |
| mediaType | MEDIATYPE | |
| enable | ENABLETYPE | |
| alarm | mediaId | string |
| mediaType | MEDIATYPE | |
| enable | ENABLETYPE | |
| dateTimestamp | string | |
| download | mediaId | string |
| mediaType | MEDIATYPE | |
| siriShortCut | mediaId | string |
| mediaType | MEDIATYPE | |
| sync | enable | boolean |
| role | ROLETYPE | |
| isMerge | boolean | |
| numServicesMerged | number | |
| numSeriesMerged | number | |
| groupId | string | |
| guestPlatform | DEVICEPLATFORMS | |
| ownerPlatform | DEVICEPLATFORMS | |
| screenView | currentPage | string |
| previousPage | string | |
| changeLayout | layoutType | LAYOUTTYPE |
| countryChoice | ||
| countryReset | ||
| appReset | ||
| inAppReview | ||
| syncRefuse | ||
| updateStore | ||
| mediaRequest | mediaId | string |
| mediaType | MEDIATYPE | |
| syncError | reason | string |
| locationChoice | enable | string |
| permissionsIP | enable | string |
| autoplay | enable | string |
| syncMigration | userChooise | string |
| applicationStarted | countryCode | string |
Please note that if the action type or the action parameter type is invalid, the action will not be collected. In Debug mode, this will be reported to the developer for further review.
Geo Localization Tracking
There are several modes to attach geolocation information to each event sent:
Off : The SDK provides the option to disable geolocation tracking. The SDK will not collect or process any geolocation data. To enable this mode, simply specify the
geoModeproperty to'off'within the SDK configuration object when it starts up:start_tracking({geoMode: 'off'})Automatic: The SDK will automatically and internally track the location of the device. For position tracking to occur properly, the application must have access to the device location. To enable this mode, simply specify the
geoModeproperty to'auto'within the SDK configuration object when it starts up:start_tracking({geoMode: 'auto'})
Please note, the SDK in 'auto' mode ignores:
geoCallbackandgeoInfoparameters- every call to
updateGeoLocationfunction.
The Automatic Geo Tracking subsection will be updated in future releases.
- Geo Callback : The SDK will accept a callback as input, which will be invoked whenever an event is generated.
The geoCallback must have the following signature.
geoCallback: () => { return { latitude: number, longitude: number } }
To enable this tracking mode, it will be necessary to specify the geoMode to 'callback' and the actual callback in the SDK's configuration object when it starts.
start_tracking({geoMode:'callback', geoCallback: geoCallbackFunction})
Please note, the SDK in 'callback' mode ignores:
- the
geoInfoparameter - every call to the
updateGeoLocationfunction.
Manual update : You can also manually set the geolocation information whenever necessary. Specifically, this can be done by setting the
geoModeto'manual'at SDK start and providing thegeoInfoobject containing the coordinates in the following format.start_tracking({geoMode:'manual', geoInfo: {latitude: number, longitude: number}})
Then the updateGeoLocation function can be called at any time to update the geolocation information stored by the SDK, using an object of the same type as geoInfo.
updateGeoLocation({latitude, longitude})
Please note, the SDK in 'manual' mode ignores the geoCallback parameter.
Please note:
- If none of the values for the
geoModeparameter are among the expected ones, then device position tracking is disabled. - If the
geoModeis set to'manual'without any startinggeoInfocoordinates, it is still possible to specify them later with theupdateGeoLocationfunction. But as long as these remain unspecified, no geolocation information will be collected. - If the
geoCallbackreturn value orgeoInfodo not conform to the longitude and latitude format, no device position will be collected.
Define multiple Trackables across different files
The SDK allows developers to define multiple Trackable objects across different files. This flexibility is designed to simplify development and avoid the need to create a single, monolithic Trackable instance containing all tracked events.
By adhering to programming best practices, developers can organize Trackable instances logically by creating separate objects wherever it makes sense within the application's architecture.
Furthermore, any JavaScript function can be targeted by any Trackable, regardless of the file in which the function is defined. The only requirement is that the target function must reside in a .js file. Otherwise, the file will be ignored and no instrumentation will be applied. This modular approach improves maintainability and scalability while preserving full tracking capabilities.
Available functions
start_tracking(conf)
Initialize and start tracking of application data
Parameters
| proper | Param type | Param Description |
|---|---|---|
| conf | Object | Contains SDK configuration parameters |
Conf Object properties
| proper | Param type | Param Description | |||
|---|---|---|---|---|---|
| debug | boolean | indicates whether the SDK should be started in debug mode | |||
| geoMode | ‘auto’ | ‘manual’ | ‘geo’ | ‘off’ | Allows you to set the tracking mode of geolocation information (more information here ) |
| geoInfo | Object | allow to specify the start device latitude and langitude (more information here ) | |||
| geoCallback | function | callback that return an object contanaing device latitude and langitude (more information here ). | |||
| appName | string | Identifies the app that integrates the SDK | |||
| appVersion | string | Version number in format ‘x.x.x’ | |||
| networkInfo | Object | Information about the network to which the user is connected (more information here ) | |||
| catalogCountryCode | string | ISO 3166 numeric country code selected by the user | |||
| platformID | ‘GCR’ | null | Static parameter to identify the receiver application | ||
| productID | ‘RPWGCA’ | ‘RPWGCM’ | ‘RPWGCW’ | null | Dynamic parameter sent from the sender application to the receiver |
stop_tracking()
Stops the collection of data generated through the use of the Trackable tags. The automatic generation of the listening_session_hb event is suppressed when a tracking session is active.
updateGeoLocation(geoInfo)
Updates the geolocation information stored by the SDK when the geoMode is set to 'manual'
Parameters
| proper | Param type | Param Description |
|---|---|---|
| geoInfo | Object | Contains informations about device geografical position |
geoInfo Object properties
| proper | Param type | Param Description |
|---|---|---|
| latitude | number | represent the latitude coordinate of the device |
| longitude | number | represent the longitude coordinate of the device |
updateCatalogCountryCode(catalogCountryCode)
Updates the catalog country code stored by the SDK.
Parameters
| proper | Param type | Param Description |
|---|---|---|
| catalogCountryCode | string | New ISO 3166 numeric country code selected by the user |
updateProductID(productID)
Updates the product ID stored by the SDK.
Parameters
| proper | Param type | Param Description | |||
|---|---|---|---|---|---|
| productID | ‘RPWGCA’ | ‘RPWGCM’ | ‘RPWGCW’ | null | Dynamic parameter sent from the sender application to the receiver |
updateNetworkInfo(networkInfo)
Updates the network type and name stored by the SDK
Parameters
| proper | Param type | Param Description |
|---|---|---|
| networkInfo | Object | Information about the network to which the user is connected |
networkInfo Object properties
| proper | Param type | Param Description |
|---|---|---|
| type | NETWORKTYPE | Network type to which the user is connected |
| name | string | Network name to which the user is connected |
Available Trackable events
| RPSDKEVENTS Enum Values | Event name |
|---|---|
RPSDKEVENTS.Listening.fire_START_on | listening_fire_START_on |
RPSDKEVENTS.Listening.fire_STOP_on | listening_fire_STOP_on |
RPSDKEVENTS.Listening.fire_SKIP_on | listening_fire_SKIP_on |
RPSDKEVENTS.Listening.fire_SEEK_on | listening_fire_SEEK_on |
RPSDKEVENTS.Listening.fire_PAUSE_on | listening_fire_PAUSE_on |
RPSDKEVENTS.Listening.fire_ERROR_on | listening_fire_ERROR_on |
RPSDKEVENTS.Listening.fire_START_STOP_on | listening_fire_START_STOP_on |
RPSDKEVENTS.Mirroring.fire_START_on | mirroring_fire_START_on |
RPSDKEVENTS.Mirroring.fire_STOP_on | mirroring_fire_STOP_on |
RPSDKEVENTS.SetValue.fire_CHANGE_on | setvalue_fire_CHANGE_on |
RPSDKEVENTS.Error.fire_ERROR_on | error_fire_ERROR_on |
RPSDKEVENTS.Action.fire_ACTION_on | action_fire_ACTION_on |
Automatic Heartbeat Event During Media Playback Session
From the moment a listening session starts, a listening_session_hb event (heartbeat) is automatically generated at fixed intervals of 60 seconds. This event serves as a heartbeat to indicate that the user is still actively listening.
The listening_session_hb event contains the same fields and values as the session start event (Listening.fire_START_on). It cannot be instrumented within a function, as its generation is handled internally by the SDK. If more listening sessions are active at the same time, the listening_session_hb will be generated for each of them.
When the listening session ends (either by generating a Listening.fire_STOP_on event) or by calling the stop_tracking function, the automatic heartbeat generation ceases immediately.
Listening Session Lifecycle
This section describes the required steps to initiate a listening session and the conditions under which listening events are considered valid.
- Start Tracking
Call start_tracking() to initialize tracking.
- Open a Listening Session
After tracking has been successfully started, must be generated the listening_fire_START_on event to open a new listening session. Once a listening session is active, it is considered unique with respect to the trackable it belongs to. Multiple sessions may be active at the same time, provided they are initiated by different trackables.
Event Validity
- All listening events listed in the event reference table must be generated within an active listening session associated with a specific trackable in order to be recorded.
- Listening events generated outside of an active session will be ignored.
Listening
Allows tracking of events that are included and of interest within the same listening session.
Attributes
| Attribute Name | Attribute type | Attribute Description |
|---|---|---|
| Listening.fire_START_on | Playback of new media is started or resumed | |
| Listening.fire_STOP_on | Playback of the media currently playing is paused. | |
| The automatic generation of the listening_session_bh event is blocked. Listening.fire_SKIP_on | Skipping the media currently playing to the previous or next item in the queue | |
| Listening.fire_PAUSE_on | Playback of the media currently playing is paused | |
| Listening.fire_SEEK_on | Jumping the media currently playing to a new position between the beginning (0) and end (duration) of the content | |
| Listening.fire_ERROR_on | An error has occured during a listening session | |
| media_id* | string | It takes the value of RPID for live content and the value of CRID for on-demand content |
| media_type* | MEDIATYPE | The type of the media |
| position* | string | Current time of media in seconds. This value will be equal to the duration value in the case of end of streaming |
| output* | string | the output playback device |
| country_code | string | ISO 3166 numeric releted to the country code related to the media_id |
| catalog_media_id | string | media_id formatted according to standard INTL logic (optional field) |
Specific event paramters
| Event | Param Name | Param Type | Required | ||||||
|---|---|---|---|---|---|---|---|---|---|
| Listening.fire_START_on | sync_info | SYNCINFOS | false | ||||||
| Listening.fire_ERROR_on | reason | string | true | ||||||
| Listening.fire_SEEK_on | seek_type | ‘BACKWARD’ | ‘FORWARD’ | ‘DRAGGING’ | true | ||||
| Listening.fire_SKIP_on | skip_type | ‘PREVIOUS’ | ‘NEXT’ | ‘JUMP’ | ‘MEDIA_END’ | true | |||
| index | number | true | |||||||
| previous_country_code | string | false | |||||||
| previous_media_id | string | false | |||||||
| previous_media_type | _MEDIATYPE_ | undefined | '' | false |
Seek and Skip EventsSeek and Skip events may also be generated outside of an active session. In such cases, at the time of generation, the SDK will automatically convert them into action_seek and action_skip events to ensure structural consistency. The SDK itself is responsible for determining whether an active session is present or not.
In this case, the skip event will not be linked to an active session and therefore will not include a sessionId value. To ensure the correct tracking of the associated fields, developers must include the following fields in the Tracker component:
previous_country_codeprevious_media_idprevious_media_typeconst AppTracking = new Trackable({ ... Listening: { media_id: Callable.media_id, media_type: Callable.media_type, position: Callable.position, output: Callable.output, country_code: Callable.country_code, catalog_media_id: Callable.catalog_media_id, targets: [... { event: RPSDKEVENTS.Listening.fire_SKIP_on, callable: prova_SKIP, index: Callable.index, skip_type: Callable.skip_type, previous_country_code: Callable.previous_country_code, previous_media_id: Callable.previous_media_id, previous_media_type: Callable.previous_media_type }, ...] } })
These parameters will be ignored if the event occurs within an active session, as their values will be derived directly from the session (which remains consistent as it is managed internally by the SDK). However, they will be used to populate the corresponding fields when handling an skip event outside of a session.
Error
Allows generic application errors to be tracked.
Attributes
| Attribute Name | Attribute type | Attribute Description |
|---|---|---|
| Error.fire_ERROR_on | A generic error occurred in the app. | |
| type | string | A string indicating the error type |
| source | string | The source of the error. It corresponds with origin* |
| reason* | string | What have caused the error |
| extraInfo | Object | Addional info about the error. It is optional and should be used only for dev purposes |
Action
Allows tracking of a generic action taken by the user through the UI.
Attributes
| Attribute Name | Attribute type | Attribute Description |
|---|---|---|
| Action.fire_ACTION_on | UI event | |
| type | ACTIONTYPE | Type of the use interaction |
| subject | ACTIONSUBJECT | Describe what it’s the target of a user action. Its structure is defined by type param, more info can be found here |
| ui_source | UISOURCE | Information about the UI origin of the event |
SetValue
Allows you to track a variable/option change within the application.
Attributes
| Attribute Name | Attribute type | Attribute Description |
|---|---|---|
| Setvalue.fire_CHANGE_on | UI event | |
| key | string | Name of the option changed |
| value | string | New value of the option |
Mirroring
Allows you to track a mirroring session.
Attributes
| Attribute Name | Attribute type | Attribute Description |
|---|---|---|
| Mirroring.fire_START_on | mirroring session is started | |
| Mirroring.fire_STOP_on | mirroring session is stopped | |
| type | string | type of the mirroring (CARPLAY OR ANDROID AUTO) |
- These attributes accept the same values as the corresponding parameters defined in the document Firebase Analytics - Radioplayer Custom Events v3.0.
Parameters Types
| Type Name | Type Values | |||
|---|---|---|---|---|
| MEDIATYPE | ['STATION', 'SERIES', 'EPISODE'] | |||
| ENABLE | ['ON', 'OFF'] | |||
| TIMERTYPE | ['T15', 'T30', 'T45', 'T60', 'T120', 'OFF'] | |||
| ROLE | ['GUEST', 'OWNER'] | |||
| DEVICEPLATFORMS | ["RPWAND", "RPWIOS", "RPWGCR", "RPWATM", "RPWTZN", "RPWWOS", "RPWSKQ", "RPWFTV", "RPWTLN", "RPWATV"] | |||
| UISOURCE | `{tag: string | null, class: string | null, id: string | null}` |
| ACTIONTYPE | ['search', 'shareRequest', 'sleepTimer', 'favourite', 'alarm', 'download', 'siriShortCut', 'sync', 'screenView', 'countryChoice', 'countryReset', 'appReset', 'inAppReview', 'syncRefuse', 'updateStore', 'mediaRequest'] | |||
| NETWORKTYPE | ['WIRED','MOBILE', 'WIFI', 'UNKNOWN'] | |||
| SYNCINFOS | {groupId: string, previouslyDevicePlatform: DEVICEPLATFORMS, currentlyPlayed: boolean} | |||
| LAYOUTTYPE | ["LIST", "GRID"] |