Radioplayer Developer Reference

Mobile Tracking SDK

Technical reference for Radioplayer partner integrations.

Version

Current

Document type

API / SDK reference

Audience

Radioplayer partner engineering teams

This is the documentation for the Radioplayer Mobile SDK v1.0.0.

General principles

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

Annotation-Based Implementation

To keep code maintainable and consistent, the Radioplayer Mobile Data Tracking SDK recommends an annotation-based approach to instrumentation. Instead of inserting trackEvent() calls inside business logic, developers declare tracking intent via annotations , and a separate processing tool injects the required tracking logic.

Benefits

• Clarity: tracking points are explicit and easy to spot.
• Separation of concerns: business logic stays clean—no analytics boilerplate.
• Consistency: event-specific annotations enforce the correct schema and required fields.
• Maintainability: schema changes are handled by updating annotation definitions, not scattered call sites.

Annotate the callee, not every call site

Place tracking annotations on the method being called (the callee), rather than on each location where it’s invoked.

Why this matters

• Reduced duplication: one instrumentation block covers all callers.
• Consistent capture: the same arguments/context are collected on every entry.
• Single point of change: updates happen once, in the annotated method.

Installation

1. Add the downloaded SDK and the following dependencies to the package.json:

   "dependencies": {
   
       // ... existing entries ...
       "@radioplayer/mobile-tracking-sdk": "file:/home/user/.../radioplayer-mobile-tracking-sdk-1.0.0.tgz",
       "@react-native-async-storage/async-storage": "^2.0.0",
       "@react-native-community/netinfo": "^12.0.1",
       "@snowplow/react-native-tracker": "^4.7.0",
       "react-native-geolocation-service": "^5.3.1",
       "react-native-get-random-values": "^1.11.0",
       "react-native-permissions": "^5.5.1",
       "react-native-safe-area-context": "^5.5.2"
   },
   "devDependencies": {
   
       // ... existing entries ...
       "@babel/plugin-transform-class-static-block": "^7.29.7",
       "@babel/plugin-proposal-decorators": "^7.29.0"
   }

2. Add the following plugins in babel.config.js:

   module.exports = {
       presets: ['module:@react-native/babel-preset'],
   
       plugins: [
   
       // 1. Tracking SDK plugin (must be the first plugin listed here)
       '@radioplayer/mobile-tracking-sdk/plugin',
       '@babel/plugin-transform-class-static-block',
       ['@babel/plugin-proposal-decorators', { version: '2023-11' }],
       ],
   };

3. Install the SDK:

   npm install

Android

1. Declare the Geo-Location usage in the android manifest:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   
       <uses-permission android:name="android.permission.INTERNET" />
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
       ...
   
   </manifest>

2. Start metro:

   npx react-native start --reset-cache

3. Start the application (tested through adb and a company android phone):

   adb devices
   # List of devices attached
   # R5.......3E	device
   
   npx react-native run-android

iOS

1. Open ios/Podfile and add the react-native-permissions setup block. It must appear before the target declaration and outside any use_frameworks! block.

   # ... existing Podfile content above ...
   require_relative '../node_modules/react-native-permissions/scripts/setup'
   
   setup_permissions([
     'LocationWhenInUse',
   ])
   
   target 'MyApp' do
     # ... rest of your target block ...

   cd ios && pod install && cd ..

2. Open ios/MyApp/Info.plist and add the following key inside the root <dict>. If the key already exists with an empty string, update the value.

   <!-- Add inside the root <dict> -->
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>The app requests geolocation access to optimise the listening tracking experience.</string>

3. Start metro:

   npx react-native start --reset-cache

4. Start the application (tested on the following iOS simulator versions: 16.4, 18.6, 26.5):

   npx react-native run-ios

Initialization and Configuration

Once you have imported the Radioplayer Mobile Data Tracking SDK files and integrated the code with annotations and related fields, you must explicitly start tracking to begin collecting data from your application. To do this, you need to call the initialize and then the startTracking methods of TrackingSDK object.

To ensure the tracker functions correctly, it must be configured, preferably when your application first starts. The following example demonstrates how to set up the TrackingSDK object.

