Sponsored Products - Integration Guide - v1.0¶

Abstract¶

Onboarding and integration with Verizon Media’s Sponsored Products involves a series of steps outlined in this document. You’ll need to follow these steps in order to implement Sponsored Products for your brand website.

Overview¶

Sponsored Products is a new publishing solution from Verizon Media aimed at major retailer brands and marketplaces, where customers search, discover and purchase various product offerings from online marketplace catalogs and offerings.

Brand-focused marketplaces that sell different brands on their websites will be able to grow supply to larger advertisers and other major brands, using Sponsored Products from Verizon Media.

In so doing, Sponsored Products enable publishers to increase revenue by 10-20% by leveraging strong purchase intent signals from customers coming to their websites.

Customer Interaction¶

Typically, customers follow this sequence of steps when interacting with sponsored products:

The customer opens a browser window, either on the desktop or mobile, and searches for “Men’s boots”.
The search takes the customer to the Super Brand X Shoe Store website.
On the Super Brand X Shoe Store website, the customer searches the product catalog for “Men’s boots”.
The customer sees a “Shoe Brand XYZ” for men’s boots at the top level with a Sponsored tag underneath it.
The ad that appears is a sponsored product already sold at Brand X Shoe Store. The ad experience is same as a normal product listing with reviews listings.
If the customer searches with a filter, results are further narrowed down because of different filtering options – for example, BodyStyle – Dress.
The Ad system will apply this filtering criteria on the product attributes and find the right ad to appear for the customer. The Shoe Brand XYZ ad will no longer be valid based on the selected filtering criteria.

Step 1: Account Creation¶

Begin by creating a Verizon Media advertiser account, if you don’t have one already. Your Verizon Media Account Manager or Solutions Engineer can help provide with one.

Step 2: Feed Integration¶

Follow these steps:

Implement a product feed that specifies general (Google product taxonomy) and custom categories set to the value of a particular product, like Nike shorts categorized as Mens’ activewear, activewear, mens shorts, and so on. Categories are specified as comma-separated values.
Clients need to provide all the filters and categories that a consumer will navigate through on website. Each product should be specified by a separate SKU ID.
For custom fields, set up a meeting with your Verizon Media Account Manager or Solutions Engineer to define custom fields.

Sponsored Product Feed Integration is explained in detail in Sponsored Product Feed Integration.

Important

The document describes the operations for creating, updating and deleting sponsored product feeds, along with tables listing product feed formats and fields.

Step 3: Tracking Integration¶

You’ll need to instrument a custom dot pixel tag separately for each product on a webpage. Use the standard DOT script tag integration but only for purchase events. Purchase events are typically available on the confirmation page of a shopping cart.

Important

Ensure that you send a separate purchase event for every product purchase with your ID and GMV value.

Using Dot Scripts¶

A Dot tag script contains 2 parts:

a standard script and
a dotq script

You must apply the standard script to all the pages that you’d like to track. For the standard part, you can find it on the view tag code page in Verizon Media Native UI. It looks like the following example:

<script type="text/javascript">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({projectId:"XXXX",properties:{pixelId:"YYYY"}});var s=d.createElement(t);s.src=r;s.async=true;s.onload=s.onreadystatechange=function(){var y,rs=this.readyState,c=w[u];if(rs&&rs!="complete"&&rs!="loaded"){return}try{y=YAHOO.ywa.I13N.fireBeacon;w[u]=[];w[u].push=function(p){y([p])};y(c)}catch(e){}};var scr=d.getElementsByTagName(t)[0],par=scr.parentNode;par.insertBefore(s,scr)})(window,document,"script","https://s.yimg.com/wi/ytc.js","dotq"); </script>

In addition to the standard part of the Dot script on the webpage, you also need to add the dotq script to pass the user action and the product id.

Below is an example of the dotq template.

<script type="application/javascript">
    window.dotq = window.dotq || [];
    window.dotq.push(
    {
     'projectId': '10001234567890', -- this value can be found on your Dot page in your account
     'properties': {
       'pixelId': '654321', -- this value can be found on your Dot page in your account
       'qstrings': {
         'et': 'custom',
         'ea': 'insert the standard value',  -- this represents the user interaction with your product
         'product_id': 'product_id value',
       }
    } } ); </script>

Note

Contact your Verizon Media Account Manager or Solutions Engineer to help set up GMV in event.

Step 4: Ad Format & Custom Layout Integration¶

To create a custom layout for your site, you’ll need to set up a meeting with your Verizon Media Account Manager or Solutions Engineer.

