Roku SDK Release Notes

In this topic, you will find the latest information on changes and enhancements to the Roku SDK.

Current release

Version 2.0.0

18 Sep 2024

Changed:

  • Changed Brightcove's EPA requests Authorization header to Bcov-Auth.
  • The bcPlayer.closeOnBack field is now a string. The supported values are soft, hard and off.
  • Changed the default bcPlayer.LogLevel field value to 0.
  • The bcPlayer.width and bcPlayer.height fields values now default to the screen resolution.
  • The bcPlayer.on.playlistIndex event now reflects the bcPlayer.playback.index field from the new custom playlist implementation.
  • The bcPlayer.on.close event data is now an AssociativeArray object that specifies what type of close action was executed.
  • Changed the following options in the bcPlayer.load() function:
    • The position supported values are now replace, append and prepend.
    • Added the prebuffer option to control whether it should prebuffer the video or start playback.
  • The bcPlayer.loadCustom() function now applies the specified position option.
  • Switched the order of the debug and verbose log levels in the Logger component. Verbose is now 4 and debug is now 3. This change means that verbose is the new default log level.
  • It's now possible to access bcAPI features right after creating a node instance without having to observe its ready field.
  • (CSAS) RAF's setAdPrefs() maxRequests property now defaults to 5.
  • The play_request Data Collection event is now only triggered once per video playback session.

Fixed

  • (CSAI) Fixed RAF's setAdConstraints() being set when bcPlayer.csai.adConstraints is set to {} (the default value).
  • Fixed Brightcove DRM sources filtering.
  • Fixed v7 HLSe sources manifest support.
  • Fixed the sources fresh not reusing the original ad_config_id and config_id Playback API parameters.
  • Fixed request refresh not allowing pending HTTP requests to complete before closing.
  • Fixed the seq and range Data Collection metric values.
  • Fixed the bcPlayer.analytics.eventOut not providing the event name.
  • Fixed the application/vnd.apple.mpegurl Brightcove sources not being recognized as HLS.

Added

  • Added the missing event property in bcPlayer.analytics.eventOut.
  • Added the following bcPlayer.on events:
    • pause – triggered when video playback is paused.
    • loadItem – triggered when a new video is loaded.
    • closed – triggered when the bcPlayer closes completely.
    • timeout – triggered when buffering times out, when enabled.
  • Added the reqParams field into Brightcove videos ContentNodes. This field contains the Playback API request query parameters. Applicable to both the bcPlayer and bcAPI components.
  • Added support for audio-only MP4 sources.
  • Added the bcPlayer.retryOnBufferTimeout configuration field, allowing the retry function to be configured to trigger upon a buffering timeout.
  • Added the bcPlayer.relativePosition read-only field which specifies the relative playback position when playing SSAI videos.
  • Added the bcPlayer.closeOnFinished field. The supported values are soft, hard, and off.
  • Added the bcPlayer.enableGsc field to toggle the Generic Stream Concurrency feature on and off.
  • Added the bcPlayer.visibleOnScreen read-only field which specifies if the bcPlayer node is visible in the screen based on its size, position, and visible and opacity fields.
  • Added support for CSAS on SSAI videos streams (pre-rolls only).
  • Added support for both CSAS and SSAI on playlist videos.
  • Added a new custom playlist implementation which can be controlled through the bcPlayer.playback node.
  • Added support for Brightcove's Generic Stream Concurrency feature.
  • Added the next and previous playlist buttons into the Video.pivotNode node when bcPlayer.enableUI is enabled.
  • Added the prebuffer option to the bcPlayer.load() function.
  • Added the following properties to the bcPlayer.on.load event data:
    • autoplay – specifies the bcPlayer.load() or loadCustom() autoplay option value.
    • prebuffer – specifies the bcPlayer.load() or loadCustom() prebuffer option value.
    • position – specifies the bcPlayer.load() or loadCustom() position option value.
  • Added support for Brightcove Ad Insight events and metrics.
  • Added the following Brightcove Data Collection metrics:
    • ip_address – the hop device external IP address.
    • user_agent – Roku's user-agent value as per roUrlTransfer.GetUserAgent().
    • platform – hardcoded to roku-sdk.
    • content_type – hardcoded to video.
    • delivery_type – ondemand for VOD, live for live streams.
    • real_time_ms – playback start time.
    • load_time_ms – video load time.

