Radioplayer Developer Reference

Web SDK

Technical reference for Radioplayer partner integrations.

Version

1.6.3

Document type

API / SDK reference

Audience

Radioplayer partner engineering teams

This is the documentation for the Radioplayer Web and CTV Apps Tracking SDK, version 1.6.3.

General principles

The SDK allows the user to track events which will be collected by the Radioplayer Data Platform.

Babel JSX 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 JSX pre-processor enables parsing of components, 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.

Installation

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.

Dependencies

"@snowplow/browser-plugin-geolocation": "^3.20.0",
"@snowplow/browser-tracker": "^3.19.0",
"@babel/core": "^7.16.0",
"crypto-browserify": "^3.12.0",

Add the babel plugin

• Create a folder to contain the rpsdk-plugin.min.js at same level of your .babelrc file.
• Add the rpsdk-plugin.min.js to the plugin list in your .babelrc file.

If you are in an environment where it is not possible to modify or insert a .babelrc file, please refer to the section Track-event-API fo ts + ssr).

Setup the SDK

• Place the rp_sdk folder in your src folder.

Environment Variables

For JavaScript Projects

The following environment variables have to be added to the .env file:

• REACT_APP_API_URL
• REACT_APP_API_KEY

For SSR TypeScript with Next framework Projects

The following environment variables have to be added to the .env file:

• NEXT_PUBLIC_API_URL
• NEXT_PUBLIC_API_KEY

Tracking Components Usage

To begin equipping your application with data tracking you must use the appropriate React components contained in the rp_sdk/tracking_components folder.

After you have identified a section in your application that you want to track within a React component you should import and use the Trackable component. This must wrap the JSX section where you want events to be tracked and you must specify its name attribute to identify this section within the component.

You then have to use one of the other tags provided by the SDK (e.g. Action) within the Trackable tag and specify all of its parameters. Parameters that contain fire in the name are used to tell the SDK to which components and event handlers the tracking events must be attached. All other attributes are used to collect tracking event parameters. Each attribute of type fire accepts a single targetTag object or an array of targetTag. The properties that compose are the following:

{
  tag!: string,
  event!: string,
  className?: string,
  id?: string
}

Where tag is the name of the tag to be instrumented, event is the the event handler tag attribute for which you would like the tracking event to be generated, className is the name of the component class you want to attach to, and id is the id attribute of the component to attach to. If only tag and event are present, the function attachment will occur on all tags within the Trackable tag that have that name. Similarly, if className is specified the tracking function will be attached to all elements that have that class within their className attribute. If id is specified, it will be attached to the only component specified by that id.

After explaining the general mechanism for enabling event tracking, let's look at an example of code instrumentation performed on a very simple React component containing only buttons. In this example, we want to track listening sessions.

<Trackable name='ListeningTracking'>
      <Listening
          fire_START_on={{tag: 'button', event: 'onClick', id: 'listening_start'}}
          fire_PAUSE_on={{tag: 'button', event: 'onClick', id: 'listening_pause'}}
          fire_STOP_on={{tag: 'button', event: 'onClick', id: 'listening_stop'}}
          fire_SEEK_on={{tag: 'button', event: 'onClick', id: 'listening_seek', seek_type: 'FORWARD'}}
          fire_SKIP_on={{tag: 'button', event: 'onClick', id: 'listening_skip', skip_type: 'BACKWARD', previous_country_code:'380', previous_media_id:'media2', previous_media_type: 'STATION', index: 1}}
          fire_ERROR_on={{tag: 'button', event: 'onClick', id: 'listening_error', reason: 'ErrorReason'}}
          media_id='media1'
          media_type='mediatype1'
          position='position1'
          output='output1'
          country_code='380'
          catalog_media_id='media2'
      >
      </Listening>
      <button onClick={func1} id='listening_start'>Listening start</button>
      <button onClick={func2} id='listening_stop'>Listening stop</button>
      <button onClick={func3} id='listening_pause'>Listening Pause</button>
      <button onClick={func4} id='listening_seek'>Listening Seek</button>
      <button onClick={func5} id='listening_skip'>Listening Skip</button>
      <button onClick={func6} id='listening_error'>Listening Error</button>
