Using Third Party Ad Servers

If you want to use a third party ad trafficking platform to target your mobile video advertisements, you can use the External Promotion option to integrate yospaceCDS with your ad server.

The basic steps on setting up advertising with an external server are:

• You must upload advertising creatives into Advert Group(s) using the Content Management tool. 
• Note the Media Item ID of each advert uploaded, and add this into your third party ad server
• Set-up an External Promotion to have yospaceCDS request to your ad server each time a video request is made

Setting up a Custom External Ad Server Promotion

Overview

When a request for a video is made and your External Promotion is applicable, yospaceCDS will make an HTTP GET request to a URL that you specify. The response returned by the ad server is then matched against a specified regular expression to extract the Media Item ID to insert into the video.

Steps

• Create the Campaign you wish to add the Promotion to.  You may find it convenient to add all of your External Promotions to a single campaign.
• Click "Create External Promotion", the External Promotion set-up screen should appear.
• The Name, Description, Campaign, Supports Audio, and State fields are the same as in setting up a regular Promotion (see Setting up Advertising main article).
• Set the URL Template according to the instructions shown below.  This is the URL that is requested by yospaceCDS to request the advert to insert.
• Set the Regex to the regular expression to search for the Media Item ID in the returned response.
• You can set where you want the advert to appear:
  • Before Content (pre-roll)
  • After Content (post-roll)
  • The Same Ads Before and After Content -- a single ad server request will be made
  • Different Ads Before and After Content -- two requests are made to the ad server, the first for the pre-roll, the second for the post-roll
  
• Select to which Content Groups you want this External Promotion to affect.  Whenever a video is delivered from the relevant Content Group it will apply this External Promotion to it (unless there is another Promotion active on this Content Group which has a higher priority).
  • All Content Groups.  The Promotion will be active across all Content Groups.
  • A specific Content Group.  This will require you to set-up an External Promotion for each Content Group you want targeted advertising on.
  
• If your application is adding additional parameters to the yospaceCDS Access URLs, then add the names of these parameters to the Pass Following Parameters list in a comma separated list.  For example, if your application is tracking a user ID, it can be passed through to Helios using this option.
  
• If you wish to have a separate system for tracking hits to your videos, then supply a URL in the Tracking URL field.  This URL is hit every time the Promotion is matched.
• The remaining fields, To Requests From, To Requests On or After, And Strictly Before, Maximum Impressions and Priority are the same as in setting up a regular Promotion (see Setting up Advertising main article).

How to Set-up URL Templates

Token Replacement Rules

You can specify special tokens that are replaced with contextual information when the URL Template is being evaluated.

• Tokens must be specified using the syntax ${TOKEN} for a simple value replacement operation
• Where a token can have multiple values, you can specify these return values using the syntax${TOKEN(value1)(value2)}
• Some tokens can be used to access values from external sources, use the syntax TOKEN.name to specify a specific external name (case sensitive).
• Tokens representing an array of name/value pairs must be specified with the assignment and concatenation symbols, for example ${TOKEN(=)(&)}
• If token yields an empty value, all text specified within the nearest surrounding block defined by square brackets ([]) is removed.
  • For example: http://server/path?[ip=${QUERY_PARAM.ip}&]somethingelse=fred resolves to http://server/path?somethingelse=fred if ${QUERY_PARAM.ip} is has no value

Supported Tokens

CONTENT_ID

the Media Item ID of the content currently requested

FEED_ID

the Output Feed ID through which the content is being requested

CLIENT_IP

the IP address of the requesting client

USER_AGENT

the HTTP User-Agent field supplied by the requesting client

QUERY_PARAM.xxx

where xxx is the name of a specific query parameter supplied in the original request. This parameter must be enabled within the 'Passthrough Parameters' field on the relevant Promotion.

CLIENT_HEADER.xxx

where xxx is the name of a specific HTTP header supplied in the original request.

ADVERT_POSITION(p1)(p2)

where p1 is the value given if the request is for pre-roll placement and p2 is the value for post-roll placement.

METADATA.xxx

this token is replaced by the value of the metadata field named xxx associated with the accessed video item. A special syntax to expand all metadata values is also possible, to do this, use ${METADATA(p1)(p2)} where p1 is the field assignment symbol and p2 is the tuple separation value. For example, ${METADATA(=)(;)} will result in the token being replaced as field1=value;field2=value;field3=value.

Examples

The following example, sends the Media Item ID and Feed ID to advert server. The parameter ac=Example is, for illustration purposes, how this ad server might identify the account it is doing the matching from.

http://adserver-example.net/handler?ac=Example&vid=${CONTENT_ID}&channel=${FEED_ID}

For the Media Item ID 1984102 and feed ID 1234098123 the full request will be made as:

http://adserver-example.net/handler?ac=Example&vid=1984102&channel=1234098123

The following example provides the value of the parameter udid originally specified by the Access URL to the video.

http://adserver-example.net/handler?ac=Example[&userid=${QUERY_PARAM.udid}]

For the request http://cds1.yospace.com/access..&udid=1234567, the resulting call will be made as:

http://adserver-example.net/handler?ac=Example&userid=1234567

Note that this token is surrounded by brackets ([ ]). These have the effect of removing everything that they contain if the token that they contain results in a null value. Therefore, when the incoming request in this example does not include a udid parameter, the request is made as:

http://adserver-example.net/handler?ac=Example

The following example, includes the ADVERT_POSITION to determine whether the call is requesting a pre-roll or post-roll video.

http://adserver-example.net/handler?ac=Example&type=${ADVERT_POSITION(pre)(post)}

Assuming the request was for a pre-roll advert, the request would be made as follows:

http://adserver-example.net/handler?ac=Example&type=pre

Assuming the request was for a post-roll advert, the request would be made as follows:

http://adserver-example.net/handler?ac=Example&type=post

Handling the Ad Server Response

Using Regular Expressions

yospaceCDS must locate the Media Item ID within the ad server's response. To do this, it employs the use of a regular expression, a common means of matching sequences of characters within text. Specifically, yospaceCDS employs Java syntax regular expressions, however Java programmers please note that it is not necessary to double escape the blackslash character in the regular expression you supply to yospaceCDS.

You should construct your regular expression return the Media Item ID as the first capture group.

Example

Supposing that your ad server provides the following type of response:

<response>
  <primary>
    <params key="videourl" value=“827381"/>
    <params key="class" value="direct"/>
  </primary>
</response>

To extract the Media Item ID (in this example 827381) from this response, you would use the regex:

.*key="videourl"\s+value="(\d+)".*