Deprecated

  • Removed the bcPlayer.playlist() function as playlist functions can now be accessed through the bcPlayer.playback field.
  • Removed the bcPlayer.playback() function as playback functions can now be accessed through the bcPlayer.playback field.
  • Removed the following bcPlayer.csai fields:
    • useCSAS – it wasn't used as only CSAS implementation is currently supported.
    • closeOnFinish – replaced by the bcPlayer.closeOnFinish field.
    • enableJIT – it was only applicable to the custom CSAI implementation (currently only CSAS is supported).
    • enableInPodStitching – it was only applicable to the custom CSAI implementation (currently only CSAS is supported).
  • Removed CSAS RAF's enableInPodStitching configuration as it's only applicable to the custom CSAI implementation (currently only CSAS is supported).
  • The native Video playlist setup is no longer supported. The bcPlayer.playback node should instead be used to setup and manage playlists. The following alternatives are provided to the most common playlist related Video fields:
    • Video.contentIsPlaylist – the bcPlayer.playback.callFunc("is", "playlist") solution should be used instead.
    • Video.playlistIndex – the bcPlayer.playback.index field should be used instead.
    • Video.nextContentIndex – the bcPlayer.playback.callFunc("playNext"), bcPlayer.playback.callFunc("playPrevious") or bcPlayer.playback.callFunc("play") solutions should be used instead.

Previous releases

Version 1.0.0

01 May 2024

Changed

  • The account_id property is now required by the bcPlayer load function to load Brightcove videos metadata. This property value must match the bcPlayer credentials.account_id config value.
  • Renamed the bcPlayer addSource function to loadCustom and changed the following items in this function:
    • Added the autoplay options property to specify the index that should start playing once the metadata is loaded. Defaults to 0, plays the first item.
    • Added the prebuffer options property to specify whether it should preload the stream or start the playback. Only applicable to single videos.
    • Removed the position options property. loadCustom will always replace the existing content.
    • loadCustom now also triggers a bcPlayer on.load event.
  • Renamed the bcPlayer on.play event to on.playing. This event is triggered when the Video state is set to playing.
  • Added the property reason to the bcPlayer on.finished event data, specifying what caused the stream to finish. The possible values are:
    • stopped: the playback has been interrupted either by the user or another operation.
    • finished: the playback has completed. It either reached the end of the stream or a playback error occurred.

Fixed

  • Fixed the Utils toString function not properly formatting Associative Arrays and Arrays.