</Trackable>

In this case we used the Trackable tag to identify the portion of the component we intend to track. Any tag outside of it will not be considered for instrumentation. Within the Trackable tag we used the Listening tag to track events that may occur in a listening section. Thanks to the fire_START_on attributes we have indicated which is the event (onClick) of the component (the button tag with listening_start as id) for which we want the session start event to be fired. Note also that even if the onClick attribute of the button is not present, the instrumentation will occur correctly and the event will be recorded successfully. As in the example shown below:

<Trackable name='ListeningTracking'>
      <Action
        fire_ACTION_on={{tag: 'button', event: 'onClick', id: 'action_button'}}
        subject={{mediaType:'STATION', mediaId: 'media1'}} type={'download'}/>
      <button id='action_button'>Button</button>
</Trackable>

Let’s now look at an example in which instrumentation occurs for several components simultaneously:

<Trackable name='ListeningTracking'>
      <Action
        fire_ACTION_on={{tag: 'button', event: 'onClick'}}
        subject={{mediaType: 'STATION', mediaId: 'media1'}} type={'download'}/>
      <button onClick={func1} >Button1</button>
      <button onClick={func2} >Button2</button>
</Trackable>

In this case both button tags will be instrumented correctly and will track an Action event whenever either one is clicked. A similar result can also be achieved by additionally specifying the className as property of the fire_ACTION_on object. In this case, the tracking function will be hooked to all buttons that have that className.

Consider that the same couple of tag name and event cannot be specified as the target of more than one tracking attribute.

<Trackable name='ListeningTracking'>
      <Listening
          fire_START_on={{tag: 'button', event: 'onClick'}}
          fire_PAUSE_on={{tag: 'button', event: 'onClick'}}
          fire_STOP_on={{tag: 'button', event: 'onClick'}}
          fire_SEEK_on={{tag: 'button', event: 'onClick', seek_type: 'FORWARD'}}
          fire_SKIP_on={{tag: 'button', event: 'onClick', skip_type: 'BACKWARD', previous_country_code:'380', previous_media_id:'media2', previous_media_type: 'STATION', index: 1}}
          fire_ERROR_on={{tag: 'button', event: 'onClick', reason: 'ErrorReason'}}
          media_id='media1'
          media_type='mediatype1'
          position='position1'
          output='output1'
          country_code='380'
          catalog_media_id='media2'
      >
      </Listening>
      <button onClick={func1}>Listening</button>
</Trackable>

In this case we are trying to handle all the tracking events related to the listening session using the same onClick event of the same Button. This type of declaration in general is not supported by the SDK in fact it is not possible to indicate for an event tag (e.g Listening) the same component and the same event for two different fire_X_on attributes. The only two exceptions to this rule are listening_fire_START_on, listening_fire_STOP_on and mirroring_fire_START_on, mirroring_fire_STOP_on. As shown in the example below:

<Trackable name='ListeningTracking'>
      <Mirroring
        fire_START_on={{tag: 'button', event: 'onClick'}}
        fire_STOP_on={{tag: 'button', event: 'onClick'}}
        type='type1'
        country_code='380'>
      </Mirroring>
      <button onClick={func1}>Mirroring Start STOP</button>
</Trackable>

Specific event parameters

Some parameters are specific to certain events and are not common across all events within the same category. In fact, certain parameters can only be included for specific fire events. For example, if you need to indicate the direction of a player seek , this parameter is only relevant to the fire_seek event. To specify such parameters, they must be included within the targetTag of the specific fire_event, which enables the preprocessor to enrich the event by adding these event specific values. Below you can find an example of use. An example of usage is provided below.

