diff --git a/sidebarsTheoplayer.ts b/sidebarsTheoplayer.ts index 42fc94a2b8f5..a98cace66ba6 100644 --- a/sidebarsTheoplayer.ts +++ b/sidebarsTheoplayer.ts @@ -289,6 +289,20 @@ const sidebars: SidebarsConfig = { }, items: [{ type: 'autogenerated', dirName: 'connectors/roku/adobe-edge' }], }, + { + type: 'category', + label: 'Mux', + description: 'Integrate with Mux analytics.', + customProps: { + icon: 'mux', + }, + link: { + type: 'generated-index', + title: 'Mux Connector for Roku', + slug: 'connectors/roku/mux', + }, + items: [{ type: 'autogenerated', dirName: 'connectors/roku/mux' }], + }, ], }), 'api-reference/roku', diff --git a/theoplayer/connectors/roku/adobe-edge/01-getting-started-aep-connector.mdx b/theoplayer/connectors/roku/adobe-edge/01-getting-started-aep-connector.mdx index 0a7d0ef7a87a..113b1b366aa6 100644 --- a/theoplayer/connectors/roku/adobe-edge/01-getting-started-aep-connector.mdx +++ b/theoplayer/connectors/roku/adobe-edge/01-getting-started-aep-connector.mdx @@ -16,10 +16,10 @@ In order to set up the Adobe Edge Connector in your Roku application, you'll nee ## Integration -1. First you must download the THEO Adobe Edge Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOAEPConnector` and providing the URI for the THEOAEPConnector.pkg: +1. First you must download the THEO Adobe Edge Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOAEPConnector` and providing the URI for the THEOAEPConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 9.2.0: ```xml - + ``` 2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field. diff --git a/theoplayer/connectors/roku/comscore/01-getting-started-comscore-connector.mdx b/theoplayer/connectors/roku/comscore/01-getting-started-comscore-connector.mdx index 52418c158c4a..2a627bc96ca2 100644 --- a/theoplayer/connectors/roku/comscore/01-getting-started-comscore-connector.mdx +++ b/theoplayer/connectors/roku/comscore/01-getting-started-comscore-connector.mdx @@ -16,10 +16,10 @@ In order to set up the Comscore Connector in your Roku application, you'll need ## Integration -1. First you must download the THEO Comscore Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOComscoreConnector` and providing the URI for the THEOComscoreConnector.pkg: +1. First you must download the THEO Comscore Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOComscoreConnector` and providing the URI for the THEOComscoreConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0: ```xml - + ``` 2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field. diff --git a/theoplayer/connectors/roku/conviva/01-getting-started-conviva-connector.mdx b/theoplayer/connectors/roku/conviva/01-getting-started-conviva-connector.mdx index e432b602218b..56c427c8b5f3 100644 --- a/theoplayer/connectors/roku/conviva/01-getting-started-conviva-connector.mdx +++ b/theoplayer/connectors/roku/conviva/01-getting-started-conviva-connector.mdx @@ -17,10 +17,10 @@ In order to set up the Conviva Connector in your Roku application, you'll need t ## Integration -1. First you must download the THEO Conviva Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOConvivaConnector` and providing the URI for the THEOConvivaConnector.pkg: +1. First you must download the THEO Conviva Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOConvivaConnector` and providing the URI for the THEOConvivaConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0: ```xml - + ``` 2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field. diff --git a/theoplayer/connectors/roku/mux/01-getting-started-mux-connector.mdx b/theoplayer/connectors/roku/mux/01-getting-started-mux-connector.mdx new file mode 100644 index 000000000000..135e7e770af1 --- /dev/null +++ b/theoplayer/connectors/roku/mux/01-getting-started-mux-connector.mdx @@ -0,0 +1,104 @@ +--- +sidebar_label: Getting started +sidebar_custom_props: { icon: '🚀' } +--- + +# Getting started with the Mux Connector for the Roku SDK + +Here's how to get started integrating the Mux Connector with the THEOplayer Roku SDK. + +## Prerequisites + +In order to set up the Mux Connector in your Roku application, you'll need the following: + +- Your Mux environment key +- An app with the THEOPlayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/). + +## Integration + +1. First you must download the THEO Mux Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOMuxConnector` and providing the URI for the THEOMuxConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 10.8.0: + +```xml + +``` + +2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field. + +```brightscript +sub Init() + THEOMuxNode = m.top.findNode("THEOMuxConnector") + THEOMuxNode.observeField("loadStatus", "onLibraryLoadStatusChanged") +end sub + +sub onLibraryLoadStatusChanged(event as object) + THEOMuxNode = event.getROSGNode() + + if THEOMuxNode = invalid + return + end if + + if THEOMuxNode.loadStatus = "ready" + ' Success + else if THEOMuxNode.loadStatus = "failed" + ? "Failed to load component library, please check URL. "; THEOMuxNode.uri + end if +end sub +``` + +3. Add the THEOMuxConnector component to the SceneGraph file where your THEOPlayer is defined. + +```xml + + +``` + +4. Then in the Brightscript file, configure the connector by calling the configure method, passing the player instance and your Mux configuration. + +```brightscript +m.player = m.top.findNode("THEOPlayer") +m.muxConnector = m.top.findNode("THEOMuxConnector") +muxConfig = { + env_key: "", +} +m.muxConnector.callFunc("configure", m.player, muxConfig) +``` + +5. Next, when you start playing the asset, call the `startSession` method and pass it the metadata for the asset you're playing: + +```brightscript +m.player.source = sourceDescription + +muxContentMetadata = { + video_id: "", + video_title: "" +} + +m.muxConnector.callFunc("startSession", muxContentMetadata) +``` + +There are more properties available to add to the metadata, but `video_id` and `video_title` are required. See [Mux's schema for streaming metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata) for more properties that are available for Mux. + +6. If you are using the THEOplayer in a size other than fullscreen, before you start the session, you can set the presentation mode to reflect the different size. This is also referred to as the playback mode. + +```brightscript +m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE) +m.muxConnector.callFunc("startSession", muxContentMetadata) +``` + +The `setPresentation` method can also be called mid-session if the presentation mode changes during a session. The available presentation modes are `FULLSCREEN`, `INLINE`, `MINI`, and `PIP`. + +7. If you desire to monitor for CDN changes, you can optionally add a configuration for that to start monitoring. + `m.muxConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })` + +8. When the video has stopped playing because it ended or the user exited, end the Mux session. + `m.muxConnector.callFunc("endSession")` + +9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the player: + +```brightscript +m.muxConnector.callFunc("destroy") +m.muxConnector = invalid + +m.player.callFunc("destroy") +m.player = invalid +``` diff --git a/theoplayer/connectors/roku/mux/02-API-reference.mdx b/theoplayer/connectors/roku/mux/02-API-reference.mdx new file mode 100644 index 000000000000..2e5b7535aad9 --- /dev/null +++ b/theoplayer/connectors/roku/mux/02-API-reference.mdx @@ -0,0 +1,87 @@ +--- +sidebar_label: API reference +sidebar_custom_props: { icon: '*️⃣' } +--- + +# Mux Connector API + +The attributes, methods and events for the THEOMuxConnector. + +## Attributes + +| Name | Type | Default | Access Permission | Description | +| ------------------ | ---------------- | ---------------------- | ----------------- | ---------------------------------------------- | +| id | string | | read,write | The id of the node. | +| CONTENT_TYPES | AssociativeArray | Mux Content Types | read | Constant with the Mux content types enums. | +| PRESENTATION_MODES | AssociativeArray | Mux Presentation Modes | read | Constant with the Mux presentation mode enums. | + +## Methods + +| Method | Params | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| configure | player: THEOplayer, configuration: THEOMuxConfiguration, metadata: (optional) AssociativeArray | Add a player to monitor, configure the Mux SDK, and also pass in optional metadata for your content. | +| destroy | none | Destroy the connector. It also ends the current session, if any. | +| endSession | none | End the current Mux session, but do not destroy the connector. | +| monitorCdnChanges | mappings: CDNMonitoringConfig, defaultCdn: string (optional) | Updates the CDN monitoring settings. If passed a CDN monitoring config (see below), it will begin monitoring the downloaded segments for changes in CDN. This will update the defaultReportingResource for the current session if a CDN change is detected If passed invalid as the first parameter, it will stop the monitoring and use any string passed as the second param as the defaultReportingResource. | +| notifyError | code: integer, message: string, context: string (optional), severity: string (optional), isBusinessException: boolean (optional) | Report an error to Mux. Note that most errors should be automatically reported. Severity defaults to "fatal". | +| setPresentation | presentationMode: MuxPresentationModes, data: (optional) AssociativeArray | Change the reported presentation mode (also called playback mode) for the player. Can also take optional arbitrary data about the mode. | +| startSession | mediaType: string, metadata: (optional) THEOMuxReadableMetadata or THEOMuxTagMetadata | Starts a Mux streaming session with the specified media type, and optionally applies the content metadata. See below for the schema of content. If not passing content metadata, you will need to add it separately with the `update` method before calling `startSession` | + +### Mux Config + +The configuration the Mux connector is the THEOMuxConfiguration interface. All properties except for `env_key` are optional. + +```brightscript +configuration = { + env_key: "", + viewer_user_id: "", + mux_base_url: "" +} +``` + +In order to get debug output from Mux in your console, you need to add the settings to your application's manifest file. + +``` +mux_debug_events=partial +mux_debug_beacons=partial +``` + +The accepted values for the debug properties are `full`, `partial`, and `none`, defaulting to `none`. + +### CDN Monitoring Config + +The configuration for CDN monitoring should be an AssociativeArray with keys that are the name of the CDN and values that are arrays of strings to search for in segment URLs. + +```brightscript +cdnMappings = { + akamai: ["akamaized.net"], + theo: ["dev.theoads.live", "cdn.theoplayer.com"] + level3: ["llnw.com"] +} +``` + +Passing a config as the only param will start CDN change monitoring with the provided configuration, or update the config if it is already started. +`m.theoMuxConnector.callFunc("monitorCDNChanges", cdnMappings)` +However, if you want to stop CDN change monitoring, pass `invalid` as the first parameter, and the string you want to use for the defaultReportingResource as the second parameter. +`m.theoMuxConnector.callFunc("monitorCDNChanges", invalid, "theo")` + +### Content Metadata + +Content metadata should be an AssociativeArray following [Mux's schema for streaming tags](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata). All properties on it are optional, except for `video_id` and `video_title`. + +For content type metadata values, there is an enum property on the THEOMuxConnector named `CONTENT_TYPES`. Its values are SHORT, MOVIE, CLIP, EPISODE, TRAILER, and EVENT. For example: `metadata.video_content_type = m.muxConnector.CONTENT_TYPES.MOVIE`. + +### Presentation Modes + +The THEOMuxConnector supports reporting changes in the presentation mode (also called presentation mode) your application uses the player in, such as fullscreen or inline. The `PRESENTATION_MODES` enum property on the THEOMuxConnector holds the possible values (FULLSCREEN, INLINE, MINI, and PIP). For example, if your application changes the THEO player so it is in a list row component, you could call: + +```brightscript +m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE) +``` + +There is also an optional `data` parameter for that method that can be an arbitrary associative array, as long as it can be converted to JSON. + +```brightscript +presentationModeData = { reason: "Viewed Asset", timestamp: 1767735434 } +m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.FULLSCREEN, presentationModeData) +```