Using GAM Premium with Brightcove Player

This topic shows you how to create a GAM Premium ad rule that will play pre-, mid- and post-roll video ads in Brightcove Player. It is assumed you already have a GAM Premium account and some familiarity with the platform.

Disclaimer

GAM Premium has hundreds of options that lead to a nearly infinite amount of possible configurations. This document shows one way to create an ad rule that gets used by a Brightcove Player. This document is not an exhaustive treatment of GAM Premium configuration and implementation. It is meant to be a starter exercise to introduce Brightcove customers to GAM Premium/Brightcove Player integration. This document in no way is meant to replace any of Google's GAM expansive documentation.

Overview

The chances of you needing the exact GAM Premium configuration detailed in this document is almost nil. That being said, this document will introduce you to the terms, concepts and configuration steps needed to start you on your path to successfully integrating GAM and Brightcove Player.

You need to build some kind of a knowledge foundation so that the detailed steps that follow in this document can be used in reference to a bigger picture. This overview section of the document will help you familiarize yourself with terms, high-level concepts and broad steps you need to understand before getting "into the weeds" of implementation.

Terminology

The following terms are used extensively in this document. Gaining knowledge of them will assist in successful implementation and understanding of the integration process detailed in the steps below. The definitions have a video advertising slant reflected in this document, and may not be applicable to all GAM uses.

  • Inventory: The video ad slots available to sell.
  • Advertiser: A company purchasing your video ad slots.
  • Ad unit: A container to organize your inventory and detail how your inventory is defined.
  • Order: An agreement between the inventory owner and a buyer that specifies the details of an advertising campaign.
  • Line item: Specifies when/where an advertiser's ads will appear. Also specifies the actual videos ads and companion ad images.
  • Creative/creative set: The video(s) and/or image(s) that are the actual ads and/or companion ads. With video advertising the combination of a video and companion ad is a creative set. Creatives are associated with line items.
  • Video content source: In this case, Brightcove Video Cloud.
  • Ad rule: Define how ads display with your video content. For instance, as a pre-roll and a mid-roll every 5 minutes.
  • Ad tag: A URL that points to the definition of how ads should be used when playing back a video. The ad tag is used when configuring IMA advertising with Brightcove Player.

Process overview

The following illustrates the entities created and their relationships.

DFP Overview Diagram

The following provides the next level of detail of the process.

  1. Create an advertiser. In GAM speak, this is a company of type Advertiser. This is required as when an order is created it must be associated with an advertiser.
  2. Create an ad unit. This is an organizer for your inventory and you will specify the size of video ads and companion ads you want from the advertiser.
  3. Create an order. The order will detail who the advertiser is. Although it can be done later, the GAM interface also allows the line items to be created as part of the order, which will be the process followed in these steps.
  4. Create a line item as part of the order. The line item will detail you want to use Video VAST ads, the size of the ad videos, when they should start and stop.
  5. Target (link) the particular line item to an ad unit. The order, through a line item, matches the advertiser's ads to your inventory.
  6. Create creative sets. Before this step you have line items which contain no actual video ads. In this exercise you will supply both video ads and corresponding companion ad images (if you wish to display them).
  7. Associate creative sets with a particular line item.
  8. Create an ad rule. This defines when and how the ads should play. As part of the ad rule creation you associate it with an ad unit. This means that if inventory from an ad unit is used, the definitions of the ad rule will be used to specify ad playback times.
  9. Generate an ad tag. This is the URL that is used when configuring the IMA3 plugin. Note the original ad tag will not function correctly. Three query string parameters must be added for proper configuration.
  10. Connect to Video Cloud. This is done to retrieve a value needed for one of the aforementioned query string parameters.
  11. Use Google's Video Suite Inspector to be sure the ad tag is functioning correctly.
  12. Lastly (and finally) use the ad tag with Brightcove Player.

Create an advertiser

If you will be using an advertiser that already exists, you do not need to complete this section.

  1. Follow the numbered steps and click New company.
    navigate to ad units
  2. From the dropdown select Advertiser
  3. Supply an advertiser name.
  4. Click Save.