<Trackable name='ListeningTracking'>
      <Listening
          fire_START_on={{tag: 'button', event: 'onClick'}}
          fire_PAUSE_on={{tag: 'button', event: 'onClick'}}
          fire_STOP_on={{tag: 'button', event: 'onClick'}}
          fire_SEEK_on={{tag: 'button', event: 'onClick', seek_type: 'FORWARD'}}
          fire_SKIP_on={{tag: 'button', event: 'onClick', skip_type: 'BACKWARD', previous_country_code:'380', previous_media_id:'media2', previous_media_type: 'STATION', index: 1}}
          fire_ERROR_on={{tag: 'button', event: 'onClick', reason: 'errorReason'}}
          media_id='media1'
          media_type='mediatype1'
          position='position1'
          output='output1'
          country_code='380'
          catalog_media_id='media2'
      >
      </Listening>
      <button onClick={func1}>Listening</button>
</Trackable>

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 paramatert is provided below:

Start and stop tracking

Once you have placed the tracking tags and assigned them the correct attributes, in order to begin 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 country code, the application name, the application version, 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: 'CTV',
        productID: 'RPWVDA'
    }

• 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 (e.g., MOBILE, WIFI)
• platformID: Identify the platform where the application is running.
• productID: Identify the specific application into RP products.

The parameters appName, platformID productID and appVersion must remain constant throughout the execution of the application. However, catalogCountryCode and networkInfo can be modified at any time after initialization by using updateCatalogCountryCode and updateNetworkInfo respectively. Below is an example for each function.

updateCatalogCountryCode("250")

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 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> tag 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 here.

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 geoMode property 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. When this mode is selected, a notification will appear asking the user for permission to share their location. For position tracking to occur properly, the browser must have direct access to the device's location. To enable this mode, simply specify the geoMode property to 'auto' within the SDK configuration object when it starts up:

  start_tracking({geoMode: 'auto'})

Please note, the SDK in 'auto' mode ignores:

• geoCallback and geoInfo parameters
• every call to updateGeoLocation function.

• 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 geoInfo parameter
• every call to the updateGeoLocation function.

• Manual update : You can also manually set the geolocation information whenever necessary. Specifically, this can be done by setting the geoMode to 'manual' at SDK start and providing the geoInfo object 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 geoMode parameter are among the expected ones, then device position tracking is disabled.
• If the geoMode is set to 'manual'without any starting geoInfo coordinates, it is still possible to specify them later with the updateGeoLocation function. But as long as these remain unspecified, no geolocation information will be collected.
• If the geoCallback return value or geoInfo do not conform to the longitude and latitude format, no device position will be collected.

Split track components between files

For tracking components with more than one fire type attribute, it is possible to split the assignment of these into different components. Some constraints must be taken into account to use this option:

• Trackings components that are in different files must be included in a <Trackable> tag with the same name attribute.
• All parameters that are not of type fire must be specified in both components.

• Each fire-type parameter must be specified exactly once for a <Trackable> tag with the same name.

  • Is not possible to assign in two different files the same fire attribute in a <Trackable> tag with the same name.
  • All fire type parameters must still be specified even if split among multiple files.

To enable ths feature, it is necessary to use webpack specifically the plugins system provided by it. Inside the babel_plugins folder is possible to find the file rpsdk-webpack-plugins.min.js To use it just import WebpackBabelPlugin class into webpack.config.js and instantiate it (it does not need parameters) in the plugin section e.g:

// ...
plugins: [

// Generates an `index.html` file with the <script> injected.
new WebpackBabelPlugin(),
new HtmlWebpackPlugin(...)
// ...
]

Let us look at an example of its use. Suppose we have a first component and we want to use the <Listening> but in this file we have only the components that handles fire_START_on and fire_STOP_on.

<Trackable name='SplitListeningTracking'>
      <Listening
          fire_START_on={{tag: 'button', event: 'onClick', id: 'listening_start'}}
          fire_STOP_on={{tag: 'button', event: 'onClick', id: 'listening_stop'}}
          fire_ERROR_on={{tag: 'button', event: 'onClick', reason: 'errorReason'}}
          media_id='media1'
          media_type='mediatype1'
          position='position1'
          output='output1'
          country_code='380'
          catalog_media_id='media2'
      >
      </Listening>
      <button onClick={func1} id='listening_start'>Listening start</button>
      <button onClick={func2} id='listening_stop'>Listening stop</button>