import { TrackingSDK, ... } from '@radioplayer/mobile-tracking-sdk';

const sdk = TrackingSDK.getInstance();

await sdk.initialize({
        appName: 'my-mobile-sdk',
        appVersion: '1.0.0',
        platformId: platformId, // provided by RP
        productId: productId,   // provided by RP
        deviceInfo: new DeviceInfo('maker', 'model', 'os-name', 14.4, 'my-pseudo-device-id'),
        apiUrl: API_URL,  // provided by RP
        apiKey: API_KEY,  // provided by RP
        debug: false,
    });

await sdk.startTracking(catalogCountryCode);

Please note that once one of these start functions has been called and data collection has begun, you cannot restart it unless stopTracking is called (consecutive calls to start method without calling stopTracking will be ignored).

Default Event Params

Certain information must be associated with each event, regardless of its categorization. Parameters such as the application name (appName), application version (appVersion), platform (platformId) and product (productId) identifiers are defined only once, when the TrackingSDK is initialized, and must remain constant throughout the application execution. 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:

await sdk.initialize({
        appName: 'my-mobile-sdk',
        appVersion: '1.0.0',
        platformId: platformId, // provided by RP
        productId: productId,   // provided by RP
        deviceInfo: new DeviceInfo('maker', 'model', 'os-name', 14.4, 'my-pseudo-device-id'),
        apiUrl: API_URL,  // provided by RP
        apiKey: API_KEY,  // provided by RP
        debug: false,
    });

Other parameters, such as the catalog country code (catalogCountryCode), are passed directly to the new startTracking methods at start-up. The catalogCountryCode can be modified at any time after initialization using updateCatalogCountryCode respectively. Below is an example for each function.

sdk.updateCatalogCountryCode("250")

The string passed to updateCatalogCountryCode function must be a valid_ISO 3166-1_ 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.

Debug Mode

To activate the SDK debug mode, you can pass a true flag during initialize or startTracking:

sdk.startTracking("250", true);

In console, in addition to possible warnings about listening session management, each tracked event will also be displayed, along with the collected parameters.

TrackingSDK: All available functions

Initialize the TrackingSDK: initialize()

Initialize tracking of application data.

Parameters

Start tracking method : startTracking()

Start tracking of application data.

Parameters

Stop tracking method : stopTracking()

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

Update catalog country code: updateCatalogCountryCode(catalogCountryCode)

Updates the catalog country code stored by the SDK.

Parameters

Update consent: updateConsent(newConsent)

Updates the consent stored by the SDK.

Parameters

Geo Localization Tracking

The Tracking SDK automatically manages user location tracking based on the Android/iOS permissions grants. The system dynamically adapts to changes in permissions in real time, ensuring privacy compliance and always using the best level of accuracy available.

Event Buffer

The Event Buffer component is designed to collect and optimize events generated by the instrumentation application before they are sent externally.

To ensure efficient data collection, the component locally manages a batch of events by:

• Optimizing the size of the event header
• Managing the persistence of events

Events are held in this local buffer until the batch is full, at which point it is sent. This approach is crucial for preventing data loss. For example, if the device loses its internet connection, the events are safely stored in the local buffer and will be sent automatically as soon as the connection is restored. The optimization of event batching specifically concerns active session management. By aggregating events during an active session, the SDK minimizes the number of transmissions, which in turn optimizes data delivery and reduces overhead.

Tracking Components Usage

In this version of the SDK, the following annotations are available. For correct implementation, you need to import the specific enumerators required from the SDK. This approach makes the code more readable and less prone to errors than using hardcoded strings.

import { SeekStatus } from '@radioplayer/mobile-tracking-sdk';

Every event has mandatory fields , and some also include optional fields.

Notation Supported

All parameters can be declared using either a string literal (e.g., "parameter") or in curly brackets (e.g., "{parameter}"). To populate the optional fields , we recommend using the relativeenumeration to access the supported and recommended values.

The value for optional fields can be defined in two ways:

• As a string literal (e.g., "ValueName").
• As a javascript expression (e.g., {myVariable}).

