MP2 (Media Protection Platform)
Advanced
Player configurations

Customizing the Fastevo MP2 Player Theme

Overview

Fastevo MP2 Player provides a flexible way to customize the player's theme. This includes options to display posters and thumbnails, change player and badge colors, set the position and theme of the badge, and configure advertisements using VAST (Video Ad Serving Template). Additionally, you can configure a customizable “big play button” (including custom play and pause button images). This document outlines how to use these options and endpoints to customize the player's theme.

Creating or Updating (Upserting) a Player Configuration

To create or update (upsert) a player configuration, make a PUT request to the following endpoint:

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}
  • The {name} in the URL is the identifier for the player configuration. This is the name you will use to refer to this configuration in future requests.
  • If the configuration does not exist, a new one is created (HTTP status 201).
  • If the configuration already exists, it is updated (HTTP status 200), and the response will include: 
    {
  "success": true
}

Request Body

The request body should be a JSON object with the following properties:

  • displayControls: A boolean indicating whether to display the player controls in videos and audios.
  • displayPoster: A boolean indicating whether to display the poster in the videos.
  • displayThumbnailsInSeekbar: A boolean indicating whether to display thumbnails in the seekbar.
  • playerThemeName: A string specifying the name of the player theme. Currently, only "default" is available. This field is reserved for future use.
  • playerColorsConfiguration: An object specifying the player's color configuration. It has the following properties:
    • base: A string specifying the base color in hex format (e.g., #000000).
    • buffered: A string specifying the buffered color in hex format (e.g., #000000).
    • played: A string specifying the played color in hex format (e.g., #000000).
  • badgePosition: A string specifying the position of the badge. Valid values are "topRight", "topLeft", "bottomRight", "bottomLeft", and "hidden".
  • badgeThemeName: A string specifying the name of the badge theme. Currently, only "default" is available. This field is reserved for future use.
  • badgeColorsConfiguration: An object specifying the badge's color configuration. It has the following property:
    • accent: A string specifying the accent color in hex format (e.g., #000000).
  • adsConfiguration: An object specifying the advertisement configuration. It has the following properties:
    • enableAds: A boolean indicating whether ads are enabled.
    • adTagUrl: A string specifying the ad tag URL.
  • bigPlayButtonConfiguration: An object specifying custom options for the big play button and includes:
    • isEnabled: A boolean indicating whether to enable the big play button.
    • scale: A number indicating the scale of the big play button.
  • seekOnTaps: A boolean indicating whether double taps should seek the video by 10 seconds (left for previous 10 seconds, right for next 10 seconds).
  • enableMobileLayout: A boolean indicating whether the mobile-friendly layout is activated, allowing the interface to adjust for an optimized viewing experience on mobile devices.
  • enableNonSecureNativeFullScreen: A boolean that enables the native full screen mode on certain scenarios.
    ⚠️

    Not recommended: This reduces security and should be used with caution.
    Important: For playbacks using an enhanced protection level, this option is forcibly disabled, even if you enable it explicitly or via a SIEM rule. This prevents fraudulent exploitation.

  • enableNonSecureAirplayCasting: A boolean that enables AirPlay casting between Apple devices.
    ⚠️

    Not recommended: This reduces security and should be used with caution.
    Important: For playbacks using an enhanced protection level, this option is also forcibly disabled, even if you enable it explicitly or via a SIEM rule.

Example Request Body

{
  "displayControls": true,
  "displayPoster": true,
  "displayThumbnailsInSeekbar": true,
  "playerThemeName": "default",
  "playerColorsConfiguration": {
    "base": "#FFFFFF",
    "buffered": "#CCCCCC",
    "played": "#FF0000"
  },
  "badgePosition": "topRight",
  "badgeThemeName": "default",
  "badgeColorsConfiguration": {
    "accent": "#00FF00"
  },
  "adsConfiguration": {
    "enableAds": true,
    "adTagUrl": "https://example.com/vast.xml"
  },
  "bigPlayButtonConfiguration": {
    "isEnabled": true,
    "scale": 1.2
  },
  "seekOnTaps": true,
  "enableMobileLayout": true,
  "enableNonSecureNativeFullScreen": false,
  "enableNonSecureAirplayCasting": false
}

In this example:

  • Ads are enabled, using a VAST ad tag URL to fetch and display advertisements.
  • The big play button is enabled and scaled to 1.2×.
  • The player is configured so that double-tapping the left or right side of the screen seeks +/-10 seconds.
  • Both enableNonSecureNativeFullScreen and enableNonSecureAirplayCasting are set to false. Enabling them can reduce security and must be done with caution. Furthermore, if the playback session has an enhanced protection level, these options are forcibly disabled.

Managing Custom Buttons

Fastevo MP2 Player allows you to upload and manage custom play/pause button images that appear when the big play button is displayed. The custom images must be in SVG format. These images can be set or removed independently of the main player configuration.

When uploaded, these buttons are stored and served via signed URLs that are valid for 24 hours.

Endpoints for Custom Buttons

Set/Update Custom Play Button

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}/customPlayButton
  • Expects multipart/form-data with a single SVG file to be used as the custom play button.
  • Replaces the existing custom play button image if set.
  • If the file is not an SVG, an error will be returned.

Set/Update Custom Pause Button

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}/customPauseButton
  • Expects multipart/form-data with a single SVG file to be used as the custom pause button.
  • Replaces the existing custom pause button image if set.
  • If the file is not an SVG, an error will be returned.

Remove Custom Play Button

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}/customPlayButton
  • Removes any existing custom play button image from the configuration.

Remove Custom Pause Button

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}/customPauseButton
  • Removes any existing custom pause button image from the configuration.

