Device Playback Capabilities

ℹ️

Understanding each viewer's device capabilities is crucial for optimizing content delivery and ensuring a seamless playback experience. This section provides information on how to gain insights into your audience's playback capabilities through the Fastevo Media Protection Platform (Fastevo MP2).

Overview

The Device Playback Capabilities endpoints allow you to:

Retrieve statistics on the playback capabilities of all viewers over the past 30 days.
Determine a specific viewer's playback capability, helping you decide the best protection level to serve them.
Retrieve a list of devices that viewers have used to attempt to play your protected media content.

By utilizing these endpoints, you can gain insights into:

Audience Capability: Understand the overall ability of your viewers to handle different protection levels.
Viewer's Device Usage: Identify all devices used by viewers.
Playback Success Rates: Determine if devices can successfully play content at different protection levels.
Optimizing Content Delivery: Make informed decisions about which protection level to serve to viewers based on their device capabilities.

Retrieving Playback Capabilities Statistics

Overview

The Playback Capabilities Statistics endpoint provides aggregated insights into the playback capabilities of your audience over the past 30 days. This enables you to understand the proportion of viewers and devices that can handle different protection levels.

Endpoint

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/stats

Authentication

This endpoint requires authentication. Include your project API key in the Authorization header:

Authorization: Bearer YOUR_PROJECT_API_KEY

Example Request

Retrieve playback capabilities statistics:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/stats
Authorization: Bearer YOUR_PROJECT_API_KEY

Successful Response

A successful response returns a status code of 200 OK and a JSON body containing playback capability percentages.

Response Schema

{
  "percentageOfPeopleCapableOfEnhancedPlaybackInLast30Days": number,
  "percentageOfDevicesCapableOfEnhancedPlaybackInLast30Days": number,
  "percentageOfPeopleCapableOfStandardPlaybackInLast30Days": number,
  "percentageOfDevicesCapableOfStandardPlaybackInLast30Days": number,
  "percentageOfPeopleCapableOfAdaptivePlaybackInLast30Days": number,
  "percentageOfDevicesCapableOfAdaptivePlaybackInLast30Days": number
}

Field Descriptions

percentageOfPeopleCapableOfEnhancedPlaybackInLast30Days: Percentage of viewers who successfully played content at the enhanced protection level in the last 30 days.
percentageOfDevicesCapableOfEnhancedPlaybackInLast30Days: Percentage of devices that successfully played content at the enhanced protection level in the last 30 days.
percentageOfPeopleCapableOfStandardPlaybackInLast30Days: Percentage of viewers who successfully played content at the standard protection level in the last 30 days.
percentageOfDevicesCapableOfStandardPlaybackInLast30Days: Percentage of devices that successfully played content at the standard protection level in the last 30 days.
percentageOfPeopleCapableOfAdaptivePlaybackInLast30Days: Percentage of viewers capable of adaptive playback (either standard or enhanced) in the last 30 days.
percentageOfDevicesCapableOfAdaptivePlaybackInLast30Days: Percentage of devices capable of adaptive playback (either standard or enhanced) in the last 30 days.

Example Response

{
  "percentageOfPeopleCapableOfEnhancedPlaybackInLast30Days": 75,
  "percentageOfDevicesCapableOfEnhancedPlaybackInLast30Days": 68,
  "percentageOfPeopleCapableOfStandardPlaybackInLast30Days": 95,
  "percentageOfDevicesCapableOfStandardPlaybackInLast30Days": 90,
  "percentageOfPeopleCapableOfAdaptivePlaybackInLast30Days": 98,
  "percentageOfDevicesCapableOfAdaptivePlaybackInLast30Days": 95
}

Understanding the Data

Enhanced Playback: Higher protection level but may not be supported on all devices.
Standard Playback: Lower protection level with broader device compatibility.
Adaptive Playback: Combines both enhanced and standard levels to maximize compatibility.

Use these statistics to:

Optimize Content Delivery: Decide whether to use enhanced protection based on audience capability.
Identify Trends: Monitor changes over time to adapt your content strategy.
Improve User Experience: Ensure the majority of your audience can access your content without issues.

Retrieving a Specific Viewer's Playback Capabilities

Overview

This endpoint allows you to determine whether a specific viewer is capable of playing back content at different protection levels based on their devices' playback history in the last 30 days.

Endpoint

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/viewer/:viewerIdentifier

Replace :viewerIdentifier with the viewer's unique identifier.

Authentication

This endpoint requires authentication. Include your project API key in the Authorization header:

Authorization: Bearer YOUR_PROJECT_API_KEY

Example Request

Retrieve playback capabilities for a specific viewer:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/viewer/viewer123
Authorization: Bearer YOUR_PROJECT_API_KEY

Successful Response

A successful response returns a status code of 200 OK and a JSON body indicating the viewer's capability for each protection level.

Response Schema

{
  "isCapableOfStandardPlaybackInLast30Days": boolean | null,
  "isCapableOfEnhancedPlaybackInLast30Days": boolean | null,
  "isCapableOfAdaptivePlaybackInLast30Days": boolean | null
}