The second method allows the value to be changed at runtime, as it is dynamically mapped from a variable. When using this approach, keep in mind that the call variable must be of the correct type to ensure data integrity and avoid runtime errors.

Allowed parsing

• Call to methods

  @SetValue({ key: 'radio_mode', value: '{this.getStereoMode()}' })

• Call to methods with args

  @SetValue({ key: 'radio_mode', value: '{this.getStereoMode(arg1, arg2)}' })

• Field access

  @SetValue({ key: 'radio_mode', value: '{this.stereoMode}' })

• Array element access

  @SetValue({ key: 'fav_radio', value: '{freqRadioFav[1]}' })

• Allowed keyword/ Keyword recognition:

  @SetValue({ key: 'radio_focus', value: '{true}' })

  • true
  • false
  • null

• Number (int, float, double)

  @SetValue({ key: 'volume_level', value: '{50}' })

• Explicit string

  @SetValue({ key: '{"Test"}', value: '{"Not work"}' })

• Return Escape Value

  @SetValue({ key: '{"Test"}', value: '{{RETURN}}' })

NOT allowed parsing

The cases not yet supported are:

• Expressions with arithmetic or logical operators

  • x + y
  • x && y
  • x || y
  • i * (j + k)
  • !flag

• Ternary expressions:

  • x > 0 ? "positive" : "negative"
  • (String) obj.getName()
• Representing negative values (negative numbers)
• Strings with special characters or escape sequences: \n, \t, etc.

• Return types and generic methods

  • Map<number, string>

Class annotation: @Trackable

The @Trackable annotation is used at the class level to identify components whose methods are to be automatically instrumented and tracked by the Device Tracking SDK.

@Trackable({trackableName: 'rs-trackable-name', origin: 'rs-origin', featureOrigin: 'rs-feature-origin'})
class RadioService {
    private freqRadioFav = [88.5, 105.1, 108.0];
    // ...
}

Annotation Element

Method Annotation

The annotations that can be used for methods are listed below.

@RadioStart

This action indicates that a radio stream has started playing. It includes details such as the rpuid and the volume level.

The @RadioStart annotation triggers a listening_session_start event, which signals the _start of a new listening session_. This event allows us to detect when the user starts listening to radio content.

Annotation Element

Example of usage

import { RadioStart, RadioMode } from '@radioplayer/mobile-tracking-sdk';
// ...

@RadioStart({
        rpuid: '{this.radioInfo.rpuid}',
        countryCode: '208',
        radioMode: '{this.radioInfo.mode}',
        bearer: 'fm:9e1.9203.09390',
        output: 'my-output',
    })
startRadio() { ... }

@RadioStop

This action indicates that a radio stream has been stopped. It includes details like the rpuid, bearer and countryCode.

The @RadioStop annotation triggers a listening_session_stop event, which indicates the _end of the listening session_. This allows us to determine when the user has stopped listening to radio content.

Annotation Element

Example of usage

@RadioStop({
        rpuid: '{this.radioInfo.rpuid}',
        countryCode: '{this.radioInfo.countryCode}',
        radioMode: '{this.radioInfo.mode}',
        output: '{this.stereo.mode}',
    })
stopRadio() { ... }

@RadioPause

This action indicates that a radio stream has been paused. It includes details such as the rpuid.

The @RadioPause annotation generates a listening_session_pause event, which signals that the listening session has been paused. In the device domain, in addition to this event, a listening_session_stop event is also generated to indicate that the user has temporarily stopped listening.

Annotation Element

Example of usage

@RadioPause({
        rpuid: '{this.radioInfo.rpuid}',
        countryCode: '{this.radioInfo.countryCode}',
        output: '{this.stereo.mode}',
    })
pauseRadio() { ... }

@RadioSkip

This action indicates that the radio has skipped to a different station or a different item in a playlist. To populate the skipType field, we recommend to follow the notation supported.

The @RadioSkip annotation triggers a listening_session_skip event, which signals that the user has skipped another radio station. Each skip corresponds to a new listening session, so in addition to the listening_session_skip event, the listening_session_stop and listening_session_start events are also generated.

Annotation Element

*Optional: if not provided, defaults to SkipStatus.NEXT.

Example of usage

