Radioplayer Developer Reference

Automotive Tracking SDK

Technical documentation for implementing Radioplayer automotive data tracking.

Version

2.1.1

Document type

API / SDK reference

Audience

Automotive partner engineering teams

This is the documentation for the Radioplayer Automotive SDK, version 2.1.1.

General principles

The 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 Automotive 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.

Tracker Initialization and Configuration

SDK Access & Authentication

Radioplayer adopts a Service Account Pattern to ensure scalability, security, and fine-grained access control. To integrate the Radioplayer Automotive Data Tracking SDK, please adhere to the following access protocols:

• Repository: The SDK is hosted within a private GitHub repository.
• Access Provisioning: Access is granted exclusively through a dedicated Radioplayer service account.
• Authentication: Authentication is handled via GitHub Personal Access Tokens (PATs) , which will be provided directly by the Radioplayer team upon request.
• Permissions: For security purposes, all provided access is strictly read-only.

How to import the Radioplayer Automotive Data Tracking SDK

1. In settings.gradle.kts, add dependencyResolutionManagement section:

   dependencyResolutionManagement {
       // ...
       repositories {
           // ...
           maven {
               url = uri("https://maven.pkg.github.com/Radioplayer/dataplatform-automotive-tracking-sdk")
               credentials {
                   username = "<github_username>"
                   password = "<your_PAT_with_packages:read>"
               }
           }
           // ...
       }
       // ...
   }

2. Add the following code to the dependencies section of your build.gradle.kts (:yourApp):

   implementation("org.radioplayer.automotivesdk:sdktracking:2.1.1")
   annotationProcessor("org.radioplayer.automotivesdk:sdkprocessor:2.1.1")
   annotationProcessor("org.radioplayer.automotivesdk:sdkannotation:2.1.1")

3. Check your setup and use:

   1. For older API level (e.g. 28) and Java version < Java 9, you may need to add this in build.gradle.kts (:yourApp):

      implementation "androidx.lifecycle:lifecycle-common-java8:2.2.0"

   2. For newer API level and Java version >= Java 9

      • you likely have to add or modify this variable in gradle.properties in order to javac arguments:

        // in this example, we used Java 17
        org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8 \
        --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
        --add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
        --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \
        --add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
        --add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED \
        --add-modules=jdk.compiler
        org.gradle.java.home=/usr/lib/jvm/jdk-17.0.12-oracle-x64

      • For dependency issues, we recommend forcing them to the desired version in build.gradle.kts :root:

        // e.g.
        allprojects {
            configurations.all {
                resolutionStrategy {
                    force(
                        "androidx.core:core:1.12.0",
                        "androidx.core:core-ktx:1.12.0",
                        "androidx.appcompat:appcompat:1.6.1",
                        "androidx.appcompat:appcompat-resources:1.6.1",
                        "androidx.activity:activity:1.7.2",
                        "androidx.activity:activity-ktx:1.7.2",
                        "androidx.constraintlayout:constraintlayout:2.1.4",
                        "androidx.profileinstaller:profileinstaller:1.3.1",
                        "androidx.annotation:annotation-experimental:1.3.1"
                    )
                }
            }
        }

4. Add these imports to every class you want to annotate:

   import org.radioplayer.automotiveSDK.EventFactory.action.*;
   import org.radioplayer.automotiveSDK.EventFactory.listening.*;
   import org.radioplayer.automotiveSDK.EventFactory.setValue.*;
   import org.radioplayer.automotiveSDK.EventFactory.EventManager;
   import org.radioplayer.automotiveSDK.Tracker;
   import org.radioplayer.automotiveSDK.annotation.*;

5. Add these uses-permission to AndroidManifest.xml file:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Initialization and Configuration

Once you have imported the Radioplayer Automotive 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 org.radioplayer.automotiveSDK.TrackingSDK;
// ...
TrackingSDK sdk = TrackingSDK.getInstance();
sdk.initialize(
    this, //context
    "SDKAndroidAppDemo", //appName
    "1.0.0",     //appVersion
    platformId,  // provided by RP
    productId,   // provided by RP
    new VehicleInfo("Jade Dragons Inc.", "Qilin",2022), //vehicle info
    apiUrl, //apiUrl - provided by RP
    appKey, //appKey - provided by RP
    debug   // boolean to enable verbose debug logging
);
sdk.startTracking(debug, catalogCountryCode, null);

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:

sdk.initialize(
    this, //context
    "SDKAndroidAppDemo", //appName
    "1.0.0",     //appVersion
    platformId,  // provided by RP
    productId,   // provided by RP
    new VehicleInfo("Jade Dragons Inc.", "Qilin",2022), //vehicle info
    apiUrl, //apiUrl - provided by RP
    appKey, //appKey - provided by RP
    debug   // boolean to enable verbose debug logging
);

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.

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 will simply need to pass true as the first debug parameter in the start method).

sdk.startTracking(
    true,  //debug
    ...);

In the logcat console, in addition to possible warnings about listening session management, the following debug information will also be displayed:

• Each tracked event, along with the collected parameters.
• Whether the events are received correctly by the Radioplayer dataplatform. In case of error or warning, it will be reported and the error type will also be shown.

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 permissions granted. 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 vehicle 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.

These optimizations were specifically implemented to meet the needs of the OEM, guaranteeing reliable and complete data transmission.

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 org.radioplayer.automotiveSDK.annotation.domainEnums.*;

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 Java/Kotlin 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 (see here) to ensure data integrity and avoid runtime errors.

Allowed parsing

• Call to methods

  @SetValue(key = "SwitchStereoMode", value = "{getStereoMode()}")
  //inject:  String.valueOf(getStereoMode())

• Call to methods with args

  @SetValue(key = "SwitchStereoMode", value = "{getStereoMode(arg1, arg2)}")
  //inject:  String.valueOf(getStereoMode(arg1, arg2))

• Field access

  @SetValue(key = "SwitchStereoMode", value = "{stereo.mode}")
  //inject:  String.valueOf(stereo.mode)

• Array element access

  @SetValue(key = "FavRadio", value = "{freqRadioFav[1]}")
  //inject:  String.valueOf(freqRadioFav[1])

• Allowed keyword/ Keyword recognition:

  @SetValue(key = "RadioFocus", value = "{true}")
  //inject:  String.valueOf(true)

  • true
  • false
  • null

• Number (int, float, double)

  @SetValue(key = "VolumeLevel", value = "{50}")
  //inject:  String.valueOf(50)

• Explicit string

  @SetValue(key = "{\"Test\"}", value = "{\"Not work\"}")
  //inject:  String.valueOf()

• Return Escape Value

  @SetValue(key = "{\"Test\"}", value = "{{RETURN}}")

• Some other example

  @SetValue(key = "SwitchStereoMode", value = "{this.changeRadio(stereo,\"TurnOn\",105.10)}")
  //inject:  this.changeRadio(stereo,"TurnOn",105.10)

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

  • List<String>
  • Map<Integer, String>
  • new ArrayList<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 Automotive Tracking SDK.

@Trackable(trackableName = "TestAutomotiveSDK", origin = "TestAutomotiveSDK", featureOrigin = "RadioSettings")
public class ExampleClass {
    // ...
}

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

@RadioStart(rpuid = "{radioStations.get(currentPosition).getMediaId()}",
    bearer = "{radioStations.get(currentPosition).getBearers().get(0).getId()}",
    radioMode = "{RadioMode.DAB}", volume = "{10}", countryCode = "276")
public void ExampleMethod() {
    // ...
}

@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 = "{radioStations.get(currentPosition).getMediaId()}",
    bearer = "{radioStations.get(currentPosition).getBearers().get(0).getId()}",
    radioMode = "{RadioMode.DAB}", volume = "{this.getDeviceVolume()}", countryCode = "{countryCode}")
public void ExampleMethod() {
    // ...
}

@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 automotive 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 = "380101", bearer = "dab:ce1.c185.c500.0", countryCode = "{528}")
public void ExampleMethod() {
    // ...
}

@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 (see here).

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

@RadioSkip(newRpuid = "380101", newBearer = "dab:ce1.c185.c500.0", countryCode = "{100}")  // DEFAULT: {SkipStatus.NEXT}
@RadioSkip(newRpuid = "380101", newBearer = "dab:ce1.c185.c500.0", countryCode = "{100}", skipType = "{SkipStatus.PREVIOUS}")

@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 = "380101", countryCode = "{100}", bearer = "dab:1e0.11f7.12e9.0")  // DEFAULT: {SeekStatus.FORWARD}
@RadioSeek(rpuid = "380101", countryCode = "{100}", bearer = "{this.bearer}", seekType = "{SeekStatus.BACKWARD}"))

@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 = "380101", bearer = "{bearer}", reason = "")

@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 = "{currCrid}", countryCode = "{countryCode}", position = "{10}")

@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 = "{currCrid}", countryCode = "{countryCode}", position = "{300}")

@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 automotive 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 = "{currCrid}", countryCode = "{countryCode}", position = "{120}")