</Trackable>

We can then assign the remaining fire type attributes in another file in the following way:

<Trackable name='SplitListeningTracking'>
      <Listening
          fire_PAUSE_on={{tag: 'button', event: 'onClick', id: 'listening_pause'}}
          fire_SEEK_on={{tag: 'button', event: 'onClick', id: 'listening_seek', seek_type: 'FORWARD'}}
          fire_SKIP_on={{tag: 'button', event: 'onClick', id: 'listening_skip', skip_type: 'BACKWARD', previous_media_id:'media2', previous_media_type: 'STATION', index: 1}}
          media_id='media1'
          media_type='mediatype1'
          position='position1'
          output='output1'
          country_code='380'
          catalog_media_id='media2'
      >
      </Listening>
      <button onClick={func3} id='listening_pause'>Listening Pause</button>
      <button onClick={func4} id='listening_seek'>Listening Seek</button>
      <button onClick={func5} id='listening_skip'>Listening Skip</button>
</Trackable>

Using start and build with Auto-Instrumentation in _JS project_

You can run or build your project as usual using:

npm run start
# or
npm run build

During these processes, the SDK plugin will automatically instrument your code, injecting the necessary logic based on the defined elements.

Alternatively, you may use any method that removes the node_modules/.cache directory.

Supported Syntax Elements

The following event handler syntax details the specific syntax elements that the SDK supports. Each element includes relevant TSX and JSX code examples.

• Arrow Function With Exact Destructured Params:

An arrow function where the parameter is a flat destructured objectExamples:

<button id={'setvalue1'} onClick={({ params: rpuIdProps }: { params: { rpuId: string } }) => calculator.add}> Setvalue1 </button>
<button id={'setvalue2'} className={'class1 class2'} onClick={({ params: rpuIdProps }: { params: { rpuId: string } }) => calculator.add}> Setvalue2 </button>

• Arrow Function Without Block:

A concise arrow function that returns an expression directly without a block ({}) Examples:

<button id={'setvalue1'} onClick={() => episode2({2,3,4})}> Setvalue1 </button>
<button id={'setvalue2'} onClick={() => episode4('test')}> Setvalue2 </button>

• Arrow Function With Block

An arrow function that uses a block body , allowing for multiple statements or internal logic. Examples:

<button id={'setvalue1'} onClick={() => { episode({ params: { rpuId: 'prova' } });}} > Setvalue1 </button>
<button id={'setvalue2'} onClick={() => { const x = 1; const y = 2; return episode2(x, y, 3); }} > Setvalue2 </button>

• Function Identifier

A function or method reference passed directly by identifier , without invocation or wrapping. Examples:

<button onClick={start} id='listening_start'>Listening start</button>
<button onClick={stop} id='listening_stop'>Listening stop</button>
<button onClick={pause} id='listening_pause'>Listening Pause</button>

• Function Call

Function calls that return another function Examples:

<button id={'setvalue1'} onClick={problem.calculator.sub()}> Setvalue1 </button>
<button className={'class1'} onClick={method_examples(method_examples2())}> Setvalue2 </button>

• Conditional Expression

A ternary expression used to determine which function or value is used. Examples:

<button id={'setvalue1'} onClick={(false) ? episode1 : calculator.add}>Setvalue1</button>

• Member Expression

Expressions such as array access or object property access can be assigned directly, provided that they are functions Examples:

<button id={'setvalue1'} onClick={calculator.add}> Setvalue1</button>
<button id={'setvalue2'} onClick={CustomObject.calculator.sub}> Setvalue2 </button>
<button id={'setvalue3'} onClick={funct[0]}> Setvalue3 </button>

Feature Origin Tracking

