Working with preview products

Overview

A preview product is one that allows users who do not have entitlements to the product’s contents to view the content for a limited time.

For example, preview could be enabled on a channel bundle product so that users can view these channels for ten minutes in any 24-hour period.

A client application needs to:

• Discover such products so that it can present the preview option to the user.

• Check whether a particular content belongs to a product for which preview is enabled so that it can enable the user to take advantage of the preview option.
  For example, for a channel that is part of a preview product, the client can display the channel in the EPG in such a way that the user will know that they can preview it.

The client can also enable upsell for such products, for example, to make it easy for the user to subscribe to the product that they are previewing.

This is explained in more detail below.

Handling preview products

The client needs to take the following steps to correctly handle preview products:

1. Get products for which preview is enabled so it can display them to the user.
   This could be in a dedicated section and/or in its existing product display functionality.
   See Getting preview-enabled products, below.

2. Check whether a content/channel belongs to a product for which preview is enabled.
   The client should check the value of the isPreviewEnabled field for the products that include the content/channel. The client can find these products in:

   1. The content or channel’s media card – see:

      • Media cards

      • Content Discovery Facade API documentation – Media Card endpoints

   2. The content or channel within a rail response – see:

      • Rail reponses

      • Content Delivery API documentation – the GET

        /contentdelivery/v1/templateviews/{templateIdOrName}/rails/{railId} endpoint

   3. The content or channel within an Metamorph or MDS response – see:

      • Retrieving channel lists

      • Retrieve content information

      • Metamorph API Documentation – BTV and VOD endpoints

3. Report playback start and playback stop events for the content (in the same way as for any other content).
   See Reporting activity and event metrics to UAV.

4. Stop playback or prevent playback start if the preview time has expired or the session limit has been reached.
   The client heartbeat (keep-alive) call to SSM will fail if:

   • The preview time for the product that the content/channel has already expired when the client attempts to begin playback.

   • The preview time expires while the user is watching the content.

   • The preview session limit has been reached.

   When this happens, SSM:

   • Returns an HTTP 403 status with an error code of 3008 (preview duration exceeded).

   • Includes the previewReset field in the error response. This contains the time (in Unix epoch time) when preview will be available again for the product

   The client should display a suitable message to the user (which can include the reset time).
   See Session control with SSM.

Getting preview-enabled products

Request

To get preview-enabled products, send a GET request to:

https://<host>:<port>/metadata/v1/products

Mandatory arguments

None

Other arguments

All these arguments are query parameters:

• sort – a list of pairs, where a pair is a list containing a field name and a sort order with 1 ascending and -1 is descending.

• fields – a list of fields names to return in the response.

• page – the page number to return (cannot be used without limit)
  For example:

  • ?limit=10 returns the first 10 records.

  • ?limit=10&page=2 returns the second 10 records.

• limit – the number of records to return for pagination.

• cache – sets or unsets HTTP headers. true allows CDN caching, false prevents CDN caching.

• distinct – returns a distinct list of values for the given field. Usage: ?distinct=<field_name>

• You can also filter on the following fields by appending ?<field_name>=<value> as a query: id, type, pack_collection, member_of_pack
  For example, ?type=capability.

Response

The response includes all the relevant metadata for each product.

See Metamorph API Documentation for more details.

See also

Enabling preview for a product