# Validation

Validation is a way to check if a user is allowed to watch content. If validation fails, content is prevented from playing. Validation can be performed before content begins and/or while content is playing.

## How To

Enabling validation requires configuration in two places, on the player config and on the content metadata.

### Player Config

To enable specific types of validation, add the validator types to the validators object in the validaton player config (note, must also be configured on content metadata):

    var player = TOP.createAndInitPlayer({
        config : {
            validation: {
                validators: {
                    '<validator-type>' : {
                        enabled    : true,                       // Must be enabled
                        serviceUrl : '<validation-service-url>', // Specify the url of the service to hit to determine if this is a valid play
                    }
                }
            }
        }
    });

### Content Metadata

Validation must also be enabled on the play call. For media.json this will be specified in the `validation` property of the json response. When playing inline it must be explicitly set.

#### Media Json

When playing content via media.json, the json response will have a `validation` property. An example can be seen on the media.json for tbs-east:

    validation: {
        val0: true // blackout validation should be enabled for this play
    }

Note that `val0` is named as such to make it less obvious to anyone who may be sniffing the data, and wants to avoid a blackout check.

#### Play Inline

To enable specific types of validation when playing inline (note, must also be configured on player config), specify the validator type on the content entry's validators:

    player.play({
        url: 'content.m3u8',
        validators: {
            '<validator-type>': true, // Must enable validator type specified in the player config
        },
    });

### Validation Types

The validator types currently available are:

- `'top.validator.blackout'` - If content has a regional black out flag enabled and user is in a blacked out region, this validator will prevent content playback (note, by default blackout validation is performed for both the pre-play and in-play) (Note: an `appId` is required with the blackout validation service. See AppId for more details)

### Pre-Play

When content is set to play and validators are configured, the validation will be performed after content has initialized but before content plays (ads / media). If all validators succeed, content playback will proceed (ads then media). If at least one validator fails, content playback is prevented (also see validation events for details of success/error).

### In-Play

If content is already playing, validation will be performed at certain points during playback. If at least one validator fails, content playback is prevented (also see validation events for details of success/error).

### Events

Validation success and error can be listened to from the events API:

- validationSuccess
- validationError