@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 = "{currCrid}", countryCode = "{this.countryCode}", position = "{1000}") // DEFAULT: {SkipStatus.NEXT}
@PodcastSkip(newCrid = "{currCrid}", countryCode = "{528}", position = "{1000}", skipType = "{SkipStatus.PREVIOUS}")

@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 = "{currCrid}", countryCode = "{this.countryCode}", position = "{1000}") // DEFAULT: {SeekStatus.BACKWARD}
@PodcastSeek(crid = "{currCrid}", countryCode = "{this.countryCode}", position = "{1000}", seekType = "{SeekStatus.BACKWARD}"))

@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 = "{currCrid}", position = "{0}", reason = "No podcast detected")

@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(type = "ClickOnLikeButton", uiSource = "likeIcon",
    mediaId = "{this.mediaId}", mediaType = "STATION", favorite = "{Opinion.LIKE}")
fun setLike() { ... }

@ActionFavorite(type = "ClickOnLikeButton", uiSource = "dislikeIcon",
    mediaId = "{this.mediaId}", mediaType = "STATION", favorite = "{Opinion.DISLIKE}")
fun setDislike() { ... }

@ActionMobileMirroring

This action indicates the status of a mobile mirroring connection, such as Android Auto. To populate the mobileMirroringType field, we recommend to follow the notation supported (see here).

Annotation Element

Example of usage

@ActionMobileMirroring(type = "SmartphoneConnected", uiSource = "None", mobileMirroringType = "{SIS.AndroidAuto}")

@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 (see here).

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(type = "Update Scan", uiSource = "Radio", mediaId = "380101", mediaType = "STATION", player = "{PlaybackStatus.PAUSED}")
@ActionPlayback(type = "PlayBackStatus", uiSource = "Radio", mediaId = "380101", mediaType = "STATION", player = "{this.status}")
@ActionPlayback(type = "PlayBackStatus", uiSource = "Radio", mediaId = "380101", mediaType = "STATION") // DEFAULT: {PlaybackStatus.BUFFERING}

@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 (see here).

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(type = "changeBand", uiSource = "{uiController.getBtnFM()}",radioMode = "{radio}")
@ActionRadioMode(type = "changeBand", uiSource = "{uiController.getBtnFM()}")  // DEFAULT: {RadioMode.DAB}

@ActionRadioPower

This action reports the power state of the radio (on or off). To populate the status field, we recommend to follow the notation supported (see here).

Using the @ActionRadioPower annotation, an action event is triggered. Through this event, we understand when the user has turned the radio on or off via the interface.

Annotation Element

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

Example of usage

@ActionRadioPower(type = "PowerMode", uiSource = "{this.radioON.getValue()}") // DEFAULT: {Enablement.ON}
@ActionRadioPower(type = "TestRadioPower", uiSource = "RadioPower", status = "{Enablement.OFF}")

@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(type = "TestRecClicked", uiSource = "Recommendation", clickedRecId = "1234")

@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(type = "TestRecClicked", uiSource = "Recommendation", clickedMediaId = "276058", clickedMediaType = "PODCAST")

@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(type = "TestRecClicked", uiSource = "Recommendation", searchedValue = "RadioName")

@ActionScan

This action indicates that the radio has started a scan for available stations and can list the frequencies it finds.

Using the @ActionScan annotation, an action event is triggered. This event lets us know when the user/device has started a scan (e.g., of radio frequencies).

Annotation Element

Example of usage

@ActionScan(type = "ScanAction", uiSource = "startScan", status = "Started", radioFound = "started", frequencyFound = "[radio1,radio2]")

@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(type = "TestMediaSource", uiSource = "MediaSource", mediaSource = "{MediaSource.AUX}")
@ActionSourceChange(type = "TestMediaSource", uiSource = "MediaSource") // DEFAULT: {MediaSource.RADIO_ON_BOARD}

@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(type = "TestStationChange", uiSource = "Radio", bearer = "dab:ce1.c185.c479.0")

@ActionUiFocus

This action indicates that the user has changed the radio app focus.

Using the @ActionUiFocus annotation, an action event is triggered. Through this event, we understand when the user has focused their attention on the radio app or on the home screen/other apps.

Annotation Element

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

Example of usage

@ActionUiFocus(type = "TestUiFocus", uiSource = "FOCUS") // DEFAULT: {Enablement.ON}
@ActionUiFocus(type = "TestUiFocus", uiSource = "FOCUS", focus="{Enablement.OFF}")

@ErrorEvent

This action logs an error when triggered.

Using the @ErrorEvent annotation triggers an error event. This event lets us know when a generic error has occurred in the system.

Annotation Element

Example of usage