Once you have both the AD_UNIT_CODE and an API_KEY, follow these steps for integration:

Add the Script Tag¶

Place the script tag at the bottom of your page above the closing </body> tag; it should not be placed in the <head> section.
If your script is intended for sponsored product ads, ensure that you include the nativeProductFilters as part of your script tag.

Inject content

Example:

<script type="text/javascript">
  window.native = window.native || [];
  window.native.push("AD_UNIT_CODE");
  window.apiKey = "API_KEY";

  (function(d) {
    var script = d.createElement("script");
    script.async = true;
    script.src = "https://s.yimg.com/dy/ads/native.js";
    d.body.appendChild(script);
  })(document);
</script>

Replace content

To use the replace method, you’ll need to add a placeholder element to your page. Use a

<div> tag

and assign the element the class name native-ad-{sectionCode}.

Example:

<div class="native-ad-{sectionCode}"></div>

When the script executes, it will scan the entire document for this element and replace it with the returned ad.

Request multiple sections

To fetch and render more than one section, you need to push the additional section codes into the global sectionCodes array. The example below illustrates this using 3 section codes.

Example:

<script type="text/javascript">
  win.native = win.native || [];

  win.native.push(
    "833b5519-edb7-47c0-88be-1152bcae7870",
    "911b5519-edb7-47c0-822be-1152bcae7811"
  );

  win.apiKey = "P11VS9SY2WQXH7TTFZZZY";

  (function(d) {
    var script = d.createElement("script");
    script.async = true;
    script.src = "https://s.yimg.com/dy/ads/native.js";
    d.body.appendChild(script);
  })(document);
</script>

Step 5: Request an Ad¶

To filter against for any product ads, you can provide a list of product offering attributes. The nativeProductFilters property is an object containing key/value pairs used for filtering on the serving-side.

Ensure that you add the following lines to the ad tag to enable the explicit keyword filtering:

win.nativeProductFilters  = {
  'custom_categories': ['shoes'],
  'sub_category': ['boots']
};

Example:

win.nativeProductFilters  = {
  'search_term': 'adidas mens shoes',
  'min_price': 100,
  'max_price': 1000,
  "color": ["blue"],
  "size": ["7"],
  "custom_categories": ["shoes"],
  "sub_category": ["boots"],
  "gender": ["male"],
  "currency": ["USD"],
  "ratings": ["4.5"],
  "brand": ["adidas"]
};

Passback Handler (Optional)¶

You can run a basic client-side passback using the nativePassbackHandler. The nativePassbackHandler is a function that will only execute when the total number of ads returned is zero.

Add the following lines to the ad tag to enable a basic client-side passback:

win.nativePassbackHandler = function(){
  // add passback logic here
};

Error Handler (Optional)¶

You can control error handling by using the nativeErrorHandler. The nativeErrorHandler is a function that will only execute if the ad request fails.

Add the following lines to the ad tag to enable a error handling for the ad request:

win.nativeErrorHandler = function(){
  // add error handling logic here
};

Make an Ad Unit Request¶

To request the ad units for your page, you’ll need to make a JSONP call. Each page will require an encoded Object containing your filters.

For example:

const filters = {
  search_term: "Mens shoes",
  additional_categories: ["christmas sale", "thanksgiving sale", …]
}

You’ll also need to populate the macros before making the JSONP request, like this:

https://n.gemini.yahoo.com/ssi?pf={encoded_filters}&pb=%7C%7C2023538075%7CSTRM%7C&cc=STRM&ve=2&ui=fp&tt=1&tk={total_ads}&se={section_id}&sd=0&ri={random_uuid}

An example with expanded macros:

https://n.gemini.yahoo.com/ssi?pf=%7B%22search_term%22%3A%22Anchor%20Audio%22%7D&pb=%7C%7C2023538075%7CSTRM%7C&cc=STRM&ve=2&tk=4&se=5301671&sd=0&ri=OEwSVGKLtJ1z35a3Uhl9rAL7S4BT21LK7zYAAbna%22

Tracking Viewability¶

To track viewability, you can use either the hosted version – and receive updates automatically – or you can download the script below and serve it yourself.

https://s.yimg.com/dy/ads/viewability.js

Usage

Once you’ve included the viewability.js script on your page, you can begin tracking any ad container by passing one or more ad responses to the global Gemini method.

Example

