Stream Personalization
Configure placement
Configure the connection to an ad server

Configure the connection to an ad server

General configuration

To configure a connection to an ad server, follow these steps:

  1. Click the Placement tab and configure the different fields as follows:

    ParameterDescription
    Can prefetchEnables anticipated calls to the ad server. Prefetch markers (HLS tag or DASH event stream) shall be present in the manifest/playlist and defined in a dedicated plugin. Prefetch cache duration can be configured.

  2. Go to the Placement Rules section then click Add to configure the ad decision server general parameters.

    Ad Server configuration

  3. Configure the different fields as follows:

    ParameterDescription
    NameProvide a name to your ADS connection (e.g.: Freewheel, my_Ad_Server…)
    TypeThis parameter defines the protocol/communication with the ad server. For Ad-related operations, Stream Personalization implements the following:
    - VAST
    - VMAP
    - SCTE-130-3
    - SCTE-224
    Note: Other ad decision servers can be supported via ADS plugin (see Manage Stream Personalization plugins).
    Decision server URLThis is the HTTP endpoint Stream Personalization connects to upon ad break detection (or upon first live/content request for pre-roll use case for instance). This configuration is usually ad server-dependent and conveys required audience and ad break details via a templated URL with well-defined key/value pair. Configuration is done via URL template, leveraging information from the following sources:
    - Query parameters from the viewer manifest request
    - Viewer request pathname
    - HTTP header from the viewer manifest request
    - Splice information retrieved in-manifest
    - Global variables
    Decision server URL example: http://ads.ip.address/ads?RequestID=hostname-{random}& VAST=vast30&Version=1.0&ChannelID={#regex} {pathname}:/hls-(.+)/{/regex}&AvailNo={splice.availNum}& HHID={query.accountID}&DeviceID={query.deviceID}& Vdur={breakDurationSeconds}
    Note: For a complete description of available variables to build such URL template, see Manage Decision server URL template.
    TriggerSelect between Marker or View Start:
    - Marker: Stream Personalization sends a placement request to the ad server when detecting in-manifest SCTE-35 markers in the source manifest.
    - View Start: Stream Personalization sends a placement request to the ad server upon first connection. This can be used for live pre-roll, or VOD ad insertion based on VMAP response for instance.
    - View Access: Stream Personalization sends a placement request upon first connection to an ACDS and replaces all the content if the rules apply (use case example: do not grant access to the playlist for unauthorized viewers).
    Skip live event ads in the pastFor live events only: when a viewer connects to a live playlist, prevent ad insertion in past content.

  4. Once you have configured the ad decision server general parameters, you can:

  5. Click Ok to validate the new placement rule creation.

Multiple placement rules can be created. Ordering is important: for each placement opportunity, the rules are processed successively until a rule with all matching parameters is applied. If you want to reorder priorities, just select the three-bars icon next to the Placement rule name and reorder them.

Manage Decision server URL

Upon placement opportunity detection such as ad break or alternate content (blackout for instance), or first content request using viewing start trigger mode, Stream Personalization connects to a decision server entity with a well-defined HTTP request. This HTTP connection carries a set of key/value pair (syntax being ADS-dependent), which value must be automatically filled by Stream Personalization.

Stream Personalization automatically retrieves information from two different sources:

  • The manifest URL request (query parameter, and HTTP header)
  • The source conditioned manifest, with splice information embedded

Since Stream Personalization manages audience/user-based manifest manipulation, the information to be conveyed to the ad server for instance will be different for each audience/user connected. You thus need to template the decision server URL with variables that will be automatically filled by Stream Personalization.

An illustration is given below with details on how to access the different variables, and have them injected into the ad decision server URL.

Decision server URL template Decision server URL template

URL template using URL query parameters

A manifest request URL (sent by the player/CDN) is usually made of the path to the manifest itself, to which query parameters are appended. An example is given below:

http://sp.ip.address/hls/catchup/hls-239192/plist/index.m3u8?deviceID=LG-H815&accountID=24699

Stream Personalization automatically detects these query parameters (regardless of the number), it can use them when sending outbound request (to a decision server for instance).

In this example, the query parameters deviceID and accountID values will be accessed the following way respectively: {query.deviceID} and {query.accountID}.

These two variables can be used and injected into the decision server URL template.

URL template using HTTP headers

Stream Personalization automatically retrieves HTTP header information and can use it in any outbound request. The general syntax to access HTTP header information is defined as follows:{headers.<http header param>}

<http header param> must be in lower case.

For instance, if the Ad decision system needs Stream Personalization to pass cache-control http header (let’s name it UA at the Ad decision level), Stream Personalization will then add into the decision server URL query parameters: UA={headers.cache-control}

The following global variables can be used directly in the URL template:

HTTP header templateDescription
{userIP}Viewer IP extracted from the HTTP header X-FORWARDED-FOR
{userAgent}HTTP header user agent

Example: UA = {userAgent}

When using {userIP} and {userAgent} in the URL template, PII (Personally Identifiable Information) configuration flag must be set to “true”. This flag is configured in the following configuration file:/opt/ericsson/stream-personalization-origin/etc/config.json. See example below.

Example of json configuration file with PII configuration flag set to “false”

URL template using SCTE-35 data from conditioned manifest

SCTE-35Stream Personalization mappingDescription
Splice_event_id{splice.id}Unique id of the ad break/splice event.
Break_duration(){breakDuration}Ad break duration in terms of ticks of the program’s 90 kHZ clock
{breakDurationSeconds}Break duration translated in seconds instead of program’s 90kHZ clock
{breakDurationMilliseconds}Break duration translated in milliseconds instead of program’s 90kHZ clock
{breakDurationISO}Break duration translated in ISO format instead of program’s 90kHZ clock
avail_num{splice.availNum}Avail number
Segmentation_type_id{splice.segmentationTypeId}Value used to determine whether the splice indicates a program start/end, placement opportunity start/end etc. (see standard for all possible values)
Segmentation_descriptor(){splice.segmentationDescriptor}Segmentation descriptor raw data bytes. These raw data can be used by 3rd party component to manage ad-hoc parsing.

URL template using Manifest/playlist information

ManifestStream Personalization mappingDescription
Manifest duration{manifestDurationSeconds}For non linear only. Manifest duration in seconds.
Manifest duration{manifestDurationMilliseconds}For non linear only. Manifest duration in milliseconds.
Manifest duration{manifestDurationISO}For non linear only. Manifest duration in ISO format.
Configure placementConfigure the connection to an ad server