Field Descriptions

isCapableOfStandardPlaybackInLast30Days:
- true: The viewer can play content at the standard protection level.
- false: The viewer cannot play content at the standard protection level.
- null: No recent data available for this viewer.
isCapableOfEnhancedPlaybackInLast30Days:
- true: The viewer can play content at the enhanced protection level.
- false: The viewer cannot play content at the enhanced protection level.
- null: No recent data available for this viewer.
isCapableOfAdaptivePlaybackInLast30Days:
- true: The viewer can play content at either protection level.
- false: The viewer cannot play content at either protection level.
- null: No recent data available for this viewer.

Example Response

{
  "isCapableOfStandardPlaybackInLast30Days": true,
  "isCapableOfEnhancedPlaybackInLast30Days": false,
  "isCapableOfAdaptivePlaybackInLast30Days": true
}

Understanding the Data

Use this information to tailor the protection level of content served to a specific viewer.
If isCapableOfEnhancedPlaybackInLast30Days is true, you can confidently serve content at the enhanced protection level.
If false, consider serving content at the standard protection level to ensure compatibility.
A null value indicates that the viewer hasn't attempted playback in the last 30 days or there's no data available.

Retrieving Device Playback Capabilities List

Endpoint

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities

Authentication

Include your project API key in the Authorization header:

Authorization: Bearer YOUR_PROJECT_API_KEY

Query Parameters

page (optional): The page number for pagination (default is 1).
limit (optional): The number of records per page (default is 10).
filter (optional): Filter playback capabilities by viewerIdentifier to focus on a specific viewer.
orderBy (optional): The field to order the results by. Possible values are:
- _id, lastSeen, clientType, viewerIdentifier, operatingSystemName, operatingSystemVersion, deviceVendor, deviceModel, deviceType, browserName, browserVersion, isInPrivateMode, didLastStandardPlaybackSucceed, lastStandardPlayback, didLastEnhancedPlaybackSucceed, lastEnhancedPlayback, firstSeen.
order (optional): The sorting order, either asc or desc (default is desc).

Example Request

Retrieve devices used by a specific viewer:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities?filter=viewer123
Authorization: Bearer YOUR_PROJECT_API_KEY

Successful Response

A successful response returns a status code of 200 OK and a JSON body containing pagination information and an array of device playback capabilities data.

Response Schema

{
  "currentPage": number,
  "totalPages": number,
  "totalRecords": number,
  "data": [
    {
      "viewerIdentifier": "string",
      "clientType": "string",
      "operatingSystemName": "string",
      "operatingSystemVersion": "string",
      "deviceVendor": "string",
      "deviceModel": "string",
      "deviceType": "string",
      "browserName": "string",
      "browserVersion": "string",
      "lastSeen": "string (ISO 8601 datetime)",
      "isInPrivateMode": boolean,
      "firstSeen": "string (ISO 8601 datetime)",
      "didLastStandardPlaybackSucceed": boolean,
      "lastStandardPlayback": "string (ISO 8601 datetime)",
      "didLastEnhancedPlaybackSucceed": boolean,
      "lastEnhancedPlayback": "string (ISO 8601 datetime)"
    }
    // ... more records
  ]
}

Field Descriptions

currentPage: The current page number in the pagination.
totalPages: The total number of pages available.
totalRecords: The total number of records across all pages.
data: An array of device playback capability records.

Each record in data includes:

viewerIdentifier: The unique identifier for the viewer.
clientType: The type of client used (e.g., "webBrowser", "mobileApp").
operatingSystemName: The name of the operating system (e.g., "Windows", "macOS", "Android").
operatingSystemVersion: The version of the operating system.
deviceVendor: The vendor of the device (e.g., "Apple", "Samsung").
deviceModel: The model of the device (e.g., "iPhone X", "Galaxy S10").
deviceType: The type of device (e.g., "smartphone", "tablet", "desktop").
browserName: The name of the browser used (e.g., "Chrome", "Safari").
browserVersion: The version of the browser.
lastSeen: ISO 8601 datetime string representing when the device was last seen.
isInPrivateMode: Boolean indicating if the device was in private/incognito mode during the last playback attempt.
firstSeen: ISO 8601 datetime string representing when the device was first seen.
didLastStandardPlaybackSucceed: Boolean indicating if the last standard protection level playback attempt was successful.
lastStandardPlayback: ISO 8601 datetime of the last standard protection level playback attempt.
didLastEnhancedPlaybackSucceed: Boolean indicating if the last enhanced protection level playback attempt was successful.
lastEnhancedPlayback: ISO 8601 datetime of the last enhanced protection level playback attempt.

Example Response