import { RadioSkip, SkipStatus } from '@radioplayer/mobile-tracking-sdk';
@RadioSkip({
        newRpuid: '276233',
        newBearer: 'dab:1e0.100c.1023.0',
        countryCode: '{this.radioInfo.countryCode}',
        skipType: '{SkipStatus.NEXT}',
        output: '{this.stereo.mode}',
    })
skipRadio() { ... }

@RadioSeek

This action indicates that a user manually changes the playback position of a live radio stream. To populate the seekType field, we recommend to follow the notation supported (see here).

The @RadioSeek annotation triggers a listening_session_seek event, which signals that the audio content is being fast-forwarded or rewound. It is used to understand whether the user is searching for a specific part of the content.

Annotation Element

*Optional: if not provided, defaults to SeekStatus.FORWARD.

Example of usage

@RadioSeek({
        rpuid: '{this.radioInfo.rpuid}',
        countryCode: '{this.radioInfo.countryCode}',
        seekType: '{SeekStatus.FORWARD}',
        output: '{this.stereo.mode}',
    })
seekRadio() { ... }

@RadioError

This action logs an error when triggered whenever an error occurs during a listening session.

Using the @RadioError annotation triggers a listening_session_error event. This event lets us know when an error related to the listening session has occurred.

Annotation Element

Example of usage

@RadioError({
        rpuid: '{this.radioInfo.rpuid}',
        reason: 'Weak signal',
        output: '{this.stereo.mode}',
    })
errorRadio() { ... }

@PodcastStart

This action indicates that a podcast episode has started playing. It includes details such as the episode ID (crid) and countryCode.

The @PodcastStart annotation triggers a listening_session_start event, which signals the _start of a new listening session_. This event allows us to detect when the user starts listening to podcast content.

Annotation Element

Example of usage

@PodcastStart({
        crid: '{this.podcastInfo.crid}',
        countryCode: '380',
        position: '{this.currentPosition}',
        output: '{this.stereo.mode}',
    })
startPodcast() { ... }

@PodcastStop

This action indicates that a podcast episode has been stopped. It includes details like the episode ID (crid) and the position at which it was stopped.

The @PodcastStop annotation triggers a listening_session_stop event, which indicates the _end of the listening session_. This allows us to determine when the user has stopped listening to podcast content.

Annotation Element

Example of usage

@PodcastStop({
        crid: '{this.podcastInfo.crid}',
        countryCode: '380',
        position: '{this.currentPosition}',
        output: '{this.stereo.mode}',
    })
stopPodcast() { ... }

@PodcastPause

This action indicates that a podcast episode has been paused. It includes details such as the episode ID (crid) and the position in the episode at which it was paused.

The @PodcastPause annotation generates a listening_session_pause event, which signals that the listening session has been paused. In the device domain, in addition to this event, a listening_session_stop event is also generated to indicate that the user has temporarily stopped listening.

Annotation Element

Example of usage

@PodcastPause({
        crid: '{this.podcastInfo.crid}',
        countryCode: '380',
        position: '{this.currentPosition}',
        output: '{this.stereo.mode}',
    })
pausePodcast() { ... }

@PodcastSkip

This action indicates that the podcast player has skipped to a different episode or a different point within the current episode. It provides details about the current media and the skip type. To populate the skipType field, we recommend to follow the notation supported (see here).

The @PodcastSkip annotation triggers a listening_session_skip event, which signals that the user has skipped another episode of the podcast. Each skip corresponds to a new listening session, so in addition to the listening_session_skip event, the listening_session_stop and listening_session_start events are also generated.

Annotation Element

*Optional: if not provided, defaults to SkipStatus.NEXT.

Example of usage

@PodcastSkip({
        newCrid: '61960-4-239200',
        countryCode: '380',
        position: '{this.currentPosition}',
        skipType: '{SkipStatus.NEXT}',
        output: '{this.stereo.mode}',
    })
skipPodcast() { ... }

@PodcastSeek

This action indicates that a user manually changes the playback position of a podcast episode. To populate the seekType field, we recommend to follow the notation supported (see here).

The @PodcastSeek annotation triggers a listening_session_seek event, which signals that the audio content is being fast-forwarded or rewound. It is used to understand whether the user is searching for a specific part of the content.

