Converting an ad tag for the Once Media Management API

This guide will help you understand how Brightcove Once handles an ad tag’s components so you can best leverage Once’s server-side ad handling capabilities. By the end of this guide you should understand how to convert your ad provider’s tag to Brightcove’s Once Media Management API JSON syntax.

1. Obtain the ad tag

Work with your ad provider to generate an ad tag. Be sure your ad provider understands that this tag will be used with Server-Side Ad Insertion (SSAI); some providers have specific query strings which must be present in an ad tag for SSAI.

Below is a generic example ad tag (yours will vary):

http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s &env=vp&output=xml_vast2&vid=video_id_value&ip=10.10.34.28&iu=/1234/ad_unit_value &unviewed_position_start=1 &url=mysite.com&cachebuster=random_number&ad_rule=1 &nofb=1&ss_req=1&cust_params=custompagevalue

2. Break down the ad tag

Separate the ad tag into its composite parts. Below is the example ad tag, broken into its path and individual query strings.

Path

http://adserver.adprovider.com/adpath/ads

Query strings

sz=640x480
impl=s
env=vp
output=xml_vast2
vid=video_id_value
ip=10.10.34.28
iu=/1234/ad_unit_value
unviewed_position_start=1
url=mysite.com
cachebuster=random_number
ad_rule=1
nofb=1
ss_req=1
cust_params=custompagevalue

3. Classify each query string

Work with your ad provider to understand each query string’s value and how that value may be generated. Each value may be:

Static
Always the same value
Dynamically generated by Brightcove Once
Video, user, and/or session properties (see appendix 1 for all available Dynamic Ad Parameters)
Generated by your app/page
Will be passed through using Once URL query strings (see our Getting Started with Once guide for more information)

In this example, you and your ad provider determine that the following query string values will always be static:

sz=640x480
impl=s
env=vp
output=xml_vast2
unviewed_position_start=1
ad_rule=1
nofb=1
ss_req=1

In this example, the following query strings’ values would be dynamically generated by Brightcove Once (see appendix 1 for all available Dynamic Ad Parameters):

vid=video_id_value         (the Once ForeignKey value assigned to the video)
ip=10.10.34.28             (the user’s IP address)
url=mysite.com             (URL of the requesting page)
cachebuster=random_number  (a random number for cache busting)

In this example, the following query strings’ values would be generated by the requesting page and passed through the Once URL:

iu=/1234/ad_unit_value
cust_params=custompagevalue

4. Return static values to the base URL

Because they’ll never change, insert query strings with static values back to the base URL. The order in which you insert these query strings will be reflected in the ad request, see Step 7 for details about inserting dynamic or passed-through query string values between static query strings.

Base URL

http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1

Variables

vid=video_id_value
ip=10.10.34.28
url=mysite.com
cachebuster=random_number
iu=/1234/ad_unit_value
cust_params=custompagevalue

5. Replace dynamic values with appropriate Dynamic Ad Parameters

As determined before, the following query string values will be generated by Brightcove at the time of request using properties of the video, user, and/or session:

url=mysite.com
cachebuster=random_number
vid=video_id_value
ip=10.10.34.28

Replace the values with the corresponding Dynamic Ad Parameter (see appendix 1). Be sure to include the double-curly-braces, as reflected in the below example:

Base URL

http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1

Variables

vid={{mediaitem.foreignkey}}
ip={{ipaddress}}
url={{referringURL}}
cachebuster={randomnumber32}}
iu=/1234/ad_unit_value
cust_params=custompagevalue

6. Replace passed-through values with appropriate passthrough parameters

You previously determined the following query string values would be generated by the requesting page:

iu=/1234/ad_unit_value cust_params=custompagevalue

These values will appended to the Once URL using pass-through parameters (UMADPARAM, UMPTPARAM, UMLITERAL; see our Getting Started with Once guide for an explanation of all Once pass-through parameters). Update your variables to reflect the formatting below:

Base URL

http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1

Variables

vid={{mediaitem.foreignkey}}
ip={{ipaddress}}
url={{referringURL}}
cachebuster={{randomnumber32}}
UMADPARAM=UMADPARAMiu
UMPTPARAM=UMPTPARAMcust_params

7. (Optional) Determine if any query string variables must be inserted to specific places

Once does not order dynamically-generated or passed-through query strings when appending them to the ad tag. Some ad providers require that some or all query strings in the ad tag must be specifically ordered. Discuss this possibility with your ad provider and ensure that you fully understand whether query strings in the ad tag must be specifically ordered. To meet this requirement you can insert placeholders to the base URL and then assign them to the corresponding ad tag variable.

For this example the vid, IP, and iu query strings must always follow the output query string.

First, insert placeholders to the base URL. Placeholders must be double-curly-braced, we recommend the below syntax {{ph01}}, {{ph02}}, etc.:

http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&{{ph03}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1

Next, assign matching double-curly-braced placeholders to the corresponding variable keys:

url={{referringURL}}
cachebuster={{randomnumber32}}
{{ph01}} vid={{mediaitem.foreignkey}}
{{ph02}} ip={{ipaddress}}
{{ph03}} UMADPARAM=UMADPARAMiu
UMPTPARAM=UMPTPARAMcust_params

Any variables without placeholders will be appended to the end of the base URL, but the order may vary. If all adServer variables must be ordered in specific places of the ad tag, insert and assign placeholders for each of them.

8. Insert base URL and variables to Media Management API syntax

Now that you’ve fully organized your ad tag, it’s time to implement it. Below is the Create Ad Decisioning Server JSON syntax for the Once Media Management API. Insert your base URL and variables to the request body accordingly:

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers

Required HTTP header:

X-BC-ONCE-API-KEY : {yourApiKey}

Request body:

{
    "name": "Documentation adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&{{ph03}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "variables": {
        "url": "{{referringURL}}",
        "cachebuster": "{{randomnumber32}}",
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "{{ph03}} UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params"
    }
}

Request fields:

Field Type Required? Description
name String Yes The new adServer’s name
baseUrl String Yes The new adServer’s base URL
variables Object Yes (see description)

An object set of query string key/value pairs to be inserted/appended to the base URL at request time.

If your base URL requires no variables, include an empty variables object ("variables": {})

Response body:

{
    "id": "c06cb299-776d-47d1-9940-7d08f1ffcbe7",
    "name": "Documentation adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&{{ph03}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "variables": {
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "url": "{{referringURL}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "{{ph03}} UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params",
        "cachebuster": "{{randomnumber32}}"
    }
}

Response fields:

Field Type Description
id String The adServerId
name String The adServer’s name
baseUrl String The adServer’s base URL
domainId String The adServer’s parent domainId
variables Object

An object set of query string key/value pairs to be inserted/appended to the base URL at request time

Response variable order may not match your original input, this is expected and will not affect ad tag performance

That’s it! You can now convert any ad tag to the JSON syntax necessary for implementation. Remember to review the response or use the GET Ad Decisioning Server method to verify that all configs were received and correct, and you can contact Support if you have any other questions.

Special cases

FreeWheel Smart XML

If you utilize FreeWheel Smart XML and your ad tag requires semicolon-separated global, key value, and/or slot params (refer to your FreeWheel documentation for more info), you must use placeholders on all variables (detailed in step 7) to insert the variables to the correct positions in the ad tag.

Example

http://1234.v.fwmrm.net/ad/g/1?ssnw=1234&asnw=1234&flag=+sltp+emcr+slcb&resp=xml &nw=1234&csid=site.section.value&caid=video_asset_id&vdur=90 &prof=1234:profile_value;statickey=staticvalue &k1=passedinvalue;slid=slot_id_value&slau=preroll&ptgt=a&tpos=0&maxd=60;

In this example the csid, caid, vdur, and k1 query strings are dynamically generated (step 5) or passed through the Once URL (step 6).

Following the process in this guide, the Create Ad Decisioning Server JSON syntax would be:

{
    "name": "Documentation SmartXML adServer Example",
    "baseUrl": "http://1234.v.fwmrm.net/ad/g/1?ssnw=1234&asnw=1234&flag=+sltp+emcr+slcb&resp=xml&nw=1234&{{ph01}}&{{ph02}}&{{ph03}}&prof=1234:profile_value;statickey=staticvalue&{{ph04};slid=slot_id_value&slau=preroll&ptgt=a&tpos=0&maxd=60;",
    "variables": {
        "{{ph01}} UMADPARAM": "UMDADPARAMcsid",
        "{{ph02}} caid": "{{mediaitem.foreignkey}}",
        "{{ph03}} vdur": "{{mediaitem.duration}}",
        "{{ph04}} UMADPARAM": "UMADPARAMk1"
    }
}

Appendix 1: Ad Request Dynamic Ad Parameters

Ad Request Dynamic Ad Parameters (DAPs)

Parameter Description
{{mediaitem.title}} String value of mediaitem defined by the title ingest object. Spaces will be encoded as %2B
{{mediaitem.tremor.title}} String value of mediaitem defined by the title ingest object. Space will be encoded as %20
{{mediaitem.guid}} String value of the system generated mediaitemId
{{mediaitem.foreignkey}} String value of foreignkey defined by the foreignkey ingest object for the mediaitem
{{mediaitem.duration}} Content file duration in seconds based on the total length of content
{{mediaitem.adposition}} Integer value for the ad position, e.g., 1, 2, 3 for pre, mid, post
{{mediaitem.adpositiontime}} Time in seconds relative to the content where ad is being played
{{uniqueuserid}} A string value used to identify unique viewers without the use of cookies
{{requestguid}} A guid generated to identify a session
{{randomnumber32}} A unique system generated random number
{{randomguid}} A unique system generated random guid
{{timestamputc}} A 32 bit representation of the current time in seconds past epoch (UTC)
{{useragent}} String of the useragent of the requesting client device
{{ipaddress}} User’s IP address
{{dma}} Designated Market Area - 3 digit numeric code
{{state}} Abbreviated State code
{{region}} Name of the region
{{referringHost}} String of the referring host from which the content was requested
{{referringURL}} URL encoded representation of the HTTP Header: Referrer
{{countrycode}} String of the ISO two-letter country code
{{postalcode}} String of the user’s postal code (if available)
{{xm."key"}} Used to extract extended metadata defined at ingest by the "metadata" object for the key and its set value
{{latitude}} To accommodate ad providers that require lat/long to be sent with ad tag request
{{longitude}} To accommodate ad providers that require lat/long to be sent with ad tag request