{
  "currentPage": 1,
  "totalPages": 1,
  "totalRecords": 2,
  "data": [
    {
      "viewerIdentifier": "viewer123",
      "clientType": "webBrowser",
      "operatingSystemName": "Windows",
      "operatingSystemVersion": "10",
      "deviceVendor": "Dell",
      "deviceModel": "XPS 13",
      "deviceType": "desktop",
      "browserName": "Chrome",
      "browserVersion": "93.0.4577.82",
      "lastSeen": "2023-10-01T14:23:55Z",
      "isInPrivateMode": false,
      "firstSeen": "2023-09-15T10:08:12Z",
      "didLastStandardPlaybackSucceed": true,
      "lastStandardPlayback": "2023-10-01T14:23:55Z",
      "didLastEnhancedPlaybackSucceed": false,
      "lastEnhancedPlayback": "2023-09-30T08:45:00Z"
    },
    {
      "viewerIdentifier": "viewer456",
      "clientType": "mobileApp",
      "operatingSystemName": "iOS",
      "operatingSystemVersion": "14.7",
      "deviceVendor": "Apple",
      "deviceModel": "iPhone 12",
      "deviceType": "smartphone",
      "browserName": "",
      "browserVersion": "",
      "lastSeen": "2023-10-02T09:15:30Z",
      "isInPrivateMode": false,
      "firstSeen": "2023-09-20T17:05:45Z",
      "didLastStandardPlaybackSucceed": true,
      "lastStandardPlayback": "2023-10-02T09:15:30Z",
      "didLastEnhancedPlaybackSucceed": true,
      "lastEnhancedPlayback": "2023-10-01T13:00:00Z"
    }
  ]
}

Understanding the Data

For each device:

Playback Success Indicators:
- didLastStandardPlaybackSucceed: Indicates whether the last attempt to play content at the standard protection level was successful.
- didLastEnhancedPlaybackSucceed: Indicates whether the last attempt to play content at the enhanced protection level was successful.
Playback Timestamps:
- lastStandardPlayback: When the last standard playback attempt occurred.
- lastEnhancedPlayback: When the last enhanced playback attempt occurred.
Use this information to determine whether devices can handle content at different protection levels and to troubleshoot issues.

Pagination and Sorting

If there are multiple devices or a large dataset, you can paginate through the results using the page and limit query parameters.

Example: To retrieve the second page of results with 5 records per page:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities?page=2&limit=5
Authorization: Bearer YOUR_PROJECT_API_KEY

You can also sort the results using orderBy and order:

Example: To sort the results by lastSeen in ascending order:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities?orderBy=lastSeen&order=asc
Authorization: Bearer YOUR_PROJECT_API_KEY

Example Usage

Scenario: Monitoring Playback Capabilities Statistics

Objective: Determine the overall capability of your audience to handle enhanced protection level content.

Request:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/stats
Authorization: Bearer YOUR_PROJECT_API_KEY

Response:

Status Code: 200 OK
Body: (As shown in the Successful Response)

Action: If the percentageOfPeopleCapableOfEnhancedPlaybackInLast30Days is high, you might choose to default to enhanced protection. If it's low, consider using adaptive strategies.

Scenario: Tailoring Content for a Specific Viewer

Objective: Decide which protection level to use when serving content to "viewer123".

Request:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities/viewer/viewer123
Authorization: Bearer YOUR_PROJECT_API_KEY

Response:

Status Code: 200 OK
Body: (As shown in the Successful Response)

Action: Since isCapableOfEnhancedPlaybackInLast30Days is false and isCapableOfStandardPlaybackInLast30Days is true, serve content at the standard protection level to ensure compatibility.

Scenario: Investigating Device Playback Issues

Objective: Identify devices that are failing to play content at the enhanced protection level.

Request:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/playbackCapabilities?orderBy=lastEnhancedPlayback&order=desc
Authorization: Bearer YOUR_PROJECT_API_KEY

Response:

Status Code: 200 OK
Body: (As shown in the Successful Response)

Action: Analyze devices where didLastEnhancedPlaybackSucceed is false to identify common factors causing playback issues.

Notes

Filtering by Viewer Identifier: Use the filter query parameter in the device list endpoint to focus on a specific viewer's devices.
Up-to-date Information: The playback capabilities are updated based on actual playback sessions and reports from the player's client-side code. Ensure that your player correctly reports playback successes and failures.
Time Zones: All datetime fields are in ISO 8601 format and are in the UTC time zone.
Privacy Considerations: Handle viewer identifiers and any PII (Personally Identifiable Information) according to your privacy policies and applicable laws.

Common Use Cases

Optimizing Content Delivery Globally: Use the statistics endpoint to assess overall audience capability and adjust your default protection level accordingly.
Adaptive Streaming Strategies: Implement logic in your application to choose the best protection level for each viewer based on their capabilities.
Troubleshooting Playback Issues: If multiple viewers report issues, analyze the device list to identify patterns or common factors.
Marketing and Support: Use insights into device usage to inform marketing strategies or provide better customer support.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request:

200 OK: The request was successful.
400 Bad Request: The request was invalid or cannot be served. Check the request parameters.
401 Unauthorized: Authentication failed or user does not have permissions for the desired action.
500 Internal Server Error: An error occurred on the server.

Apple FairPlay Rules