Gemini({
  "section": {
    "id": 5413775
  },
  "ads": [{
    "actionUrls": {
      "STATIC_VIEW_3P": ["https://beap.gemini.yahoo.com/action?bv=1.0.0&es=TWkvDIYGIS8F_hpM2LFNVaaoOtd1SRsorcLc346on45jRsyb3emtqhX2yf70keWXg05UEhhR.ZT.m1gjkVnvkysAJRik17RWkxETSpWKG9n9BrurfXk0pMcL.zCTChb.2IFhDXRbIm2j9UGUFvOKIRMQWgwvnQNJDEB85DQLEG1ihCX5Toa8nM3E6SZ9VV.iL.BwfJLNgtub67t4ybp_rcb05bigJ1t6GbQNCpYC0Rajql1IDn2wtJquRNolx9bwpsS65krEGSNHjuTIB05z73mkePELjGuuAgPi8IOgIGaiAdtGCPhhZIKPo4yCJnBBfKfV0tR8RD99CMOAUKjUUxLnGQAuLRs-&vt=$(S_VIEW_TYPE)"],
      "PARTIAL_VIEW": ["https://beap.gemini.yahoo.com/action?bv=1.0.0&es=TWkvDIYGIS8F_hpM2LFNVaaoOtd1SRsorcLc346on45jRsyb3emtqhX2yf70keWXg05UEhhR.ZT.m1gjkVnvkysAJRik17RWkxETSpWKG9n9BrurfXk0pMcL.zCTChb.2IFhDXRbIm2j9UGUFvOKIRMQWgwvnQNJDEB85DQLEG1ihCX5Toa8nM3E6SZ9VV.iL.BwfJLNgtub67t4ybp_rcb05bigJ1t6GbQNCpYC0Rajql1IDn2wtJquRNolx9bwpsS65krEGSNHjuTIB05z73mkePELjGuuAgPi8IOgIGaiAdtGCPhhZIKPo4yCJnBBfKfV0tR8RD99CMOAUKjUUxLnGQAuLRs-"]
    },
    "beacon": "https://beap.gemini.yahoo.com/mbcsc?bv=1.0.0&es=xvZAQckGIS8XC963IFu4iZlOTWPLod8eVdZf0y427vTwOr5.KEXEBgB411PxxgkO90zX.udaAC4GiIeA5NBOLaMGl22ybN7qyGHNAJa4EVJQ9zyrAUk_OfcIkJT0_4uAryRD1P_kFrDyB7PwEMqiQXlkeAz4aE5R2fEbUkI0gOfDCo.w.g_N0PORK0GVw9UI5w2fp93qVn36LuRB90ZGiLyqsO0Z_sBDHS1JlDO1TQ1qpb67Ypzxwtdq__LW3KvDnzySb6ZeiiNYvbA12.D_VlalSUwC73Dwfer7gtfjKrPOj94P0hUl5K5TnrFR7ZB8SPSt4rswP_EK9qVHuDsjivYvTPRErdycfncwJXk0qEpIYdG6XqJkUJ7f7IUxul.7NRZi_AxbW.ozE8Y-&ap=$(AD_POSN)",
    "creativeId": 0,
    "dynamicProductAdId": 35311940826,
    "index": 1,
    "rules": {
      "viewabilityDefStatic": {
        "d": 1,
        "p": 50,
        "c": 1
      },
      "viewabilityDefStatic3P": [{
        "d": 1,
        "p": 100,
        "c": 0,
        "t": 3
      }]
    },
    "tag": "{\"ad_feedback_beacon\":\"https://us.af.beap.bc.yahoo.com/af?bv=1.0.0&bs=(1602vq491(gid$a9b4e820-f556-11e6-9710-008cfa5b3354-7f6562751700,st$1487366324554000,li$0,cr$32717205965,dmn$smartysolarsaver.info,srv$3,exp$1487373524554000,ct$27,v$1.0,adv$1512783,pbid$1,seid$5413776))&r=1487366324554&al=$(AD_FEEDBACK)\",\"advertiser_id\":\"1512783\",\"callToAction\":\"Learn more\",\"clickUrl\":\"https://beap.gemini.yahoo.com/mbclk?bv=1.0.0&es=qFUKq4UGIS89xKPwSDrLWY_so8CghZm_3Z1N5EbOFkynLFlKFctwOOpq6RNPCaqsbzn83Z4UZWRK_rRT_l0Cu5kyPnxi7VTpBaWLhi5nuBW37VY5bpauac7Mf7QaaEw7Gf0iL0P8pFrCu2460nCgEq6EcIwWsGh8f32SB7K3A6WllVWUjplr9eoqCBGv0wsKBB4VVbWhWm69vpoK7FjNhonC1Gjf5iCMKU58HKgdZEyZkgYIM_5NLofby_Zu6M5kezJEvYzKvXeQiEXmbF.DtP_wwpYlrVNEHEfUIntC1LBku3_EN7HpUUUEbEHMAhVFZZxGAZ.Oaht6vvv4_gJcN9E_OBH.s9gpuGNF86SiezHRrXsCAHoQqqtqJRFWhFFjkD0vkkso1SCMe0MHYi4fCurD6UMgueS6yUUDJjyoN6xHiZw0Uw8Ly_1dy7hv7VUqPq8e8zPvajryhxLSBlU..26..6zPzFdgIduasEiQe.T_XQkEfrPARIPrgtStRx6Uk6CEFJxEUd48A.TaUelmFh3nKM1jUjXwbxBGMRpI7kheG4k6LWJbIzSI8eGF0Cjlfp4IuOJ4pGpScJbKhMEctYbFQni5MQVIgjSpYx9eW3J4hH6_h.7jJ9_m4p_aZNnp3Oz.fiAY.XXxsdK.t4ngFHAq4XiEMd.LPGtH2S01xymSSOG5TsQpaPCZGOMmMDQpt3zYaBUghB.AScCRzT34DxnuKXjakT2zIe9C5E1UTCp78g--%26lp=\",\"headline\":\"New Solar Tax Rebates Terrifying Power Companies\",\"hqImage\":\"\",\"hqImageHeight\":-1,\"hqImageWidth\":-1,\"image\":\"http://l.yimg.com/av/curveball/ads/pr/RESIZE/82x82/48328e5e050157afbf5c11daae103fe0.jpeg\",\"imageHeight\":82,\"imageWidth\":82,\"landingUrl\":\"http://www.smartysolarsaver.info/track/ctrack-new.php?adid=32717205965&int=g1-nohq&d=p&n=n&t=new-rebates&i=solar-lady-nohq&c=nahfumy_eadesrosanann-PieceGoodsFabric_the-solarelectric&a=eadesrosanann-PieceGoodsFabric&g=All&age=35-120\",\"objective\":\"VISIT_WEB\",\"origImg\":\"https://s.yimg.com/av/moneyball/ads/1479102313033-9029.jpg?a=eadesrosanann-PieceGoodsFabric_76\",\"origImgHeight\":627,\"origImgWidth\":627,\"secImage\":\"https://s.yimg.com/av/curveball/ads/pr/RESIZE/82x82/48328e5e050157afbf5c11daae103fe0.jpeg\",\"secOrigImg\":\"https://s.yimg.com/av/moneyball/ads/1479102313033-9029.jpg?a=eadesrosanann-PieceGoodsFabric_76\",\"secThumbnailImage\":\"NOT_PROVIDED\",\"source\":\"Smarty Solar Saver\",\"sponsoredByLabel\":\"Sponsored\",\"summary\":\"Why is no one telling homeowners about this? If you own a home and pay more then $49/month for power, you better read this.\",\"thumbnailImage\":\"NOT_PROVIDED\",\"uuid\":\"32717205965\"}"
  }]
});