Annotation Element

*Optional: if not provided, defaults to SeekStatus.FORWARD.

Example of usage

@PodcastSeek({
        crid: '{this.podcastInfo.crid}',
        countryCode: '380',
        position: '{this.currentPosition}',
        seekType: '{SeekStatus.BACKWARD}',
        output: '{this.stereo.mode}',
    })
seekPodcast() { ... }

@PodcastError

This action logs an error when triggered whenever an error occurs during a listening session.

Using the @PodcastError annotation triggers a listening_session_error event. This event lets us know when an error related to the listening session has occurred.

Annotation Element

Example of usage

@PodcastError({
        crid: '{this.podcastInfo.crid}',
        position: '{this.currentPosition}',
        reason: 'Network timeout',
        output: '{this.stereo.mode}',
    })
errorPodcast() { ... }

@ActionFavorite

This action indicates that the user has provided feedback on the currently playing media by marking it as liked or disliked. To populate the like field, we recommend to follow the notation supported (see here).

Using the @ActionFavorite annotation triggers an action event. This event lets us know when the user has performed an action on their favorites (e.g., adding or removing a favorite).

Annotation Element

Example of usage

@ActionFavorite({
        uiSource: 'uiSource-favorite',
        mediaId: '200',
        mediaType: 'STATION',
        favorite: '{Opinion.LIKE}',
        sourceScreen: '{UiStatus.HOME}',
    })
triggerFavoriteAction() { ... }

@ActionPlayback

This action reports the status of media playback, for instance, when a station is buffering or the playback status is updated. To populate the player field, we recommend to follow the notation supported.

Using the @ActionPlayback annotation launches an action event. This event lets us know when the user has interacted with the playback controls.

Annotation Element

*Optional: if not provided, defaults to PlaybackStatus.BUFFERING.

Example of usage

@ActionPlayback({
        uiSource: 'uiSource-playback',
        mediaId: '201',
        mediaType: 'STATION',
        player: '{PlaybackStatus.PLAYING}'
    })
triggerPlaybackAction() { ... }

@ActionRadioMode

This action is used to change the radio band , for example, switching to FM mode. To populate the uiSource field, we recommend to follow the notation supported.

Using the @ActionRadioMode annotation launches an action event. Through this event, we understand when the user has changed or interacted with the radio mode (AM, FM, DAB etc.).

Annotation Element

*Optional: if not provided, defaults to RadioMode.DAB.

Example of usage

@ActionRadioMode({uiSource: 'uiSource-radio-mode', radioMode: 'RadioMode.DAB'})
triggerRadioMode() { ... }

@ActionRecClicked

This action indicates that a recommendation was clicked, such as a suggested station or podcast. It captures which recommended item was selected.

Using the @ActionRecClicked annotation, an action event is triggered. This event lets us know when the user has clicked on recommended content.

Annotation Element

Example of usage

@ActionRecClicked({
        uiSource: 'uiSource-radio-mode',
        clickedRecId: '202',
        clickedRecType: 'EPISODE'
    })
triggerRecClickedAction() { ... }

@ActionRecClickedSearchResult

This action indicates that a search result item was clicked. It captures which result was selected.

Using the @ActionRecClickedSearchResult annotation, an action event is triggered. This event lets us know when the user has clicked on a search result within the recommendations.

Annotation Element

*Optional: if not provided, defaults to MediaSource.RADIO_ON_BOARD.

Example of usage

@ActionRecClickedSearchResult({
        uiSource: 'uiSource-rec-clicked-search-result',
        clickedMediaId: '203',
        clickedMediaType: 'EPISODE',
    })
triggerRecClickedSearchResultAction() { ... }

@ActionRecSearch

This action indicates that a search was performed. It records the search query.

Using the @ActionRecSearch annotation launches an action event. This event lets us know when the user has performed a search in the recommendation system.

Annotation Element

Example of usage

@ActionRecSearch({
        uiSource: 'uiSource-rec-search',
        searchedValue: 'searched-value',
    })
triggerRecSearchAction() { ... }

@ActionSourceChange