If you’re also interested in tracking the point where an event is generated at a higher abstraction level than the Trackable, you can use the featureOrigin parameter. Unlike name, which must be a literal string, featureOrigin accepts any value that evaluates as a string (variables, function calls, constants, literals, etc.). When a component containing the Trackable is designed to identify which logical feature (e.g podcasts carousel, favourite lits, etc..) of the app it belongs to, this knowledge can be extended to event tracking. For example, suppose the <Trackable> is positioned within a component TrackCompwhich is used by two different parent components: FeatureComp1 and FeatureComp2. If TrackComp is configured to recognize which of these parent components invoked it (e.g., via a prop), you can assign this value to featureOrigin, allowing differentiation between events generated by TrackComp in FeatureComp1 versus FeatureComp2.

function TrackComp({feature}){
    return (
        // ...
        <Trackable name='TrackComp', featureOrigin={feature}>
        // ...
    )
}
function FeatureComp1(){
    return (
        // ...
        <TrackComp feature='FeatureComp1'>
        // ...
    )
}
function FeatureComp2(){
    return (
        // ...
        <TrackComp feature='FeatureComp2'>
        // ...
    )
}

Older Browser Compatibility

The SDK provided is written following the ES6 standard and it is compatible with the most modern versions of Chrome (125) and Firefox (127). However, if there is a need to use the web SDK for older browsers, the runtime of the SDK has been written so that it is transpilable to comply with the ES5 standard. In order to use the ES6 version and to transpile it to ES5, you will need to add to the dependency: "@babel/preset-env@7.23.6". Also, to build the application for a specific browser version (e.g Chrome 49) you must specify the following Babel configuration.

{
    "presets": ["@babel/preset-react", [
    "@babel/preset-env",
    {
        "targets": {
            "chrome": "49"
        },
        "useBuiltIns": "usage",
        "corejs": 3,
    }
    ]],
    "plugins": ["./babel_plugins/rpsdk-plugin.min.js"]
}

This way, all polyfills needed for the SDK to work will be introduced at build time.

If this does not apply to your case and you are working in an environment that supports only ES5, you can find a version already built following this standard in the older_browser directory.

Note that only the rpsdk.min.js runtime is provided following the ES5 standard while the generated API will not comply with ES5. If you need to work in ES5 environment, you have to transpile the API.

Track event API

If, unfortunately, <Trackable> tags and Events tags fail to cover all your use cases, it is possible to generate and use API calls anywhere in your JavaScript code in order to track the application events. However, the generation of such an API is based on the proper use of the <Trackable> tags within the code and relies on Babel for generating the necessary code.

Addional Dependencies

"@babel/core": "^7.16.0",
"@babel/generator": "^7.24.6",
"@babel/types": "^7.24.7",
"yargs": "^17.7.2"

Note on TypeScript + SSR Projects (e.g. Next)

For projects written in TypeScript and using Server Side Rendering (SSR), such as those built with Next.js , Babel-based instrumentation is not supported.

This is due to several limitations:

• Incompatibility between Babel and Next’s native TypeScript handling in SSR mode.
• Partial or inconsistent transformation of server-side entry points.
• Potential issues with Next.js’ compilation pipeline bypassing Babel in certain server contexts.

✅ Recommended Approach

For these cases, the only supported method to instrument your code is by generating the API manually using the CLI command ( see here ) :

node babel_plugins/generate_api_library.js --input src --filename rpsdk_api.js --rpsdk src/rp_sdk --jsGeneration true --enableTsPreset true

This will generate the instrumented API code in advance, which can then be imported and used directly without relying on Babel or runtime plugins.

How to generate the API

To generate the tracking API, you first need to specify which <Trackable> tags you intend to use for API calls. To do this, you will simply specify for each one the generateAPI attribute. This additional attribute admits only boolean literal values or no value at all.

<Trackable name='ErrorTracking' generateAPI={true}>
// ...
</Trackable>
<Trackable name='appTracking' generateAPI>
// ...
</Trackable>