Essential Reference Documentation¶

The table below points you to the reference documentation that you should read when creating dot pixel tags and product feeds:

Topic	Documentation	Required
Instrument Dot tag	How to instrument Dot tags for dynamic product ads is described in Dot tag Instrumentation.	Yes
Sponsored Product Feed Integration	How to integrate sponsored product feeds is explained in detail in Sponsored Product Feed Integration. Operations include creating, updating and deleting the product feed into Verizon Media Native.	Yes

Learn More¶

For more information about supported third-party Tag managers, describing the steps required to set up and deploy Verizon Media Dot tags, refer to

For information about Yahoo App Publishing, which describes ad unit setup, refer to the documentation for Flurry Publishers - Monetization. In addition to Flurry Analytics, you’ll find tools for Publishers who wish to monetize with ads from Yahoo App Publishing. Note that you’ll need to set up a Flurry account.

Document History¶

Date	Release
3-11-2020	Document now available externally for Verizon Media partners and developers, with updates and additions.
8-30-2019	v1.0 release of document with detailed information about steps for integration and onboarding for select Verizon Media partners and developers. Companion document also created for Sponsored Product Feed Integration
6-06-2019	Updated release of document for select Verizon Media partners and developers. Updated code snippets for injecting content for the script tag, product filters, and requesting multiple sections. Removed JSON example response. Changed terminology: Native Feed Ads to Dynamic Product Ads.
3-20-2019	First release of document for select Verizon Media partners and developers