This action indicates that the active radio station has changed and tracks who triggered the change. It distinguishes between an explicit user-initiated change and an automatic/non-explicit change.

Using the @ActionSourceChange annotation, an action event is triggered. Through this event, we understand when the user has changed the playback source (e.g. On-board radio, Mobile Mirroring, Bluetooth, AUX).

Annotation Element

*Optional: if not provided, defaults to MediaSource.RADIO_ON_BOARD.

Example of usage

@ActionSourceChange({
        uiSource: 'uiSource-source-change',
        mediaSource: 'media-source',
    })
triggerSourceChangeAction() { ... }

@ActionStationChange

This action indicates that the active radio station has changed and tracks who triggered the change. It distinguishes between an explicit user-initiated change and an automatic/non-explicit change.

Using the @ActionStationChange annotation, an action event is triggered. Through this event, we understand when the user has changed radio stations.

Annotation Element

*Optional: if not provided, defaults to Enablement.OFF.

Example of usage

@ActionStationChange({
        uiSource: 'uiSource-station-change',
        mediaId: '{this.radioInfo.rpuid}'
    })
triggerStationChangeAction() { ... }

@ActionBroadcast

Annotation Element

Example of usage

@ActionBroadcast({
        uiSource: 'uiSource-broadcast',
        deviceName: 'device-name',
        deviceType: 'phone',
    })
triggerBroadcastAction() { ... }

@ActionDownload

Allows you to track a download and its status.

Example of usage

@ActionDownload({
        uiSource: 'uiSource-download',
        crid: '{this.podcastInfo.crid}',
        countryCode: '{this.radioInfo.countryCode}',
        state: '{DownloadStatus.START}',
    })
triggerDownloadAction() { ... }

@ActionFilter

Allows you to track a requested filtering action.

Example of usage

@ActionFilter({ uiSource: 'uiSource-filter', filter: 'genre' })
triggerFilterAction() { ... }

@ActionShareContent

Allows you to track a requested content sharing.

Example of usage

@ActionShareContent({
        uiSource: 'uiSource-share-content',
        mediaId: '{this.radioInfo.rpuid}',
        mediaType: 'STATION',
        countryCode: '{this.radioInfo.countryCode}',
    })
triggerShareContentAction() { ... }

@ActionTimerSet

Allows you to track the setup of a timer.

Example of usage

@ActionTimerSet({ uiSource: 'uiSource-timer-set', minutes: 30, })
triggerTimerSetAction() { ... }

@SetValue

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

Annotation Element

Example of usage

@SetValue({ key: 'radio_mode', value: '{this.stereo.mode}' })
setModeValue() { ... }

@MetadataUpdate

This action reports an update to the metadata of the currently playing media, such as the artist , song title , and album.

Using the @MetadataUpdate annotation triggers a metadata_update event. This event lets us know when the metadata of the content being played (e.g., song title, artist) has been updated.

Annotation Element

Example of usage

@MetadataUpdate({
        mediaId: '{this.radioInfo.rpuid}',
        bearer: '{this.radioInfo.bearer}',
        artist: '{this.currentTrack.artist}',
        song: '{this.currentTrack.song}',
        album: '{this.currentTrack.album}',
        show: '{this.currentTrack.show}',
        scheduleStart: '{this.currentTrack.scheduleStart}',
        scheduleStop: '{this.currentTrack.scheduleStop}',
    })
updateMetadata() { ... }

@ErrorEvent

This action reports a generic unexpected runtime error on the mobile app during normal execution.

Annotation Element

Example of usage

@Error({
        errorType: '{CategoryError.API}',
        source: 'home-screen',
        severity: '{Severity.CRITICAL}',
        reason: '500 response',
        stackTrace: '{this.error.stackTrace}'
    })
error() { ... }

Recommended annotations for a first integration

Not all annotations are strictly required from the start. For those approaching the SDK for the first time, it is recommended to focus on the annotations marked with a relevance level of High , as these represent the core integration points for correct and complete functionality.

Annotations with a Medium or Low relevance level can be introduced at a later stage, as the integration matures or based on the specific needs of the product.

Enumeration

Other

Consent Management:

