Qualified User Limiter (QUL)

The Flowplayer Native QUL plugin (qul) adds a viewer token and a device ID to the URL of HLS streams. The streaming server uses them to decide whether the viewer is allowed to watch. If the server rejects the request, the plugin stops playback and shows the error message returned by the server.

Features

  • Adds the token and device ID to the path of HLS (.m3u8) source URLs.
  • Generates a device ID automatically if you do not configure one.
  • Shows the error message returned by the server when access is denied, and emits an event you can handle yourself.
  • Checks access periodically on platforms where a denied stream would otherwise not raise an error, such as iOS.
  • Reloads the stream with a new token when the token is changed with setOpts().

Prerequisites

  • An HLS stream served by a QUL-enabled streaming backend.
  • A valid QUL token for the viewer.

Installation

Load the plugin next to the core player and the HLS plugin:

<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/hls.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/qul.min.js"></script>

Player and plugins exist in different release versions. Please see the release channel documentation.

Configuration

Configure the plugin with the top-level configuration option qul:

    • property
    • description
    • qul.token string
    • The viewer token. Required, without a token the source URL is not changed.
    • qul.device_id string
    • Optional device ID. If not set, the player generates a device ID. qul.dId is accepted as an alias.
    • qul.interval number
    • Interval in milliseconds for the periodic access check (see access checks). Default and maximum: 20000.

Example

flowplayer("#player_container", {
  src: "https://streams.example.com/path/playlist.m3u8",
  qul: {
    token: "<viewer token>"
  }
})

The plugin inserts the token and device ID into the path in front of the manifest file name. With the configuration above, the player requests:

https://streams.example.com/path/<viewer token>/dId:<device id>/playlist.m3u8

Changing the token

To replace the token during playback, pass a new token with setOpts(). The player reloads the stream with the new token:

player.setOpts({ qul: { token: "<new viewer token>" } })

Access checks

On platforms without Media Source Extensions, such as iOS Safari, and when the HLS plugin is configured to use native HLS playback, a stream that is denied during playback does not raise an error. On these platforms the plugin checks the master manifest periodically, by default every 20 seconds.

Error handling

If the server rejects a request, the plugin pauses playback and shows an error message in the player. The message is taken from the server response.

The plugin also emits the flowplayer.qul.events.QUL_ERROR event on the player. The event detail contains the error code and the server response resp. To show your own error UI instead of the built-in error message, call preventDefault() on the event:

player.on(flowplayer.qul.events.QUL_ERROR, function (e) {
  e.preventDefault()
  console.log("QUL error", e.detail.code, e.detail.resp)
  // show your own error message
})
Results