openapi: 3.0.3 info: title: Brightcove Analytics API Reference Access Tokens Player Configurations API description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our API Testing Tools.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com" x-bc-access: public version: 1.0.0 servers: - url: https://analytics.api.brightcove.com variables: {} tags: - name: Player Configurations description: Operations for managing player configurations. paths: /accounts/{{account_id}}/players/{{player_id}}/configuration/{branch}: get: tags: - Player Configurations summary: Get player configuration description: Get a preview or published player configuration operationId: GetPlayerConfiguration security: - BC_OAuth2: - video-cloud/player/read parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/player_id' - $ref: '#/components/parameters/branch' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/Authorization' responses: '200': description: '200' content: application/json: schema: $ref: '#/components/schemas/configuration' '400': description: 'BAD_REQUEST: the syntax of the API call is likely incorrect' '401': description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token' '404': description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested' '429': description: 'RATE_LIMIT_EXCEEDED: Too many requests per second' '500': description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request' deprecated: false x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /accounts/{{account_id}}/players/{{player_id}}/configuration: patch: tags: - Player Configurations summary: Update player configuration description: Update a player configuration operationId: UpdatePlayerConfiguration security: - BC_OAuth2: - video-cloud/player/all parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/player_id' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/Authorization' requestBody: description: Update a player configuration. Please note that all the parameters except for `name` and `description` must be inside a `configuration` object content: application/json: schema: configuration: null $ref: '#/components/schemas/configuration' required: true responses: '200': description: '200' content: application/json: schema: description: '200' type: object properties: account_id: type: string description: The account id created_at: type: string description: The player creation date-time embeds_count: type: integer description: The number of embeds (instances of this player), will always be at least 1 id: type: string description: The player id name: type: string description: The player name description: type: string description: The player description url: type: string description: URL to player branches: type: object description: The branches of the player - contains objects for the preview and master (published) player properties: preview: type: object description: The preview player branch properties: configuration: $ref: '#/components/schemas/configuration' updated_at: type: string description: date-time of last update to preview player template_updated_at: type: string description: date-time of last update to preview player template preview_url: type: string description: URL for the player master: type: object description: The master (published) player branch properties: configuration: $ref: '#/components/schemas/configuration' updated_at: type: string description: date-time of last update to preview player template_updated_at: type: string description: date-time of last update to preview player template preview_url: type: string description: URL for the player '400': description: 'BAD_REQUEST: the syntax of the API call is likely incorrect' '401': description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token' '404': description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested' '429': description: 'RATE_LIMIT_EXCEEDED: Too many requests per second' '500': description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request' deprecated: false x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false components: schemas: configuration: title: Player Configuration type: object description: Configuration for a player properties: ad_config_id: type: string description: A Dynamic Delivery SSAI ad configuration ID. In addition to being set on the player configuration, it can be set at runtime via the adConfigId query string parameter for iframe players or the data-ad-config-id attribute for in-page players. Either of these will override any value in the player configuration. default: undefined ad_failover: type: boolean description: 'Set to true to enable ad failover behavior. This is a multi-part configuration that depends on:
- Both IMA3 and SSAI plugins must be configured on the player.
- An ad_config_id should be available, otherwise SSAI ads are not available.' default: undefined application_id: type: string description: The application ID is used to differentiate multiple uses of a single player in metrics. It is invisible to the user. default: undefined autoadvance: type: integer description: 'Autoadvance setting if using playlists: 0 for no wait; a number for seconds between advance; null to cancel autoadvance' default: not enabled autoplay: oneOf: - type: boolean description: If `autoplay` is set to a Boolean value the browser's native autoplay behavior is used. - type: string description: 'If `autoplay` is set to one of the following three valid string values, the following occurs:
- `play`: The player will manually try to call play.
- `muted`: The player will manually mute the player and call play.
- `any`: The player will first try to call play. If that fails, mute the player and call play.
If any of the above fail, the player will display the "Big Play Button" as if autoplay was set to false.' enum: - play - auto - any description: Indicates player should play video immediately, on platforms that allow this default: false compatibility: type: boolean description: Provides compatibility with the Player 1.x.x API readOnly: true crossorigin: type: boolean description: 'If true, the underlying <video> element will have crossorigin="anonymous". This means that any videos or text tracks pulled into the player must have CORS headers. *This feature should only be used if you know that all your content (video and text tracks) have CORS headers applied to them.*' readOnly: true css: type: object description: Object containing CSS color overrides properties: controlBarColor: type: string description: Background color of control bar default: '{set by player template}' controlColor: type: string description: Color of buttons and text in control bar default: '{set by player template}' progressColor: type: string description: Color of progress bar default: '{set by player template}' debugger: type: boolean description: If true, debugger shows player information in a modal window. See the [Player Information Modal document](https://player.support.brightcove.com/troubleshooting/brightcove-player-information-modal.html) for full information. errors: type: boolean description: Indicates if the error messages plugin should be excluded flash: type: object description: Can be used to provide custom Flash options to **Video.js**. fullscreenControl: type: boolean description: Indicates whether the fullscreen control should be shown in the control bar hls: oneOf: - type: boolean description: If `false`, the player will not include **videojs-contrib-hls** - type: object description: If an object is passed, it will be used as options for **videojs-contrib-hls** properties: captionServices: type: object description: Used to rename 608 captions properties: CC1: type: object description: Properties of the captions to use for CC1 properties: language: type: string description: The language of the captions example: en label: type: string description: Label to used for these captions in the player controls example: English CC2: type: object description: Properties of the captions to use for CC2 properties: language: type: string description: The language of the captions example: en label: type: string description: Label to used for these captions in the player controls example: English parse708captions: type: boolean default: true description: Set to false to hide 708 captions if the encoder is sending both 608 and 708 description: Handling of **videojs-contrib-hls** and renaming of 608 captions default: {} language: type: string description: Can be provided to set the lang attribute of the <html> element. default: undefined languages: type: array description: Languages (2 letter abbreviations) you wish your player to support, from the video.js supported list items: type: string enum: - ar - ba - bg - ca - cs - da - de - el - en - es - fa - fi - fr - gl - he - hr - hu - it - ja - ko - nb - nl - nn - pl - pt-BR - pt-PT - ru - sk - sr - sv - tr - uk - vi - zh-CN - zh-TW loop: type: boolean description: Indicates if the video should play over as soon as it ends default: false media: type: object description: Media information for non-Video Cloud media properties: sources: type: array description: Array of non-Video Cloud media sources items: type: object properties: height: type: integer description: Video frame height in pixels width: type: integer description: Video frame width in pixels poster: type: object description: Information for the poster image properties: highres: type: string description: The file path to the poster image, relative to the root directory of the skin src: type: string description: The URL of the video file to load into the player title: type: string description: Content of the `<title>` element of the page type: type: string description: MIME type of the video, as specified in the HTML5 standard, for instance `video/mp4` form MP4 or `application/x-mpegURL` for HLS enum: - video/mp4 - application/x-mpegURL src: type: string description: The URL of the video file to load into the player tracks: type: array description: Array of text track objects for non-Video Cloud media items: type: object properties: label: type: string description: Text label for the track, for instance `English` for an English language text track src: type: string description: URL to source of track, required in a track object srclang: type: string description: 2 letter code (valid BCP 47 language tag) for the language of the text track muted: type: boolean description: If `true`, the player will be muted when it loads default: false play_button: type: object description: Properties are available for modification of the play button via player configuration properties: hover: type: string description: '`glow` or `darken`; default is pink / progress color' enum: - glow - darken shape: type: string description: '`square` or `rectangle`; default is a circle' enum: - square - rectangle position: type: string description: '`topLeft` or `topRight`; default is center' enum: - topLeft - topRight player: type: object description: General settings for the player properties: inactive: type: boolean description: Whether the player is active (usable) or not default: true template: type: object description: Object containing details of the template the player is based on properties: name: type: string description: The template name readOnly: true version: type: string description: The player template version - note that you only need to be concerned about this if you have opted out of auto-updates for players. See [Opting Out of Automatic Player Updates](/player-management/guides/opting-out-automatic-player-updates.html) for more information. example: 6.22.7 locked: type: boolean description: Whether the player is locked to prevent auto-updates to new template versions default: false player_id: type: string description: Same as the `id` - the id for the player is returned as player_id when you get the configuration by putting config.json on the end of the player preview URL (it is not returned at all when you get the configuration via the Player Management API, but it returned as `id` in some responses, such as the response to updating or publishing a player).. readOnly: true player_name: type: string description: Same as the `name` - the name you enter for the player is returned as player_name when you get the configuration by putting config.json on the end of the player preview URL (it is returned as name when you get the configuration via the Player Management API. But you must use name when you create or update the player. readOnly: true playsinline: type: boolean description: Allows inline playback (necessary for playback on some devices) default: false plugins: type: array description: 'The `plugins` property specifies the order to initialize video.js plugins and any customized settings to apply to them.
**For plugins in the [plugin registry](https://player.support.brightcove.com/plugins/plugin-registry.html)**: include the `registry_id`and a `version` (and `options`, if any)
**For plugins not in the plugin registry**: include the `name` (and `options`, if any). The plugin must be supported by a corresponding `scripts` property URL entry, and if needed a supporting `stylesheets` URL.' items: type: object properties: name: type: string description: The name of the plugin (for plugins not in the plugin registry options: type: object description: An optional object containing the options for the plugin registry_id: type: string description: The registry id for the plugin example: '@brightcove/videojs-custom-endscreen' version: type: string description: The version of the plugin. You can specify a major version in the form `2.x` and the plugin will automatically update when a new version is released. If you specify a minor version in the form `2.7.1`, the plugin will **not** be automatically updated. example: '@brightcove/videojs-custom-endscreen' preload: type: string description: What data should be preloaded immediately - note that `preload` is just a suggestion in the HTML5 spec, so **there may be different behavior across browsers**.
`auto` indicates that the whole video may be downloaded if possible (which improves performance for viewers, but also consumes unnecessary bandwidth if the user does not watch the video).
`metadata` indicates that video metadata should be preloaded; at least a few seconds of the video itself will also be preloaded.
`none` tells the player not to load any video data or metadata until the user clicks play. enum: - auto - metadata - none default: none query_string_to_window: type: object description: Used to control the population of the global namespace (window) from query string parameters. This is useful particularly in cases of embedded players, such as Google's AMP components or Facebook Instant Articles. The parsing of query strings is done using the Node.js querystring module. Use of this configuration object requires at least one of the following sub-properties. Both can be used simultaneously. **Supported for Standard (iframe) player implementations only.** properties: target: type: string description: 'A destination object to create on the window, which will be populated with the entire parsed query string. For example, a use of query_string_to_window.target given the following in a player configuration:
{
"query_string_to_window": {"target": "queryStringParams"}
}
and given the following query string:
?foo=bar&nums=1&nums=2
would yield the following window.queryStringParams global object would be available to the player and plugins:
foo: ''bar'',
nums: [''1'', ''2'']
}' globals: type: array description: 'Description: An array of property names of the window object, which will be populated from values found in the query string. Any matching properties that already exist on the window object or its prototype chain will not be set. For example, a use of query_string_to_window.globals given the following in a player configuration:

{ 
 "query_string_to_window": { 
 "globals": [ 
 "foo", 
 "nums", 
 "self" 
 ]}}

and give the following query string:
?foo=bar&nums=1&nums=2&self=not-allowed
would yield the following window global object with the following properties added:

window.foo; // ''bar'' 
 window.nums; // [''1'', ''2''] 
 // Because `self` already exists on the `window` object, it will not be set 
 // and a warning will be logged to the browser console. 
 window.self; // window

' items: type: string repeat: type: boolean description: Will cause a playlist to repeat playing **IF** the player is a playlist player. Set at the top level of the player configuration. default: false scripts: type: array description: 'The data type is an array of strings (URLs) referencing JavaScript files that are included with the player. At the time the player is built, these files will be downloaded and inlined into the resulting output so that they do not need to be subsequently fetched at runtime. Note: unless the script is for a registered plugin, you can **not** use it to interact with the player.' default: none items: type: string skin: type: string description: Select the Brightcove Player 1.x skin instead of the Brightcove Player 5.x look. If you enable this option, you will also need to make sure Brightcove Player 1.x `compatibility` property is also set to `true`. enum: - graphite stylesheets: type: array description: 'The data type is an array of strings (URLs) referencing CSS files that are included with the player. At the time the player is built, these files will be downloaded and inlined into the resulting output so that they do not need to be subsequently fetched at runtime. Note: the stylesheets are included in the order you specify them.' default: none items: type: string techOrder: type: array description: 'By default Brightcove Player performs tech-first ordering when it searches for a source/tech combination to play videos. This means that if you have two sources and two techs, the player will try to play each video with the first tech in the `techOrder` option property before moving on to try the next playback technology. See the [Guide: Playback Technology](https://player.support.brightcove.com/playback/guide-playback-technology.html) document for more information.' default: - html5 - flash items: type: string enum: - html5 - flash video_cloud: type: object description: With this property you can create a player using a video from your Video Cloud library and add a few more settings specific to Video Cloud. properties: aspect_ratio_width: type: string description: Set the width of the player for aspect ratio calculations - typically used only for non-standard aspect ratios default: '{automatically assigned}' example: '630' aspect_ratio_height: type: string description: Set the height of the player for aspect ratio calculations - typically used only for non-standard aspect ratios. default: '{automatically assigned}' example: '300' base_url: type: string description: Set the base URL for the player - this setting should be used **only** to overcome IP restriction issues - see the [Player Configuration Guide](/player-management/guides/player-configuration-guide.html#iprestrictions) for more information. enum: - https://edge.api.brightcove.com/playback/v1/ - https://edge-elb.api.brightcove.com/playback/v1/ default: https://edge.api.brightcove.com/playback/v1/ example: https://edge-elb.api.brightcove.com/playback/v1/ max_retry: type: integer description: For [Generic Stream Concurrency](/playback-restrictions/guides/generic-stream-concurrency.html), the number of times the player should try to connect to the server to check concurrency limits default: 3 interval_retry: type: integer description: For [Generic Stream Concurrency](/playback-restrictions/guides/generic-stream-concurrency.html), the interval in milliseconds between retries when the player is unable to connect to the server default: 60000 policy_key: type: string description: A policy key for the player. Policy keys are created automatically for the player, so there is no need to set it yourself unless you want to provide a key that is enabled for video search. You can use the Policy API or [this sample app](/policy/getting-started/quick-start-policy-api.html) to create a search-enabled policy key if you need one. default: '{the key automatically assigned}' poster_image_url: type: string description: Public URL for a custom poster image to be used by the player. default: '{the key automatically assigned}' thumbnail_image_url: type: string description: Public URL for a custom thumbnail image to be used by the player. default: '{the key automatically assigned}' video: type: string description: A Video Cloud video id (you can also use the reference id with the syntax `ref:reference_id`) default: undefined parameters: account_id: name: account_id in: path description: Video Cloud account ID. required: true style: simple explode: false schema: type: string Authorization: name: Authorization in: header description: '**IMPORTANT:** Basic Authentication is no longer supported. You must use OAuth 2.0 for all authentication. `Authorization: Bearer {access_token}` - (see [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html))' required: true style: simple explode: false schema: type: string player_id: name: player_id in: path description: Brightcove Player ID. required: true style: simple explode: false schema: type: string branch: name: branch in: path description: A plugin id required: true style: simple explode: false schema: type: string enum: - master - preview ContentType: name: Content-Type in: header description: 'Content-Type: application/json' required: true style: simple explode: false schema: type: string example: application/json securitySchemes: BC_OAuth2: type: oauth2 description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more flows: clientCredentials: tokenUrl: https://oauth.brightcove.com/v4/access_token scopes: video-cloud/analytics/read: Read analytics data video-cloud/video/read: Read video data x-bc-implicit-head: true x-bc-implicit-options: true x-bc-upstream: https://backend_server