Why this class exists

Radioplayer processes different types of data depending on what the user has agreed to. Privacy regulations (ePrivacy Directive, GDPR) require that some of these activities — particularly anonymous usage analytics and precise location retention — only take place when the user has explicitly opted in.

Internally, the SDK maps the consent flags to one of three operating levels defined by CmpState:

Consent dependency

Granting location consent automatically implies analytics consent, because location retention is a superset of the analytics processing level. It is not possible to enable location analytics while keeping usage analytics disabled.

Usage

Use the enumeration and the proper method:

import { TrackingSDK, CmpState, } from '@radioplayer/mobile-tracking-sdk';

// ...
sdk.updateConsent(cmpState.FULL_SERVICE_LOCATION_ANALYTICS)

DeviceInfo Class

The DeviceInfo class is a data object for managing device information. The primary goal is to create a unique yet deterministic ID for each device.

Properties:

• id (String): A unique, deterministically generated identifier for the device object;
• deviceType (String): Textual identifier of the device type, obtained by concatenating maker, model and year;
• maker (String): The device's manufacturer;
• model (String): The device's model;
• osName (int): The device OS name;
• osVersion (number): The device OS version;

How the Deterministic ID Works

The ID is automatically generated by the class constructor. This ID is deterministic , meaning that if you use the same parameters (maker, model, osName, osVersion, and pseudoId), the generated ID will always be identical. This feature is useful for identifying the same device across different tracking sessions or applications without relying on an external identifier.

The ID generation process uses a combination of these parameters. Specifically, the maker string, model string, and year, combined with the pseudoId, create a hash that is then converted into a UUID Type 5, ensuring the ID is both immutable and deterministic but at the same time, not invertible.

APPENDIX

A. Country Code

The International Organization for Standardization (ISO) created and maintains the ISO 3166 standard – Codes for the representation of names of countries and their subdivisions. A country code is a standardised identifier that uniquely represents a country (or territory) in computer systems. In this SDK, we exclusively use the ISO 3166-1 numeric standard which defines 3-digit numeric codes (script-independent).

Validation rules

• Length : must be exactly 3 digits.
• Permitted characters : numbers only (0–9), no spaces or symbols.
• Padding : if the code includes leading zeros, they must be included (e.g. 004, 008).
• Permitted values : the value must belong to the official ISO 3166-1 numeric list (no custom values).
• _Implementation advice_ : treat the value as a string to preserve any leading zeros.

Current ISO 3166 country codes

For an updated list, see: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes#Current_ISO_3166_country_codes

ISO 3166 country codes (last updated on February 2026)

B. Country Code vs Catalog Country Code

CountryCode

Indicates the country associated with the media currently being played (e.g., selected radio station, selected podcast/stream). Therefore, it changes based on the content being played.

CatalogCountryCode

Indicates the country of the content catalog used by the app for browsing/searching/listing. This value is chosen when the app is initialized and remains stable until it is reinitialized/changed.

Why they may be different

A user may want to listen to content from the Italian catalog (CatalogCountryCode = IT), but be located in Germany (CountryCode = DE).

In this case, an FM/DAB scan based on the receiver will mainly find German stations, because it depends on local coverage and the region where the device is located.

Practical example

_CatalogCountryCode_ = IT → the user is browsing/filtering “Italy” content (Italian stations, metadata, IT market lineup).

_CountryCode_ = DE → the tuner scan/search returns frequencies/stations that can be received in Germany.

C. WRAPI

The Radioplayer Partner API (WRAPI) provides developers with unparalleled access to broadcasters' streaming radio programming and proprietary metadata. You can use this to build a rich and flexible hybrid radio experience for your customers.

The base address for the Radioplayer Partner API (WRAPI) is: api.radioplayer.org/v2/

There are ten endpoints to the Radioplayer Partner API (WRAPI):

WRAPI endpoints

For complete documentation, see Radioplayer Partner API (WRAPI) documentation.

D. RadioConnectApi

TBD

E. RPUID

TBD

F. Category Error

Below is an explanation of the values in the CategoryError enumeration.

G. Radio Mode

Below is an explanation of the values in the RadioMode enumeration.