Create an ad unit

  1. Follow the numbered steps and click New ad unit.
    navigate to ad units
  2. From the selections that appear, select Current level.
  3. Supply appropriate values for the Code, Name and Description.
  4. Select the Video (VAST) sizes.
  5. Based on your videos and companion ads, enter the sizes. In this example the videos are 1280x720 and the companion ads 728x90. You can either select the size if they have been previously used, or enter new sizes.
    create ad unit sizes
  6. No further information need be entered, so scroll down and click Save.

Create an order

  1. Follow the numbered steps and click New order.
    navigate to order
  2. Enter a Name for the order.
  3. Click in the Advertiser box. Select an existing advertiser, either the one created earlier in this document, or one that existed previously.
  4. The Trafficker entry will be pre-populated with your name and email address.

Create a line item

A line item can either be created at the same time as a new order, or created later then associated with the order. In this exercise, you will create the line item as you are creating the order.

  1. Enter a Name for the line item.
  2. For the Inventory sizes, click Video VAST.
  3. Enter sizes for videos and companion ads. You will most likely enter the same sizes as used for step 9 above.
  4. Check the Allow same advertiser exception. This permits ads from the same advertiser to be used for pre-, mid- and post-rolls.
  5. Check to be sure your form is filled out similarly to the following:
    line item properties
  6. In the line item Settings section, set the following:
    • Type: Sponsorship
    • Start time: Immediately
    • End time: Unlimited
  7. Scroll down to the Add targeting section.
  8. If it is not selected, click Inventory.
    targeting ad unit
  9. Click Ad units.
  10. Click the include button next to your ad unit to associate this order with your ad unit.
  11. Click Save to finalize the configuration of the new order and line item.
  12. Click the Approve button to approve your newly created order.
    approve order
  13. Click the Approve button again to acknowledge the overbooking warning.
    overbook warning

You have now created an order and an associated line item.

Create creative sets

You will repeat the steps in this section once for each creative set you wish to create. There are two parts to creating a creative set, uploading the video and also uploading the image for the companion ad.

  1. Follow the numbered steps and click New creative set.
    create-creative
  2. Select an advertiser with which to associate the new creative set.
  3. Click Video VAST.
  4. Enter sizes for videos and companion ads. You will most likely enter the same sizes as used for step 9 above.
  5. Click Continue.
  6. Enter a Name for the creative set.
  7. When ask to Select a creative set type, click Linear.
  8. Click Video.
  9. For the video asset, set the following:
    • Creative set name
    • Name (of the video asset)
    • Click-through URL
    • Duration
  10. Check to be sure your form is filled out similarly to the following:
    line item properties
  11. Supply the video by either dragging and dropping into the highlighted area, or browse for the file.
  12. You will notice that various renditions of the video ad will be created.
  13. Scroll down to the Companion creative section.
  14. For the companion ad image asset, set the following:
    • Name (of the image asset)
    • Image file
    • Click-through URL
  15. Click Save to finalize the configuration of this creative set.

Add creatives to the line item

  1. Follow the numbered steps and to see the orders you have created.
    navigate to my orders
  2. Click on the order you've created during this exercise.
  3. Click your line item name to begin the process of adding creatives to the line item.
    add creatives to line item
  4. Click the Add creative sets dropdown and select use existing creative sets.
    add creatives to line item button
  5. Click the Creatives folder in the dialog that pops up.
    click creatives
  6. Click the include button for the creative sets you wish to include.
  7. Click Save in the Use existing creatives dialog.
  8. Scroll down and click Save to finalize the changes to the line item.
  9. Click on My orders again, and you will see the line item for your order is now labeled Ready.
    line item ready

Create an ad rule

In an ad rule you configure when you want your ads to play. You will have options for each of pre-, mid- and post-role, as follows:

ad rule example

Depending on your selection from the dropdown, and the roll type, you will then be presented with further options.

  1. Follow the numbered steps and click New ad rule.
    navigate to ad rule
  2. Provide a Name for the ad rule.
  3. For the Status, click the Active button.
  4. Configure the pre-, mid- and post-roll ads as desired. An example configuration follows:
    ad rule form
  5. In the ad rule Settings section, set the following:
    • Start time: Immediately
    • End time: Unlimited
  6. Scroll down to the Targeting section.
  7. Click Inventory then Ad units to see all available ad units.
    ad rule targeting
  8. Click the include button for the ad unit created earlier in this exercise. This instructs your ad unit to use this ad rule.
    ad rule form
  9. Click Save to finalize the configuration of your ad rule.