Added

  • Added bcPlayer on.isHidden event: indicates if the bcPlayer node is completely hidden based on the renderTracking value.
  • Added bcPlayer sdkVersion field: provides the SDK version number.
  • Added bcPlayer voiceControls field: toggles custom voice controls handling on/off (currently only the "next" voice command is handled by the bcPlayer, all other commands are handled natively by the Video node).
  • Added adPlaying field: indicates if an ad is playing.
  • Added support for Brightcove Analytics.
    • Added bcPlayer analytics field which allows for some BC Analytics parameters to be customized:
      • accountId: specifies the Videocloud account ID used in the Analytics events. If not set, the bcPlayer credentials are used.
      • url: specifies a different URL where the BC Analytics metrics should be redirected to. Useful for debugging purposes.
      • applicationID: used to denote a specific instance or application of a player.
      • env: specifies the Brightcove Analytics API environment. Defaults to production.
      • playerId: used to build the player_name parameter. Useful for metrics filtering purposes.
      • viewerId: used to build the player_name parameter. Useful for metrics filtering purposes.
      • user: specifies a user identification.
      • orientation: specifies the destination parameter.
      • source: specifies the source parameter.
      • eventOut: [read-only] allows access to all the events data every time an event is triggered.
  • The following events are supported:
    • player_load
    • player_ready
    • catalog_request
    • catalog_response
    • catalog_error
    • video_impression
    • play_request
    • video_view
    • video_engagement
    • ad_mode_begin
    • ad_mode_complete
  • Added support for Brightcove SSAI
    • SSAI playback is not supported with native playlists.
    • Added bcPlayer ssai field which allows for some SSAI parameters to be customized:
      • enabled: enabled or disable SSAI handling.
      • enabledDiscontinuities: toggles playback with Discontinuities in HLS & MultiPeriods in Dash. More info here.
      • adMeasurements: allows the ad measurement parameters to be overridden. If set to invalid, RAF.enabledAdMeasurements() will be disabled. If set to an AssocArray, the following optional properties are supported:
        • childDirected: specifies the RAF.setContentGenre() childDirected parameter. Defaults to false.
        • contentId: specifies the RAF.setContentId() parameter. If not provided, the video ContentNode id field is used instead.
        • contentGenre: specifies the RAF.setContentGenre() parameter. If not provided, the video ContentNode Categories or tags field is used instead.
        • contentLength: specifies the RAF.setContentLength() parameter. If not provided, the video ContentNode Length field is used instead. It's set to a value of 999999 in Live videos.
        • bcovToken: specifies the token used to authorize playback of HLSe streams protected by Brightcove's Playback Authorization Service.
        • macros: specifies the list of macros and respective values that will be replaced in the VMAP ad tag. These only apply to the variables specified as {url.*} in the VMAP ad tag. More info here.
        • event: [read-only] allows access to all the ads related events.
  • Added support for CSAI through RAF's CSAS implementation.
    • CSAI playback is not supported with native playlists.
    • CSAI does not support the Retry Playback feature.
    • Playback control over CSAI streams should be done through the bcPlayer playback function.
    • Added bcPlayer csai field which allows for some CSAI parameters to be customized:
      • enabled: enabled or disable CSAI handling.
      • useCSAS: use RAF's CSAS implementation (WIP: changing this setting has no effect. It's always enabled).
      • closeOnFinish: specifies if the bcPlayer should close when a CSAI source playback finishes.
      • maxRequests: specifies RAF.setAdPrefs() maxRequests parameter.
      • enableJIT: specifies RAF.enableJITPods() parameter.
      • enableInPodStitching: [WIP] not supported.
      • adMeasurements: allows the ad measurement parameters to be overridden. If set to invalid, RAF.enableAdMeasurements() will be disabled. If set to an AssocArray, the following optional properties are supported:
        • childDirected: specifies the RAF.setContentGenre() childDirected parameter. Defaults to false.
        • contentId: specifies the RAF.setContentId() parameter. If not provided, the video ContentNode id field is used instead.
        • contentGenre: specifies the RAF.setContentGenre() parameter. If not provided, the video ContentNode Categories or tags field is used instead.
        • contentLength: specifies the RAF.setContentLength() parameter. If not provided, the video ContentNode Length field is used instead. It's set to a value of 999999 in Live videos.
      • adConstraints: specifies RAF.setAdConstraints() parameters.
      • event: [read-only] allows access to all the playback and ads related events.
  • Added support for the seek action in the bcPlayer playback function.
  • Added the following Utils functions:
    • isFunction: verifies if a variable is a Function.
    • toDouble: converts a string value to a Double value.
    • setAddFields: adds new fields / updates existing fields values in the specified Node.
    • addURLParams: adds the specified key-value params into the URL provided. It does not check if params already exist in the URL.
  • The Utils validate function is now able to verify other property types in the type map property (if not string, number, boolean, array, node or aa).

Deprecated

  • Removed bcPlayer setSources function. Alternatively the loadCustom function should be used to load custom sources.
  • Removed the startsWith and endsWith Utils functions as these are already available as native functions.

Version 0.0.1

27 Oct 2023