If formats other than the indicated two are specified, a compilation error will be returned. Also note that generateAPI is not mandatory and in case it is not specified, the <Trackable> will be excluded from API generation. Furthermore, <Trackable> tags can also contain none of the Event tags, as the generated API will allow any type of event to be fired from an instance of the target <Trackable>. Once you have correctly specified the value for all <Trackable> tags of interest, you need to run the rpsdk-generate-sdk-api.js node script that you can find in the babel_plugins folder. The script accepts the following arguments:

So an example of execution might be as follows

node babel_plugins/generate_api_library.js --input src --filename rpsdk_api.js --rpsdk src/rp_sdk --jsGeneration true --enableTsPreset false

Once the script has finished its execution, it will produce the file named rpsdk_api.js within the rp_sdk folder, ready to be used. Specifically, the rpsdkAPI namespace will be generated and exported, which contains an instance for each <Trackable> for which you have specified generateAPI as true. Within these objects you can find all instances of the Event tags (such as <Listening>, <Error> etc, but in lower case. If you want to know more in depth between the <Trackable> tag mapping and the APIs callable from the generated library look at this table). Each of these in turn will contain all the methods of fire_type of the corresponding Event tags, the parameters of these methods are the same as the parameters of the events. Then once you import the namespace inside a file you can track events in the following way:

import {rpsdkAPI} from "./rp_sdk/rpsdk_api.js"
...
function func1(){
  rpsdkAPI.apptrackingInstance.listening.fire_start({media_id: 'media_id', media_type: 'media_type', position: 'position', output:'output', origin:'origin'})
}
...
function func2(){
  rpsdkAPI.apptrackingInstance.listening.fire_stop({media_id: 'media_id', media_type: 'media_type', position: 'position', output:'output', origin:'origin'})}
}

Note that the name of the instances is always equal to the value of the name attribute specified on the <Trackable>. Each <Trackable> instance always has instances of all event classes inside it. Finally, all instances of the event classes have methods for firing each type of event defined by the Event class. In particular, this is an object that must have as keys the attribute names of the corresponding tag. However, there is one exception to this rule: For the action.fire_action event, you need to specify an additional parameter that the preprocessor previously compiled automatically which is the ui_source i.e. a javascript object of this type:

{
  tag!: string,
  class?: string,
  id?: string
}

Where tag is the name of the tag that should have generated that event and class and id are possibly its className and id. The ui_source gives information about the ui component that generated that event.

Trackable Events/API calls mapping

Available functions

start_tracking(conf)

Initialize and start tracking of application data

Parameters

Conf Object properties

stop_tracking()

Stops the collection of data generated through the use of the Trackable tags.

updateGeoLocation(geoInfo)

Updates the geolocation information stored by the SDK when the geoMode is set to 'manual'

Parameters

geoInfo Object properties

updateCatalogCountryCode(catalogCountryCode)

Updates the country code stored by the SDK.

Parameters

updateNetworkInfo(networkInfo)

Updates the network type and name stored by the SDK

Parameters

networkInfo Object properties

Available tracking tags

_All tag parameters are mandatory._

Trackable

Identifies a portion of JSX that is intended to be tracked; this section is identified by its name within the component.

Attributes

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.

1. Start Tracking

Call start_tracking() to initialize tracking.

1. 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.

1. 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

Specific event paramters

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_code
• previous_media_id

• previous_media_type

  const AppTracking = new Trackable({
    ...
    Listening: {
      media_id: Callable.media_id,
      media_type: Callable.media_type,
      position: Callable.position,
      output: Callable.output,
      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

Action

Allows tracking of a generic actions taken by the user through the UI.

Attributes

The parameters specified in the subject for each Action events identify the specific parameters related to the action being analyzed, where applicable. The following sections provide details about these parameters.

SetValue

Allows you to track a variable/option change within the application.

Attributes

Mirroring

Allows you to track a mirroring session.

Attributes

For the attributes with followed by *, they accept the same values as the corresponding parameters defined in the document _Firebase Analytics - Radioplayer Custom Events v3.0_.

Finally, note that for any parameter that is not of type targetTag is indicated as string. Actually, complex objects can also be assigned as long as they are first converted to a string using a method that return a valid JSON representation for that object.

Parameters Types