Configuring Advertisements

The adsConfiguration object allows you to integrate advertisements into your player using VAST (Video Ad Serving Template). This enables you to serve ads from any ad server that supports VAST.

adsConfiguration Properties

  • enableAds: Set this to true to enable ads in your player. If set to false or omitted, ads will not be displayed.
  • adTagUrl: Provide the ad tag URL supplied by your ad server or network. This URL should point to a VAST XML file that defines the ads to be displayed.

Notes on Advertisement Integration

  • VAST Support: Only VAST ads are supported at this time. Ensure that your ad server provides a VAST-compliant ad tag.
  • Ad Tag URL: The adTagUrl must be a valid URL returning a proper VAST response. The player will use this URL to fetch ad metadata and content.
  • Ad Playback: The player will handle ad playback according to the VAST specification. This may include pre-roll, mid-roll, or post-roll ads, depending on how your ad tag is configured.
  • Testing Ads: When testing your player configuration, make sure that the ad tag URL is accessible and returns valid VAST content to avoid playback issues.

Listing Player Configurations with Pagination

To retrieve a list of player configurations with pagination, perform a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players

You can include query parameters such as page, limit, orderBy, order, and filter to customize the response.

Query Parameters

  • page (optional): The page number to retrieve.
  • limit (optional): The number of items per page.
  • orderBy (optional): The field to order by. Options are _id (creation date) and name.
  • order (optional): The order direction. Options are asc for ascending and desc for descending.
  • filter (optional): A string to filter the player configurations based on name.

API Response

The API will return a response with a status code of 200 and a JSON body containing the list of player configurations along with pagination details.

Example Response

{
  "currentPage": 1,
  "totalPages": 1,
  "totalRecords": 2,
  "data": [
    {
      "name": "CustomPlayerWithAds",
      "isDefault": false
    },
    {
      "name": "DefaultPlayer",
      "isDefault": true
    }
  ]
}

Explanation of Response Fields

  • currentPage: The current page number.
  • totalPages: The total number of pages available.
  • totalRecords: The total number of player configuration records.
  • data: An array of player configuration objects, each containing:
    • name: The name of the player configuration.
    • isDefault: A boolean indicating if the configuration is the default one.

Ordering and Filtering

To order the player configurations by their creation date, use the _id field. This represents a similar ordering to createdAt since the _id field is generated based on the creation time.

Use the filter query parameter to filter the player configurations based on the name.

Retrieving a Player Configuration

To retrieve a player configuration, make a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}

The {name} in the URL is the identifier for the player configuration. The response will be a JSON object with the same properties as when creating or updating a player configuration, plus any existing custom play/pause button URLs. These URLs are signed SVG URLs valid for 24 hours if they were previously uploaded.

Example Response

{
  "displayControls": true,
  "displayPoster": true,
  "displayThumbnailsInSeekbar": false,
  "playerThemeName": "default",
  "playerColorsConfiguration": {
    "base": "#FFFFFF",
    "buffered": "#CCCCCC",
    "played": "#FF0000"
  },
  "badgePosition": "topRight",
  "badgeThemeName": "default",
  "badgeColorsConfiguration": {
    "accent": "#00FF00"
  },
  "adsConfiguration": {
    "enableAds": true,
    "adTagUrl": "https://example.com/vast.xml"
  },
  "bigPlayButtonConfiguration": {
    "isEnabled": true,
    "scale": 1.2,
    "customPlayButton": "https://example.com/signed-play-url.svg",
    "customPauseButton": "https://example.com/signed-pause-url.svg"
  },
  "seekOnTaps": true,
  "enableMobileLayout": true,
  "enableNonSecureNativeFullScreen": false,
  "enableNonSecureAirplayCasting": false
}

Retrieving the Default Player Configuration

To retrieve the default player configuration, make a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/default

The response will be a JSON object containing the name of the default player configuration.

Example Response

{
  "name": "DefaultPlayer"
}

Setting a Default Player Configuration

ℹ️

Remember, you can set the player configuration separately for a specific playback session by adding the value playerConfigurations to the playbackToken as described in the Playback Tokens page.

To set a player configuration as the default for a project, make a PUT request to the following endpoint:

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}/default

The {name} in the URL is the identifier for the player configuration you want to set as the default.

Removing the Default Player Configuration

To remove the player configuration as the default for a project, make a DELETE request to the following endpoint:

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/default

After this request, the project will revert to the default settings. This does not delete the player configuration; it simply unsets it as the default.

Deleting a Player Configuration

To delete a player configuration, make a DELETE request to the following endpoint:

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/players/{name}

The {name} in the URL is the identifier for the player configuration you want to delete. If this configuration is the default for the project, it will be unset as default before deletion.

Development modePlayer events