@ErrorEvent(type = "{CategoryError.PERSISTENCE}", source = "ConsoleButton", severity = "{Severity.CRITICAL}", reason = "Click on button when radio state is off", stackTrace = "{e.getStackTrace().toString()}")
@ErrorEvent(type = "{CategoryError.GENERAL}", source = "ConsoleButton", severity = "{Severity.WARN}", reason = "Click on button when radio state is off")

@SetValue

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

Annotation Element

Example of usage

@SetValue(key = "getCurrentFrequency", value = "{{RETURN}}")

@SystemEventCalling

Used to detect interruptions. Essential for calculating real-time listening sessions and adjusting session metrics. To populate the status field, we recommend to follow the notation supported (see here).

Using the @SystemEventCalling annotation triggers a system_event_calling event. This event lets us know when a system event related to a phone call has occurred (start or end of call).

Annotation Element

*Optional: if not provided, defaults to CallingStatus.NO_CALL.

Example of usage

@SystemEventCalling() // DEFAULT: {CallingStatus.NO_CALL}
@SystemEventCalling(status = "{CallingStatus.RINGING}")

@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 = "{currentOnAirInfo.getMediaId()}",
    bearer = "{currentOnAirInfo.getBearer()}",
    artist = "{currentOnAirInfo.getSongArtist()}",
    song = "{currentOnAirInfo.getSongName()}",
    album = "{currentOnAirInfo.getAlbumName()}",
    show = "{currentOnAirInfo.getShowName()}",
    scheduleStart = "{currentOnAirInfo.getSongStart()}",
    scheduleStop = "{currentOnAirInfo.getSongEnd()}")

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

• For more information about CategoryError see here.

** For more information about RadioMode see here.

Other

Consent Management: CmpConsent

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. CmpConsent is the bridge between the consent decision shown to the user in the car's UI and the SDK's internal behaviour.

Relationship with CmpState

Internally, the SDK maps the consent flags carried by a CmpConsent instance 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 one of the three factory methods that mirror the options presented to the user in the consent UI, or the Builder when the flags come from a custom CMP integration.

// User chose "Essential Radio Services"
CmpConsent consent = CmpConsent.essentialOnly();

// User chose "Essential Services + Usage Analytics"
CmpConsent consent = CmpConsent.withAnalytics();

// User chose "Full Service + Location Analytics"
CmpConsent consent = CmpConsent.fullService();

// Consent flags sourced from a custom CMP integration
CmpConsent consent = new CmpConsent.Builder()
    .analyticsConsent(userGrantedAnalytics)
    .locationConsent(userGrantedLocation)
    .build();

VehicleInfo Class

The VehicleInfo class is a data object for managing vehicle information. It's designed to encapsulate an automobile's basic details like maker, model, year, and a list of features. The primary goal is to create a unique yet deterministic ID for each vehicle.

Properties:

• id (String): A unique, deterministically generated identifier for the vehicle object;
• vehicleType (String): Textual identifier of the vehicle type, obtained by concatenating maker, model and year;;
• maker (String): The vehicle's manufacturer;
• model (String): The vehicle's model;
• year (int): The vehicle's manufacturing year;
• features (Set<String>): A set of specific vehicle features (e.g., "DAB", "FM", "Bluetooth").

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, year, and pseudoId), the generated ID will always be identical. This feature is useful for identifying the same vehicle across different tracking sessions or applications without relying on an external identifier (like the VIN, which might not always be available due to permission restrictions).

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.

ID retrieval

The TrackingSdk support this method for requests deletion of the user data:

public String retrievalUserId()

The method:

• retrieves the current device ID,
• removes it from local storage.

Usage

You can create a VehicleInfo instance using one of the available constructors depending on the information you have.

1. Creating a VehicleInfo object with basic data:

   VehicleInfo car1 = new VehicleInfo("Chimera Motors", "Manticore", 2024);
   VehicleInfo car2 = new VehicleInfo("Siren Automotive", "Leviathan", 2023);
   
   // car1.getId() and car2.getId() will return deterministically generated IDs

2. Creating an object with additional features:

   List<String> features = Arrays.asList("FM", "DAB", "Navigation", "Apple CarPlay");
   VehicleInfo carWithFeatures = new VehicleInfo("Asgardian", "Valkyrie", 2022, features);

3. Creating an object with a custom pseudo-ID:

If you need to associate the vehicle with a specific identifier (like a user ID or an internal session), you can use the constructor with the pseudoId.

String userId = "user-12345";
VehicleInfo carWithUser = new VehicleInfo("Nautilus Drives", "Kraken", 2024, null, userId);

// The generated ID will always be the same for "Nautilus Drives", "Kraken", 2024, and "user-12345"

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