StreamsPlaybackEncodingBitmovin Dashboard

## What is Third Party Licensing?

The Third Party Licensing feature allows you to internally take control of Allowing or Denying the use of your Player Key. Normally Bitmovin Players will validate a License call against a given License Key by comparing the requesting Domain (web), App Package (Android), Bundle ID (iOS), or Channel ID (Roku) against what you have Allow-Listed inside your Bitmovin Dashboard.

However, with Third Party Licensing we pass that control back to you. This may be useful scenarios such as:

  • Allowing Partners to embed your content on their site or app

  • Real time control and logging of your Player Licensing requests

## Compatibility

Third Party Licensing is applied to a specific License Key which can be used by our Web, Android, iOS, and Roku Players.

## How does it work?

The Third Party Licensing workflow consists of the player first making the license request to our Licensing platform. Then the Bitmovin Licensing Platform passes that license request to the HTTPS endpoint that you specify in the [Bitmovin Dashboard](🔗) for your License. Your endpoint POST method call which contains a pre-defined JSON payload structure shown in the next section and then Accept or Deny the request based on the HTTP response we get from the POST method.

### Data passed to your License Server

The licensing HTTPS POST call will contain the following JSON Payload. There are 3 standard fields - `domain`, `key`, and `version` included in all requests, along with an optional `customData` field.

  • `domain` - String containing the origin Domain, Package Name, Bundle Identifier, or Channel ID

  • `key` - String containing the License Key. This may be useful if you use the same endpoint for multiple Keys enabled with 3rd Party Licensing

  • `version` - String containing the Player version.

  • `customData` - _Optional_ JSON Object containing key/value pairs which can contain arbitrary data. This data is set by calling the PlayerApi.setAuthentication method. _Note:_ This field only applies to our HTML5-based Web Player.

Your licensing endpoint's Allow/Deny logic can you use any combination of the above data fields to determine whether or not to Allow licensing request. For example, if you want to enable Partner content by simply checking the domain you could just validate against the domain field.

For our HTML5 Player, we also allow you can enable more complex checks by requiring some arbitrary data(like a `thirdPartyKey` for example) to be passed in the `customData` field.


### Endpoint responses
Your licensing server needs to respond with either a `2xx` code, `4xx` code, or `5xx` code as described below You can also return arbitrary `customData` in the response as well that will be passed to the client.
  • HTTP code `2xx` -> Allow License
  • HTTP code `4xx` -> Deny License
  • HTTP code `5xx` -> Allow/Deny based on configuration in your Bitmovin Dashboard
  • Timeout -> Response Timeout and Default Action based on configuration in your Bitmovin Dashboard.
Response codes `2xx` will explicitly Allow while response codes `4xx` will explicitly Deny. You can also set the default behavior for Internal Server Error codes `5xx` as well as the default behavior if no response is given within your configured timeout.
Third Party Licensing is controlled at the Player Key level, so once enabled, ALL requests for a given key will be routed to the endpoint that you provided. If you are using 3rd Party Licensing to enable Partners to use your player/content, It is good practice to create secondary Player licenses to be used along with this licensing strategy to isolate Partner licensing from your own Production Player licensing.
## Example Third Party License Server Implementation
This tutorial will be based on the supplemental sample content hosted in our Github repos here - <https://github.com/bitmovin/licensing-demo>
### Creating The Server
You can host your Licensing endpoint however you want - For example, a Java Servlet, AWS API Gateway + Lambda, NodeJS server, etc… For this example we will setup a simple Java Servlet that will look for an arbitrary key called `thirdPartyKey` to passed as a key/value in the `customData` field. The servlet will return a `200` if a valid `thirdPartyKey` is provided and will return a `400` code if not. In case of an Exception being raised the servlet will return a `500` code. In this example our Servlet will also return a `customData` JSON payload via Key/Value pairs.

Now all you need to is to do is host this Java Servlet.
_**Note:**_ It's important to consider your average and peak player usage when hosting your Third Party Licensing endpoint and plan your capacity/redundancy/availability of your hosting accordingly. It is also important to consider how you want Bitmovin's License platform to handle both timeouts and server errors (`5xx` responses) from your endpoint - This is configurable and shown in the next section.
### Enabling Third Party Licensing in the Bitmovin Dashboard
Let's head over to the [Bitmovin Dashboard](🔗) to configure our Player License for Third Party Licensing. Once logged into your Dashboard, Select PLAYER > Licenses from the left-hand menu and Select the License you want to enable.
  1. In the Third Party Licensing modal, enter your hosted License API endpoint into the Server Url input.
  2. Set your response timeout in milliseconds - Maximum of 2000 milliseconds
  3. Set your Default (Allow or Deny) for Error Action (`5xx` server response)
  4. Set your Default (Allow or Deny) for Timeout.

  1. Lastly, click the Enable Button.
Your License is now enabled for Third Party Licensing and ALL licensing requests for the given Key will be routed through this flow.
### Player Configuration
To round-off our above example, let’s configure a Bitmovin Web Player example that will set the example `thirdPartyKey` field that our sample Servlet expects.