Generate an ad tag

  1. Follow the numbered steps to include your ad unit and then click Generate tags.
    navigate to generate tags
  2. Click the Continue button to accept Google Publisher Tag as the tag type.
  3. Click the Continue button again to accept the targeting and sizes.
  4. Click in the Video Units text area and copy the entire ad tag.
    copy ad tag
  5. Paste the copied URL into a browser, browse it, and you will see the VAST XML associated with your ad tag. NOTE, this is not the final version of the needed tag.

Connect to Video Cloud

The only reason the steps in this section of the document need to be performed for this exercise is to generate a source ID that indicates a connection to Video Cloud. This ID is required in the next section.

  1. Follow the numbered steps and click New source.
    navigate to source
  2. Provide a Name for the source and set the Type to Brightcove.
  3. Follow the steps in the Managing API Authentication Credentials document to obtain a Client ID and Client Secret. You will select the following for API permissions:
    correct
  4. Enter, then validate, the Client ID, Client secret and Account ID. When you validate the credentials, you will see a list of videos from your Video Cloud account.
  5. Check to be sure your form is filled out similarly to the following:
    source form
  6. Click Save.
  7. After saving, you will see information similar to the following. Record your source ID as it will be used later in this exercise.
    source created

Test the ad tag

  1. Just above the ad tag you will see a link to the Video Suite Inspector. Open this link in another browser or tab.
    vsi link
  2. Paste your ad tag into the text box for the VAST tag.
    vsi test
  3. Click the TEST AD button and you will see ONLY the pre-roll will play.
  4. Again, paste the ad tag into a browser, but before browsing, add the query string parameter &ad_rule=1 to the end of the ad tag. You will see the XML displayed has changed to reflect that a pre- and post-roll are defined. This query string parameter turns using ad rules on. There is a chance that ad rules may be turned on for the entire account, in which case, you will not have to use this query string parameter.
    browsing the ad tag, pre and post roll showing
  5. Add the query string parameter to the ad tag in the Video Suite Inspector and you will see the pre- and post-roll ads now play.
  6. Locate the source ID recorded from step 72 above.
  7. Also, locate a video ID from a Video Cloud media asset.
  8. Add another query string to the ad tag, this time using the field to be cmsid, and the associated value to be the retrieved source ID. 
          cmsid=1111
  9. Add yet another query string to the ad tag, this time using the field to be vid, and the associated value to be the video asset ID. 
          &vid=4825296720001
  10. The entire query string added should appear similar to the following: 
          &ad_rule=1&cmsid=1111&vid=1234567891234
  11. Again, paste the ad tag into a browser, and add the complete query string to the ad tag. You will now see the mid-roll has been added to the generated XML.
    browsing the ad tag, pre, mid and post roll showing
  12. Add the query string parameter to the ad tag in the Video Suite Inspector and you will see the pre-, mid- and post-roll ads now play.

You now have a functioning ad tag, and are (finally) ready to use it with Brightcove Player.

Use the ad tag with Brightcove Player

Fairly broad steps will be used here on how to configure Brightcove Player's IMA3 plugin to use the ad tag you have constructed. If you need more detailed instruction, see the Implement using Players module section of the Advertising with IMA3 Plugin Guide document.

  1. In Studio's PLAYERS module, create a new player, or use an existing player, and view its properties.
  2. Scroll down to the Advertising section, and click the Edit button.
  3. Click Yes for Enable IMA Ads.
  4. For the Server URL, enter the ad tag that includes the three query string parameters.
  5. Leave the rest of the values the same, and click Save.
  6. Publish your player.
  7. Navigate to the MEDIA module and click on the video whose ID you used in the vid query string parameter.
  8. Publish this video using the player to which you added IMA3 advertising.
  9. Use the Standard or Advanced code and test your configuration.

Display companion ads

Displaying companion ads is as easy as copying code from where the ad tag was generated. The following steps detail the process.

  1. Return to the results of the ad tag generation (or generate the tag again).
  2. Locate the Document header section and copy the code indicated.
    companion code for header
  3. Paste this code into the head section of your HTML page.
  4. Back in the results of the ad tag generation, copy the indicated code.
    companion code for body
  5. Paste the code into the body of your HTML page where you wish the companion ad to be displayed.
  6. Test your HTML page and you will see the companion ad change with the video ad.