yahoo partner ads technical onboarding document

Yahoo Partner Ads

Technical Onboarding Document

05/31/2018. v12.6

-1-

Copyright © 2016 Yahoo. All Rights Reserved. Confidential and Proprietary.

Table of Contents

Preface Support Legal Notice

Revision History Yahoo Partner Ads Overview

Definitions of Entities Product Features Search Ad Creative with Ad Extensions YPA Online Tool

YPA Tool - Technical Setup Instructions YPA Functional Screens

Step 1: Create Site Group(s) Step 2: Create Site(s) Step 3: Create JS AD Tag Step 4: Export JavaScript Ad Tag Code Step 5: Apply Traffic Protection Blocks and/or Caps

Create a Traffic Protection rule Block sites Block IPs

Traffic Protection Rules IP Block Site Block Capping Rules

Domains and Subdomains Partner JavaScript Ad Tag

Callback Function Pagination of Ad/Algo results Dynamic Parameters Ad Tag Level Options Ad/Algo Unit Level Options

Ad/Algo Unit ‘n’ Structural Options Ad/Algo Unit ‘n’ Container Formatting Options Ad Unit ‘n’ Label Formatting Options Ad/Algo Unit ‘n’ Ad Element Formatting Options Ad Unit ‘n’ Ad Extensions Formatting Options Ad Unit ‘n’ Image Ad Formatting Options

Sample Ad Tag Keyword Extraction Market Identification

Ad label switch based on Market Identification Official Site Badge switch based on Market Identification

Beaconing Search Beacon Click Beacon

Dynamic CSS Support for Third Party Image Providers for Image in Ads Ad Extension

-2-


A/B Experimentation Framework Appendix

Table 1: Supported languages for Ad labels Table 2: Official Site Badge text for supported languages

-3-


Preface

The purpose of this document is to assist the Syndication Partners in understanding the Yahoo Partner Ads (YPA) online management tool. This document and the information contained herein are Yahoo Confidential Information and subject to confidentiality restrictions set forth in the non-disclosure agreement between you and Yahoo.

Support

If you have any questions, please contact your Partner Manager at Yahoo.

Legal Notice

Access and use of this document and the information contained herein is governed by and subject to a license agreement and to nondisclosure provisions contained therein or in a separate non-disclosure agreement. Without fully executing such agreement(s), your access to, and use of the information contained in this document is strictly prohibited. Yahoo®, the Yahoo logo, and other Yahoo related product and service names are trade names and/or registered trademarks of Yahoo Inc.

-4-


Revision History

Date Version Content Changed

07/24/2014 1.0 New document

07/31/2014 2.0 The following sections were added: ● Traffic Protection Rules ● Domains and Subdomains

10/30/2014 3.0 The following sections were added: ● Dynamic Parameters ● Support for Third Party Image Providers for Image in

Ads Ad Extension

The following sections were modified: ● Beaconing

○ type tag added to search beacons ● Image In Ads - Ad Extension

04/21/2015 4.0 The following sections were added: ● Ad label switch based on Market Identification ● Appendix

The following sections were modified:

● Beaconing ● Ad Unit ‘n’ Label Formatting Options

05/28/2015 5.0 The following sections were modified: ● Updated UI how-to screenshots (various) ● Added more examples under Keyword Extraction

06/18/2015 6.0 The following features were added in Product Features: ● Enhanced Site Links ● Smart Annotations

Related changes on Dynamic Parameters

09/14/2015 7.0 The following features were added in Product Features: ● Algorithmic Web Results ● Official Site Badge ● Call Extensions ● Support for Multiple Encoding

Related changes on Dynamic Parameter The following sections were modified:

● Beaconing ● Dynamic CSS

The following feature was removed in Product Features:

● Content Match backfill

-5-


02/04/2016 8.0 The following sections were modified: ● Update specifications for type tag under Ad Tag Level

Options The following section was added: New Product Feature

● A/B Experimentation Framework

02/25/2016 9.0 The following section was added: New Product Feature ● Pagination of Ad/Algo results

04/07/2016 10.0 Added support for slot level beacon parameters. ● clickBeacon/serveBeacon

04/22/2016 10.1 Minor bug fixes ● Algo onHover ● Color hex code case insensitive.

04/28/2016 11.0 The following section was added: New Product Feature ● clickBeaconServer ● serveBeaconServer

10/11/2016 12.0 Added support for “target=<option>”: click-behavior on ads/algo.

● ypaClickTarget

05/08/2017 12.1 Remove Support for adult ads. YPA will serve only clean ads.

11/29/2017 12.2 The following features were added in Product Features: ● Callout Extension ● Review Extension ● 4th Line Annotation

Related changes on Dynamic Parameter

04/24/2018 12.5 The following features were added in Product Features: ● Security Badge Extension ● Brand Annotation ● Top Ads Annotation

Related changes on Dynamic Parameter. Added missing TemplateOptions configurations for: Review Extension, Callout Extension, 4th Line Annotation

05/31/2018 12.6 Adding GDPR documentation and example usage for gdpr and euconsent parameters

-6-


-7-


Yahoo Partner Ads Overview

Yahoo Partner Ads (YPA) is a client side Javascript Solution which provides quality search ads and algo results for partners with owned and operated sites, who manage their own search engine results pages (SERPs). YPA can be added to any partner web page across PC, tablet, and mobile devices and offers an online management UI for you to manage your search experience.

Definitions of Entities

Yahoo Partner Ads includes the following entities:

Entity Definition

Publisher Top level entity for Yahoo Partner Ads. This is the name of the Publisher.

Site Group Second level entity for Yahoo Partner Ads. This is a grouping of sites, typically representing a vertical (sports), a sub-syndicate, or a grouping of properties.

Site Third level entity for Yahoo Partner Ads. This is an individual domain (yahoo.com) where Yahoo Partner Ads will appear.

JS Ad Tag This is the Yahoo Partner Ads JS code that partners will place on their site to get ads and algo from Yahoo. A single JS Ad Tag will support multiple units on the page. The same ad tag can be used across desktop, mobile, and tablet.

Ad / Algo Unit A block of ads / algo on the page. A page can have multiple units.

Source Tag This is a required reporting tag provided by Yahoo for the partner to use in the JS Ad Tag setup. Reporting is done at the Source Tag level.

Type Tag This is an optional reporting tag that the partner may use in the JS Ad Ad Call. The tag is defined and passed by the partner.

YPA Online Tool This is the online YPA management tool for Partners to manage their JavaScript search ads implementations.

-8-


Product Features

Yahoo Partner Ads includes the following product features:

Feature Area Description

Search Ads Ads Yahoo Sponsored Search Ads

Algorithmic Web Results

Algo Yahoo Algorithmic Web Results

3rd Party Ad Serving

Ads Call-back functionality to partner when zero ads are returned, so partner can make ad request to a 3rd party

Multiple Units Ads and Algo Ability for partner to have multiple ads and algo units on the page with a single JS Ad Tag

Multi-Device Ads and Algo Single JS Ad Tag will work across all device types (mobile, tablet, and desktop)

Multiple Encoding Ads and Algo Support multiple input and output text encodings.

Creative Formatting

Ad Creative Ability for partner to apply basic formatting to tailor the look and feel of the ads and algo to the partner’s site

Dynamic CSS Ad Creative Ability for partner to apply their own CSS for the formatting of the JS Ad Tag. Partner CSS will need to conform to Yahoo Partner Ads HTML Classes.

3rd Party Images Ad Features Ability to get images for your Ads from 3rd party of your choice.

A/B Testing Ad Features YPA offers the capability of running A/B tests. This provides an opportunity for you to easily set up and run various experiments.

Official Site Badge Ad Extension The Official Site Badge highlights branded advertisers with a badge icon to the right of the ad letting users know that is the official site for their branded query.

Favicon Ad Extension A Favicon is a graphical image (usually the logo) that is displayed to highlight the “perfect” ad for branded or navigational queries.

-9-


Merchant Ratings Ad Extension Merchant Ratings are star ratings plus number of reviews the advertiser/merchant has.

Note: The feature is not available for APAC and LATAM regions.

Site Links Ad Extension Sitelink extensions are additional text plus URL pairs (up to six) that provide links to an advertiser’s website. These links provide more specific access points into the advertiser’s website to drive searchers to exactly the information they are looking to find.

Enhanced Site Links

Ad Extension Two line description for each site link in the Ad.

Local Ads Ad Extension Local Ads are ads with extended local attributes for users who are located near advertiser’s business location inside the targeted area.

-10-


Note: The feature is not available for APAC and LATAM regions.

Long Ad Title Ad Extension Long Ad Title (LAT) is a feature that displays longer ad titles. Long Ad Titles will append the domain name or part of the description to the original ad title.

Image in Ads Ad Extension Images are shown next to the ads to increase the brand visibility of the ad.

Smart Annotations Ad Extension

Single line of non-clickable text below the Description line, based on landing page data.

Call Extensions Ad Extension Connect advertisers and users directly from the ad via a phone call.

-11-


Callout Extensions Ad Extension Support for advertisers to highlight their unique product offerings and deals.

Review Extension Ad Extension Include a review of the product from a trusted source along with a link to the source.

4th Line Annotation

Ad Extension Include a second description line that will contain the best annotation for the ad.

Brand Annotation Ad Extension Include brand name in the ad.

Security Badge Annotation

Ad Extension Display name of 3rd party security provider that protects site referenced in the ad.

Top Ad Annotation Ad Extension Includes number of user visits to a particular domain.

-12-


Click Beaconing Reporting Ability for partner to get click data by providing Partner Click Server URL to Yahoo.

Search Beaconing Reporting Ability for partner to get search data by providing Partner Search Server URL to Yahoo.

IP Block List Traffic Protection Ability for partner to upload a list of IPs they want to block.

Site Block List Traffic Protection Ability for partner to upload a list of sites they want to block.

Capping Rules Traffic Protection ● Ability to set capping rules at site group and/or site level. ● Capping rules can be applied on: Searches, Clicks,

Revenue, CTR ● Capping rules are applied daily, at UTC time zone. ● Once max limit is reached, no ads will be returned for

remainder of day ● If there are overlapping rules, the stricter rule will be

applied

Search Ad Creative with Ad Extensions

The following examples show individual ad listings with multiple ad extensions:

-13-


YPA Online Tool

Partners will use the YPA online tool to setup and manage their JavaScript implementations. Partners will create and manage Site Groups, Sites, and JS Ad Tags in this tool. Additionally, partners will have the ability to input Traffic Protection Controls and Blocks for their business. Partners will be provided with credentials to access the YPA online tool (partnerads.yahoo.com) by their Yahoo Partner Manager.

-14-


YPA Tool - Technical Setup Instructions

This section includes process details for creating a new implementation in YPA.

Step Instructions Notes

1 Create New Site Group(s) in YPA Site Group = Sub-Syndicate, Property, or Group of Properties

2 Create Site(s) under your newly created Site Group(s)

● Sites = Domain where ads and algo will appear ● Sites must be input under Site Groups for ad

serving ● Can use bulk upload for large number of sites

3 Create JavaScript Ad Tags for your new Site Group(s).

● Configure settings for the JS Ad Tag (beacons, source tag, adult ads, etc.)

● Configure settings for each Ads & Algo Unit(s) (position, width, count, extensions, layout, etc.)

● May create multiple units for an Ad Tag ● Ad Tags are across devices ● Can clone ad tags for ease of entry ● Can create templates for ad tags

4 Export JavaScript Ad Tag code for your new Site Group(s)

● Download the ad tag code from the YPA UI

5 Apply any Traffic Protection Blocks and/or Capping Rules to your new implementation(s)

● Block lists are at Publisher level ● Capping rules can be at Domain and/or group of

Domains

-15-


YPA Functional Screens

Step 1: Create Site Group(s)

The following instructions explain how to create new site groups.

1. On the Site Groups page, click Create a Site Group.

2. Enter/select the options for your new site group, and then click Done.

-16-


Step 2: Create Site(s)

The following instructions explain how to add sites to a site group.

1. On the Site Groups page, select the Site Group.

2. Click Sites, and then click Add Sites.

3. Enter/select the options for your new sites, and then click Done.

-17-


Step 3: Create JS AD Tag

The following instructions explain how to create an ad tag.

1. On the Site Groups page, select the site group.

2. Click Ad Tags, and then click Create an Ad Tag.

3. Enter/select the options for each ad unit, and then click Create ad tag.

-18-


-19-


Step 4: Export JavaScript Ad Tag Code

The following instructions explain how to export JavaScript ad tag code.

1. On the Site Groups page, select the site group.

2. Click Ad Tags, select the ad tag name, and then click the Get JS Code icon.

3. You can copy the JavaScript code or you can download it by clicking Download JS code.

4. When you are finished, click Done.

-20-


Step 5: Apply Traffic Protection Blocks and/or Caps

The following instructions explain how to apply traffic protection blocks/caps.

Create a Traffic Protection rule

1. On the Traffic Protection page, select Manage Rules from the drop-down menu.

2. Click Create a Rule.

-21-


3. Enter/select the rule options, and then click Create Rule.

-22-


Block sites

1. On the Traffic Protection page, select Block Sites from the drop-down menu.

2. Enter or upload the site addresses you want to disable, and then click Done.

-23-


Block IPs

1. On the Traffic Protection page, select Block IPs from the drop-down menu.

2. Enter or upload the site addresses you want to block, and then click Done.

-24-


Traffic Protection Rules

You can control traffic in your network via the following available rules. These rules are only applied to your traffic. All rules may take an hour to get reflected.

IP Block

You can upload a list of IP addresses. Any traffic from this list will be blocked and ads will not be served. Both individual IP addresses and ranges in the CIDR format are supported. E.g. 13.1.23.45

10.10.1.67/24

Site Block

You can upload a list of sites to be blocked. Any traffic from this list of domains will be blocked and ads & algo will not be served. These sites must belong to your list of approved and registered sites.

Capping Rules

You can cap sites and site groups on four criteria:

● Searches ● Clicks ● Revenue ● CTR

You can specify a threshold for one or more criterias for any given site(s) or site group. These thresholds should be at a daily level, UTC Time zone. Rules are evaluated and applied every hour on the aggregated data for that day until that hour. If any threshold is crossed, that site(s) or site group will be capped for rest of the day. Once capped no ads & algo will be served for the site(s) or site group. At the end of the day these rules are reset and all capped sites or site groups will be uncapped. For site group rules, data is aggregated for all sites in that site group and then the rule is evaluated. If the defined threshold is crossed, all sites in that site group will be capped. Rules are based on a UTC day.

-25-


Domains and Subdomains

You’ll be uploading domains and subdomains in the YPA tool for site registration and traffic protection rules. All domains (and subdomains) will be implicitly wildcarded to include all further subdomain levels of the domain. For Traffic protection rules, all subdomain levels will be aggregated and then the rule will be applied. Examples:

● Registered site: example.com Traffic from example.com, anysubdomain.example.com and onemorelevel.anysubdomain.example.com will be served.

● Traffic Protection rule created for: example.com

Data is aggregated for example.com, anysubdomain.example.com and onemorelevel.anysubdomain.example.com and then the rule is applied on the aggregated data.

● Registered site: mysubdomain.example.com

Traffic from mysubdomain.example.com and onemorelevel.mysubdomain.example.com will be served. However, traffic from example.com, othersubdomain.example.com will not be served.

● Traffic Protection rule created for: mysubdomain.example.com

Data is aggregated for mysubdomain.example.com and onemorelevel.mysubdomain.example.com and then the rule is applied on the aggregated data.

You can only create traffic protection rules for sites that are registered. If you have registered example.com, you cannot create a traffic protection rule for mysubdomain.example.com. If you want to manage traffic on multiple subdomains separately, you should register each one separately.

-26-


GDPR Support for EU

In response to the EU General Data Protection Regulation (Regulation 2016/679) (“GDPR”) Oath is adopting the IAB Europe Transparency and Consent Framework and is listed as a Vendor on the framework’s Global Vendor list. We strongly encourage our YPA Search Partners to use this industry framework as part of their compliance efforts. For Oath Search Partners on the YPA platform, support for EU consent is provided with two additional ad tag parameters: “gdpr ” and “euconsent ”. Information on the IAB Europe Transparency and Consent Framework and Technical Specification on the IAB CMP JS API can be found at http://advertisingconsent.eu/. More information about the cookie is located in “Tech specification - Cookie and Vendor List Format v1.0a”. For details on implementing GDPR support within YPA, reference the “gdpr ” and “euconsent ” parameter documentation in the “Partner Javasciprt Ad Tag” section below.

-27-


http://advertisingconsent.eu/

Partner JavaScript Ad Tag

Once you have created an ad tag, you can export the JavaScript ad tag code and implement it on your page. The code snippet page includes instructions that will help you add the code to your page. Additional instructions:

● You should change the name(s) of the div(s) in the code snippet to the actual div names on your page, where you want the ads and algo to be inserted.

● This JavaScript should be implemented directly on a page and not inside of an IFRAME. ● You should only deploy the JavaScript code on the site that has been approved and uploaded using the

YPA tool. Ads and Algo will not be served on the sites that are not registered in the YPA tool.

Callback Function

When YPA does not return any ads/algo, YPA provides the ability for you to call for content/ads from any marketplace outside of Yahoo. Ads/Algo are not returned in the following cases:

● When the site from which the ad call is triggered is unregistered in the YPA system. ● When there is no coverage in case of a valid ad call (call originated from a registered site, passed all

other checks, and an ad call was made to the ad system). When there are no ads or algo results(no coverage), YPA will call a function specified by the ypaOnNoAd ad tag param for the ad slot which did not have ads/algo results. ypaOnNoAd : <Your callback function name> Two parameters will be passed to your callback function:

1. errObj

○ errObj.URL_UNREGISTERED This is set to 1 only in case of unregistered URL. ○ errObj.NO_COVERAGE This is set to 1 in case of no ads or zero algo results.

2. slotInfo

○ slotInfo.ypaAdSlotId Name of the ad/algo unit. ○ slotInfo.ypaAdDivId Name of the div associated to the ad/algo unit. ○ slotInfo.ypaAdWidth Width of the ad/algo unit.

Your callback function signature should be the following:

<script>

function <your callback function name> ( errObj, slotInfo )

{

…

}

</script>

-28-


You can specify a different callback function for each unit. If some units get back ads/algo results and some don't, then the callback function will only be called for the units for which ads/algo results were not served.

Pagination of Algo and Ad results

YPA provides the ability to paginate the ads/algo results. This helps you to show ad/algo results as pages. This can be done by setting the ‘ypaPageCount’ value in the ad tag as follows: <script type="text/javascript">

window.ypaAds.insertMultiAd({

ypaPubParams : {

query : "addidas shoes",

location : "Burbank, CA",

inputCharEnc : "utf8",

outputCharEnc : "utf8"

},

ypaAdConfig : "000000005",

ypaAdTypeTag : "typeTag",

ypaPageCount : "2", //indicates the current page number

ypaAdSlotInfo : [

{

ypaAdSlotId : "south",

ypaAdDivId : "ypaAdWrapper-MainSouth",

ypaAdWidth : "300",

ypaAdHeight : "100",

},

{

ypaAdSlotId : "northalgo",

ypaAdDivId : "ypaAdWrapper-MainAlgoNorth",

ypaAdWidth : "300",


}

]

}); </script>

You have to track the user’s navigation across pages and track page count. Every time the user navigates to a new page, you have to invoke insertMultiAd() after populating “ypaPageCount” appropriately. All ad/algo units on the page will move to the appropriate set of results based on the ypaPageCount. You cannot choose to paginate specific ad/algo units on a page. For example, if the page is configured to show an ad unit with 2 ads and an algo unit with 6 results, ypaPageCount=3 will show ads 5-6 and algo results 13-18. Valid values for “ypaPageCount” are between 1 and 9999, although the actual number of pages of results available depends upon the keyword.

-29-


Dynamic Parameters

1. An ad tag has to be created via the YPA UI before using any of the parameters below to configure its behavior.

2. You cannot add more Ad/Algo units than what is configured for the ad tag in the UI. You can however, choose to show less Ad/Algo units by removing the ad slots that you do not want to display.

3. Ad tag and Ad/Algo unit names cannot be overridden. 4. You can specify a different behavior for Mobile and Desktop. Depending on the user agent, appropriate

settings will be used. Tablet will follow Desktop configurations. 5. Each parameter should be added to the appropriate hash. Most of the parameters are in nested

hashes. The Ad Tag Level Options table shows the hash hierarchy. For an example, you can refer to Sample Ad Tag.

6. If a dynamic parameter is not passed or cannot be read by the system, then the value used is based on:

a. The value available on the YPA UI against that ad config OR

b. YPA system default value 7. The ad formatting options shall be applied in the following order of priority:

a. From dynamic parameters b. From CSS file (if specified) c. From ad tag values

8. All parameters and values are case sensitive. 9. The values should not be enclosed in quotes unless they are strings. In the tables below, quotes have

been used to highlight the values. Please refer to Sample Ad Tag for the usage of the values.

Ad Tag Level Options

The following parameters control the behavior of the entire ad tag:

Parameter YPA UI Label Description/Notes Allowed Values

ypaAdTypeTag ● There is no equivalent of this in the YPA UI.

● This parameter can be used to tag traffic and run reports on that traffic.

● The default type tag value of “meta” will be used. ● The allowed characters in type tag are a-z A-Z 0-9 ,(comma) -(hyphen) and _(underscore). Type tags can be up to 200 characters long. If you are running A/B testing experiments on YPA, the type tag will be truncated to 100 characters and with the last 100 characters reserved for experiment related information.

-30-


ypaAdTrafficType Ad Tag mode ● Same meaning as in YPA UI ● The only allowed value is “test”.

ypaPageCount Page Count ● There is no equivalent of this in the YPA UI.

● This parameter can be used to set the page count.

● This should be an integer between 1 and 9999. Default value is 1. See Pagination of Algo and Ad results for more details.

ypaClickTarget ● There is no equivalent of this in the YPA UI.

● This parameter can be used to control the behavior of click on ads/algo

● The value can be _self,_parent,_blank

● Default is _blank.

query Hash: ypaPubParams

● There is no equivalent of this in the YPA UI.

● This parameter is used to pass the user query dynamically to the YPA system.

● If this parameter is not used or empty, YPA will fall back to extracting the search term from the URL parameters. See Keyword Extraction for more details.

location Hash: ypaPubParams


● This parameter enables search scenarios like local search, where location needs to be sent along with the query term. The location can be sent in this parameter.

● The value can be in the form of a five digit zip code or a city, state format.

inputCharEnc Hash: ypaPubParams


● This parameter allows you to specify the encoding for the ‘query’ and ‘location’ parameters

● The value can ‘big5’ or ‘utf8’

● Default is utf8

outputCharEnc Hash: ypaPubParams


● This parameter specifies the encoding for ads/algo returned by YPA

● The value can ‘big5’ or ‘utf8’

● Default is utf8

euconsent Hash: ypaPubParams

● Specifies the user’s level of consent

● Information on the IAB Europe Transparency and Consent

● Base64 encoded consent string in IAB standard format.

-31-


Framework and Technical Specification on the IAB CMP JS API can be found at http://advertisingconsent.eu/. More information about the cookie is located in “Tech specification - Cookie and Vendor List Format v1.0a”.

● If gdpr=0 (see below), this is not expected.

gdpr Hash: ypaPubParams

● Indicates if the user and/or partner’s website would trigger GDPR for this request.

● String value of 0 or 1. 1 Indicates the user is in the EU or the website generally targets EU users.

SrcTag Hash: ypaAdTagOptions: SponsoredSearch: Mobile

Mobile SS Source tag

● This gives you the option to pass in a source tag that will be used for mobile traffic for Sponsored Search ads.

● YPA will detect the device type based on the user agent and use the appropriate source tag based on the logic in the table below:

User agent

Dynamic source tag passed

Source tag used

Desktop/ Tablet

Yes/No SS Source Tag configured on YPA UI for this ad tag

Mobile Yes The source tag passed dynamically in the ad tag

Mobile No Mobile SS Source Tag configured on YPA UI for this ad tag or SS Source Tag from YPAUI if Mobile Source Tag is not specified on YPAUI

● Mobile SS Source tag configured in YPA UI against the ad tag will be used by default if the system is unable to read the dynamic source tag for any reason.

● All your source tags have to be registered in Yahoo systems prior to use. Please consult your Partner Manager for Source Tags.

serveBeaconServer Hash: ypaAdTagOption

serveBeaconServer URL

● Same meaning as in YPA UI ● Overwrites the serve beacon set

on UI. ● Enables firing of serve beacon.

This takes serve beacon server name and parameters.

-32-


http://advertisingconsent.eu/

● myservebeaconserver.com/?a=xyz&b=456&d=001

● myservebeaconserver.com

clickBeaconServer Hash: ypaAdTagOption

clickBeaconServer URL

● Same meaning as in YPA UI ● Overwrites the click beacon set

on UI. ● Enables firing of click beacon.

This takes click beacon server name and parameters.

● myclickbeaconserver.com/?a=xyz&b=456&d=001

● myclickbeaconserver.com

serveBeacon Hash: ypaAdTagOptions

Serve Beacon URL

● Parameters and values for serve beacon

● The server URL will be picked from the serveBeaconServer/UI.

● E.g: Value in serveBeaconServer/UI is “myserver.com?a=123&b=456”. Value passed via serveBeacon parameter is “a=xyz&d=001” then the beacon emitted will be “myserver.com?a=xyz&b=456&d=001&<additional params added by YPA>)

● The input value will be a string of key value pairs. This key value pair mapping shall be appended to the URL that has been input in the serveBeaconServer/YPA UI.

● If the parameter name is already present in the serveBeaconServer/UI, then the value passed dynamically will be used.

● The default value of a parameter is the value specified in the YPA UI against the ad tag.

● This parameter is sent over ad call and its length should be such that the ad call does not exceed the browser limit on url length.YPA does not enforce any limit on its length.

clickBeacon Hash: ypaAdTagOptions

Click Beacon URL parameters


● The server URL will be picked from the clickBeaconServer/UI.

● E.g: Value in clickBeaconServer/UI is “myserver.com?a=123&b=456”. Value passed via clickBeacon parameter is “a=xyz&d=001” then the beacon emitted will be

● The input value will be a string of key value pairs. This key value pair mapping will be appended to the URL that has been input in the clickBeaconServer/UI.

● If the parameter name is already present in the clickBeaconServer/UI, then

-33-


“myserver.com?a=xyz&b=456&d=001&<additional params added by YPA>)

the value passed dynamically will be used.


● This parameter is sent over ad call and its length should be such that the ad call does not exceed the browser limit on url length.YPA does not enforce any limit on length.

adultFilter Hash: ypaAdTagOptions

Adult ads ● Same meaning as in YPA UI ● The allowed values are true or false.

● true means allow adult ads ● false means do not allow

adult ads ● adultFilter is set to False

and is not overridable.

Ad/Algo Unit Level Options

These parameters control the behavior of the individual ad unit.

Ad/Algo Unit ‘n’ Structural Options

The following options are for the ad/algo unit as a whole:

Parameter YPA UI Label Description/Notes Allowed Values

ypaAdWidth Hash: ypaAdSlotInfo

Maximum width ● Same meaning as in YPA UI ● This should be an integer between 200-1000.

● The default value is the value specified in the YPA UI against this ad tag for this ad unit.

ypaOnNoAd Hash: ypaAdSlotInfo

● There is no equivalent of this in the UI. See Callback Function for more details.

clickBeacon Hash: ypaAdSlotInfo

Click Beacon URL parameters


● This overwrites the value set at the AdTag level

● Length of this parameter should be such that the ad call does not exceed the browser limit on url length.YPA does not enforce any limit on length.

-34-


ypaAdTagOptions:clickBeacon.

● The server URL will be picked from the clickBeaconServer/UI.

● E.g: Value in clickBeaconServer/UI is “myserver.com?a=123&b=456”. Value passed via clickBeacon parameter is “a=xyz&d=001” then the beacon emitted will be “myserver.com?a=xyz&b=456&d=001&<additional params added by YPA>)

● The input value will be a string of key value pairs. This key value pair mapping will be appended to the URL that has been input in the clickBeaconServer/YPA UI.

● If the parameter name is already present in the clickBeaconServer/YPA UI, then the value passed dynamically will be used.


serveBeacon Hash: ypaAdSlotInfo

Serve Beacon URL parameters

● Parameters and values for serve beacon.

● This overwrites the value set at the AdTag level ypaAdTagOptions:serveBeacon.

● The server URL will be picked from the serveBeaconServer/UI.

● E.g: Value in serveBeaconServer/UI is “myserver.com?a=123&b=456”. Value passed via serveBeacon parameter is “a=xyz&d=001” then the beacon emitted will be “myserver.com?a=xyz&b=456&d=001&<additional params added by YPA>)

● Length of this parameter should be such that the ad call does not exceed the browser limit on url length. YPA does not enforce any limit on length.

● The input value will be a string of key value pairs. This key value pair mapping will be appended to the URL that has been input in the serveBeaconServer/YPA UI.

● If the parameter name is already present in the serveBeaconServer/YPA UI, then the value passed dynamically will be used.


AdRange Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

● This is different than the YPA UI behavior.

● This parameter will capture the ad start rank and the ad end rank to be shown on desktop/tablet/mobile.

● This should be a range between “1-10”.

● The default value is the value specified in the YPA UI against this ad tag for this ad unit. The ad rank will move down from each ad unit unless the mirroring option is used in the UI.

-35-


Favicon Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Favicons ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)

● The allowed values are true or false.

● true means show favicon ● false means do not show

favicon ● The default value is the value

specified in the YPA UI against this ad tag for this ad unit.

LocalAds Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Local Ads ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means show local ads ● false means do not show local

ads ● The default value is the value


Lat Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Long Ad Title ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means use Long Ad Title ● false means do not use Long

Ad Title ● The default value is the value


SiteLink Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Site Links ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means show site links ● false means do not show site

links ● The default value is the value


MerchantRating Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Merchant Ratings

● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means show merchant ratings

● false means do not show merchant ratings


-36-


ImageInAds Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Images in Ads ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means show images in ads

● false means do not show images in ads


EnhancedSiteLink Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Enhanced Site Links


for Algo)


● true means show Enhanced Site Links

● false means do not show Enhanced Site Links


SmartAnnotations Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Smart Annotations


for Algo)


● true means show Smart Annotations

● false means do not show Smart Annotations


OfficialSiteBadge Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Official Site Badge


for Algo)


● true means show Official Site Badge

● false means do not show Official Site Badge


CallExtension Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop:

Call Extension ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)


● true means show Call Extensions

● false means do not show Call Extensions


-37-


CalloutExtension Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

Callout Extension


for Algo)


● true means show Callout Extensions

● false means do not show Callout Extensions


ReviewExtension Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

Review Extension


for Algo)


● true means show Review Extension

● false means do not show Review Extension


FourthLine Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

Fourth Line Annotation


for Algo)


● true means show Extension ● false means do not show

Extension ● The default value is the value


BrandAnnotation Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

Brands Annotation


for Algo)





SecurityBadge Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

Security Badge Annotation


for Algo)





TopAdAnnotation

Top Ad Annotation

● Same meaning as in YPA UI ● The allowed values are true or false.

-38-


Hash: ypaAdSlotInfo: ypaSlotOptions: AdOptions: Mobile/DeskTop

● Only for Ads (not available for Algo)




Ad/Algo Unit ‘n’ Container Formatting Options

The following formatting options will apply to the entire ad/algo unit container:

Parameter YPA Label Description/Notes Allowed Values

backgroundColor Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

Background Color

● Same meaning as in YPA UI ● The allowed value is a color value in hex.

● The default value is the value specified in the YPA UI against this ad tag for this ad/algo unit.

borderColor Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

Border Color ● Same meaning as in YPA UI ● The allowed value is a color value in hex.


lineSpacing Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit


● This parameter will capture the vertical spacing between title/description/click URL. This height will include the height used by the text of the respective element.

● The allowed value is a decimal between 8 – 25.

● The decimal will be stripped to one place before being used.

● There is no need to add “px” or any other text with this value.

● The default value is 17.

adSpacing Hash: ypaAdSlotInfo:



● The decimal shall be stripped to one place before being used.

-39-


ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

● This parameter will capture the vertical spacing between two ads.

● There is no need to add “px” or any other text with this value.

● The default value is the system default.

font Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

Font Family ● Same meaning as in YPA UI ● This should be a valid font family.


● If an incorrect font family is passed, the behavior is browser dependent.

adLayout Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

Ad Layout ● Same meaning as in YPA UI ● Only for Ads (not available

for Algo)

● The allowed values are 1,2,3 to show ads in one line, two lines or three lines respectively.


urlAboveDescription Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

URL above description

● Same meaning as in YPA UI ● The allowed values are true or false.

● true means show URL before description

● false means do not show URL before description


cssLink Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnit

Custom CSS Link

● Same meaning as in YPA UI ● Should be a maximum of 1000 characters

● The input value will be a URL which will have the partner server name and some optional parameters as desired by the partner.


● Must use https link or it will be blocked by the browser.

-40-


● Any value with a “http” prefix will be changed to https.

-41-


Ad Unit ‘n’ Label Formatting Options

The following formatting options will apply to the ad unit label (not applicable for algo):


position Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnitLabel

Ad Unit Label Position

● Same meaning as in YPA UI ● The allowed values are: a. “Top Left” b. “Top Right” c. “Bottom Left” d. “Bottom Right”

● The default value is “Top Left”.

fontsize Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnitLabel

Ad unit Label Font


● This captures the font size of the ad unit label.




color Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnitLabel

Ad unit Label Color


● This captures the color of the ad unit label.

● The allowed value is a color value in hex.

● Default value is “#BBB”.

labelId Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: AdUnitLabel

Ad unit Label text

● Similar functionality as YPA UI.

● You can choose the language and text of your Ad Label

● NOTE: Your choice of the Ad label text may not be always used. It’ll depend on the market determination logic. See Market Identification section for more details.

● Allowed value is a number which maps to a combination of language and ad label text

● See Appendix Table 1

-42-


Ad/Algo Unit ‘n’ Ad Element Formatting Options

The following formatting options will apply to Title, Description, and Display URL for all ads in the ad/algo unit:


fontsize Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL:

Title/Description/Display URL font size

● Same meaning as in YPA UI ● The allowed value is a decimal between 8 – 18.


● The default is the respective value for title/description and click URL specified in the YPA UI for this ad tag for this ad/algo unit.

color Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL:

Title/Description/Display URL color

● Same meaning as in YPA UI ● The allowed value is a color value in hex.

● Default is the respective value for title/description and click URL specified in the YPA UI for this ad tag for this ad/algo unit.

underline Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL:

Underline Title ● The current UI only gives an option to underline the title.

● This provides additional capability to underline description and display URL.


● true means underline ● false means do not underline ● The default value for title is

the value specified in the YPA UI for this ad tag for this ad/algo unit.

● The default value for description and display URL is false.

bold Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL:

Bold Title ● The current UI only gives an option to make the title bold.

● This provides additional capability to bold the description and display URL.


● true means bold ● false means do not bold ● The default value for title is

the value specified in the YPA UI for this ad tag for this ad/algo unit.

-43-


● The default value for description and display URL is false.

color Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL: onHover:


● This parameter will capture the color the of title/description/click URL on mouseover.

● Color specified on title is applied to background color of Official Site Badge too.


● If an incorrect value is passed then this parameter is ignored.

●

underline Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: Title/Description/URL: onHover:


● This parameter will capture whether or not to underline the title/description/click URL on mouseover.


● true means underline title on hover

● false means do not underline title on hover

● If an incorrect value is passed then this parameter is ignored.

● The default value is false.

-44-


Ad Unit ‘n’ Ad Extensions Formatting Options

The following formatting options will apply to Local Ads, Merchant Ratings, Site Links, Enhanced Site Links, Smart Annotations, Call Extensions and Official Site Badge for all ads in the ad unit (not applicable for algo):


fontsize Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/CallExtension/OfficialSiteBadge/CalloutExtension/FourthLine/ReviewExtension/BrandAnnotation/SecurityBadge/TopAdAnnotation:


● This parameter will capture the font size of the Local Ads/Merchant Ratings/Site Links text.




color Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/CallExtension/OfficialSiteBadge/CalloutExtension/FourthLine/ReviewExtension/BrandAnnotation/SecurityBadge/TopAdAnnotation:


● This parameter will capture the color of the Local Ads/Merchant Ratings/Site Links text.


● The default value is “#00E”.

underline Hash: ypaAdSlotInfo: ypaSlotOptions:


● This parameter will capture whether or not to underline


● true means underline ● false means do not underline ● The default value is false.

-45-


TemplateOptions: Mobile/DeskTop: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/CallExtension/CalloutExtension/FourthLine/ReviewExtension/BrandAnnotation/SecurityBadge/TopAdAnnotation:

Local Ads/Merchant Ratings/Site Links text.

bold Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/CallExtension/CalloutExtension/FourthLine/ReviewExtension/BrandAnnotation/SecurityBadge/TopAdAnnotation:


● This parameter will capture whether or not to bold Local Ads/Merchant Ratings/Site Links text.


● true means bold ● false means do not bold ● The default value is false.

color (onHover) Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/:


● This parameter will capture the color the of Local Ads/Merchant Ratings/Site Links text on mouseover.


● If an incorrect value is passed, this parameter is ignored.

underline (onHover) Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions:


● This parameter will capture whether or not to underline the Local Ads/Merchant


● true means underline title on hover

● false means do not underline title on hover

-46-


Mobile/DeskTop: LocalAds/MerchantRating/SiteLink/EnhancedSiteLink/SmartAnnotations/:

Ratings/Site Links text on mouseover.

● The default value is false.

backgroundColor

Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: OfficialSiteBadge:


● This parameter will capture the background color of Official Site Badge.


● If an incorrect value is passed, this parameter is ignored.

Ad Unit ‘n’ Image Ad Formatting Options

The following formatting options will apply to image ads extension for all ads in the ad unit (not applicable for algo):


align Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: ImageInAds:


● This parameter will capture if the image is shown to the right or the left of the Ad.

● The allowed value are “left” or “right”.

● “left” means image will be to the left of the ad

● “right” means image will be to the right of the ad

● The default value is “right”.

size Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop: ImageInAds:


● This parameter controls the size of the image to be shown.

● This is expressed as width x height.

● The default value is “50x50” for desktop and “20x20” for mobile.

appendToImageSrcUrl Hash: ypaAdSlotInfo: ypaSlotOptions: TemplateOptions: Mobile/DeskTop:


● This parameter will capture extra parameters that need to be appended to the image URL.

● The input should be a key value pair that will be appended to the image URL.

-47-


ImageInAds:

-48-


Sample Ad Tag

1. Insert the following script tag in the head section.

<script src="https://s.yimg.com/uv/dm/scripts/syndication.js"></script>

2. Place the style and div tag for an ad unit where ads should be shown on the page.

<style>#myDiv-AdUnit-1 iframe{width:100%}</style> <div id="myDiv-AdUnit-1"></div>

3. If you have multiple ad/algo units, place the style and div tag for each ad/algo unit where ads/algo should be shown on the page. Each ad/aglo unit should have its own style tag and div tag.

<style>#myDiv-AdUnit-2 iframe{width:100%}</style> <div id="myDiv-AdUnit-2"></div>

<style>#myDiv-AlgoUnit iframe{width:100%}</style> <div id="myDiv-AlgoUnit"></div>

4. Insert the following code after the last ad div on the page:

<script type="text/javascript">

window.ypaAds.insertMultiAd({

ypaPubParams : {

query : "addidas shoes",

location : "Burbank, CA",

inputCharEnc : "utf8",

outputCharEnc : "utf8",

gdpr: "1",

euconsent: “BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA”

},

ypaAdTagOptions : {

SponsoredSearch : {

Mobile : {

SrcTag : "ss_src_tag_mobile"

},

DeskTop : {

SrcTag : "ss_src_tag_desktop"

}

},

//set clickBeacon/serveBeacon here if you want to use the

same parameters for

//all the slots.

//string of key value pairs, which is appended to server URL provided in UI.

//if key passed is already in UI, it will be overridden.

clickBeacon : "click=true&serve=false",

serveBeacon : "click=false&serve=true",

serveBeaconServer: "serve.beacon.server.com/?a=1",

clickBeaconServer: "click.beacon.server.com/?a=1",

-49-


},

ypaAdConfig : "000000005",

ypaAdTypeTag : "typeTag",

ypaAdTrafficType : "test",

ypaClickTarget : “<options>”

ypaPageCount : 3,

ypaAdSlotInfo : [

{

ypaAdSlotId : "north",

ypaAdDivId : "ypaAdWrapper-MainNorth",

ypaAdWidth : "300",


ypaOnNoAd : postittoscreen,

//next two parameters take priority over the same parameters mentioned under ypaAdTagOptions //for this slot.Set it here if it's different for each slot.

//string of key value pairs, which is appended to server URL provided in UI.

//if key passed is already in UI, it will be overridden.

clickBeacon : "click=true&serve=false",

serveBeacon : "click=false&serve=true",

ypaSlotOptions : {

AdOptions : {

Mobile : {

AdRange : "1-2",

Lat : true/false, //default is UI selection

Favicon : true/false, //default is UI selection

LocalAds : true/false, //default is UI selection

SiteLink : true/false, //default is UI selection

MerchantRating : true/false, //default is UI selection

ImageInAds : true/false, //default is UI selection

EnhancedSiteLink : true/false, //default is UI selection

SmartAnnotations : true/false, //default is UI selection

OfficialSiteBadge : true/false, //default is UI selection

CallExtension : true/false, //default is UI selection

CalloutExtension : true/false, //default is UI selection

ReviewExtension : true/false, //default is UI selection

FourthLine : true/false, //default is UI selection

SecurityBadge : true/false, //default is UI selection

BrandAnnotation : true/false, //default is UI selection

TopAdAnnotation : true/false //default is UI selection

},

DeskTop: {

AdRange : "1-4",

Lat : true/false, //default is UI selection

Favicon : true/false, //default is UI selection

LocalAds : true/false, //default is UI selection

SiteLink : true/false, //default is UI selection

MerchantRating : true/false, //default is UI selection

-50-


ImageInAds : true/false, //default is UI selection

EnhancedSiteLink : true/false, //default is UI selection

SmartAnnotations : true/false, //default is UI selection

OfficialSiteBadge : true/false, //default is UI selection

CallExtension : true/false, //default is UI selection

CalloutExtension : true/false, //default is UI selection

ReviewExtension : true/false, //default is UI selection

FourthLine : true/false, //default is UI selection

SecurityBadge : true/false, //default is UI selection

BrandAnnotation : true/false, //default is UI selection

TopAdAnnotation : true/false //default is UI selection

}

}, //AdOptions end

TemplateOptions : {

Mobile : {

AdUnit : {

backgroundColor : "#ABABAB",

borderColor : "#ABABAB",

lineSpacing : 15, (valid values 8-25)

adSpacing : 15, (valid values 5-30)

font : "Verdana",

urlAboveDescription : true/false, //default is UI selection

adLayout : 1/2/3, //show ad in one line, two lines or three lines

respectively

cssLink : "https://partnercsslocaiton.com/mycss.css",

},

AdUnitLabel : {

position : "Top Left"/"Top Right"/"Bottom Left"/"Bottom Right",

fontsize : 6-24, //allowed values 6-24

color : "#123123", //hex value

labelId: 2, // Maps to "Ads" from Appendix Table 1 },

Title : {

fontsize : 14, ( valid value 8-18 ),

color : "#ABABAB",

underline : true/false,

bold : true/false,

onHover : {

color : "#BCBCBC", //Applies to background color of

OfficialSiteBadge as well.

underline : true/false

}

},

Description : {


color : "#ABABAB",


bold : true/false,

onHover : {

-51-


color : "#BCBCBC",


}

},

URL : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

LocalAds : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

MerchantRating : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

SiteLink : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

EnhancedSiteLink : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

-52-


SmartAnnotations : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

ImageInAds : {

align : left/right, //default is UI selection

size : "30x50", // width x height, default 20X20 for mobile

appendToImageSrcUrl : "a=5&b=home"

},

OfficialSiteBadge : {


color : "#ABABAB",


},

CallExtension : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

}

},

BrandAnnotation : {


color : "#ABABAB",


bold : true/false

},

SecurityBadge : {


color : "#ABABAB",


bold : true/false

},

TopAdAnnotation : {


color : "#ABABAB",


bold : true/false

},

FourthLine : {


color : "#ABABAB",


-53-


bold : true/false

},

CalloutExtension : {


color : "#ABABAB",


bold : true/false

},

ReviewExtension : {


color : "#ABABAB",


bold : true/false

} // Mobile End

DeskTop: {

AdUnit : {





font : "Verdana",

urlAboveDescription : true, //default is UI selection

cssLink : "partnercsslocaiton.com/mycss.css"

},

AdUnitLabel : {

position : "Top Left"/"Top Right"/"Bottom Left"/"Bottom Right",

fontSize : 6-24, //allowed values 6-24

color : "#123123", //hex value

labelId: 2, // Maps to "Ads" from Appendix Table 1

},

Title : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

Description : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

URL : {


-54-


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

LocalAds : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

MerchantRating : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

SiteLink : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

EnhancedSiteLink : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

SmartAnnotations : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",

-55-



}

},

ImageInAds : {

align : left/right, //default is UI selection

size : "50x50", // width X height, default 50X50 for Desktop

appendToImageSrcUrl : "a=5&b=home"

},

OfficialSiteBadge : {


color : "#ABABAB",


},

CallExtension : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

BrandAnnotation : {


color : "#ABABAB",


bold : true/false

},

SecurityBadge : {


color : "#ABABAB",


bold : true/false

},

TopAdAnnotation : {


color : "#ABABAB",


bold : true/false

},

FourthLine : {


color : "#ABABAB",


bold : true/false

},

CalloutExtension : {


color : "#ABABAB",


bold : true/false

},

ReviewExtension : {


-56-


color : "#ABABAB",


bold : true/false

}// DeskTop End

} // TemplateOptions End

} // ypaSlotOptions End

}, // Slot 1 end

{

ypaAdSlotId : "south",

ypaAdDivId : "ypaAdWrapper-MainSouth",

ypaAdWidth : "300",


onNoAd : postittoscreen

},

{

//Algo Slot

ypaAdSlotId : "northalgo",

ypaAdDivId : "ypaAdWrapper-MainAlgoNorth",

ypaAdWidth : "300",


ypaOnNoAd : postittoscreen,

ypaSlotOptions : {

AdOptions: {

Mobile : {

AdRange : "1-2"

},

DeskTop: {

AdRange : "1-4"

}

}, //AdOptions end

TemplateOptions : {

Mobile : {

AdUnit : {





font : "Verdana",

urlAboveDescription : true/false, //default is UI selection

cssLink : "partnercsslocaiton.com/mycss.css",

},

Title : {


color : "#ABABAB",


-57-


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

Description : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

URL : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

}

}, // Mobile End

DeskTop: {

AdUnit : {





font : "Verdana",

urlAboveDescription : true, //default is UI selection

cssLink : "partnercsslocaiton.com/mycss.css"

},

Title : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

},

Description : {


color : "#ABABAB",


bold : true/false,

-58-


onHover : {

color : "#BCBCBC",


}

},

URL : {


color : "#ABABAB",


bold : true/false,

onHover : {

color : "#BCBCBC",


}

}

} // DeskTop End

} // TemplateOptions End

} // ypaSlotOptions End

} // Algo Slot end

]

});

</script>

Keyword Extraction

YPA can also extract the search term from the page URL ( refer pubParams:query as well ) where ads/algo will be displayed.

For example, the keyword that will be extracted from the following URLs is laptop:

● http://example.com?k=laptop ● http://example.com?key=laptop ● http://example.com?keyword=laptop ● http://example.com?keywords=laptop ● http://example.com?kw=laptop ● http://example.com?p=laptop ● http://example.com?pt=laptop ● http://example.com?q=laptop ● http://example.com?qt=laptop ● http://example.com?query=laptop ● http://example.com?s=laptop ● http://example.com?search=laptop ● http://example.com?searchfor=laptop ● http://example.com?search_query=laptop ● http://example.com?stx=laptop ● http://example.com?t=laptop

-59-


● http://example.com?text=laptop ● http://example.com?title=laptop

Market Identification

YPA detects the correct market for ad serving, based on the various signals received from the YPA implementation. Advertiser demand will be matched to the ad call based on Bing’s Global Targeting Feature.

The following signals may be used to determine the correct market:

● User IP ● Language of the Keyword ● Domain where ads are served ● Browser settings

Note: Yahoo will only serve ads in markets for which you are contracted.

Ad label switch based on Market Identification

If the language of the ad label you choose on the UI or pass via dynamic parameter is not the dominant language in the market chosen by YPA, YPA will change the Ad label text to the default Ad label for the dominant language in that market.

Example: If you choose ‘Spanish’ as the Ad label language on the UI but YPA decides to serve the ad call from the Taiwan market, the Ad label text will be changed to: ‘廣告’

Details on default ad label per language are in Appendix Table 1.

Official Site Badge switch based on Market Identification

If the language of the ad label you choose on the UI is not the dominant language in the market chosen by YPA, YPA will change the Official Site Badge text to the Official Site Badge for the dominant language in that market.

Default Official Site Badge text per market is in Appendix Table 2.

-60-


Beaconing

YPA allows you to optionally get beacons on a search and click event for ads & algo on the page. This will help you to get real time data on searches and clicks on your network. You will also be able to associate individual clicks to the corresponding searches. You will have to implement a server that is able to accept HTTP get requests (beacons) and respond back with a 1x1 pixel image. With the HTTP request you will get the UserIP and UserAgent information for both search and click beacons. While creating an ad tag, you can input the details of the server where you would want to receive the beacons. You can also add any tracking information as params on the beacon URL. YPA will add details of the search and click at the end of the provisioned URL.

Search Beacon

The search beacon will be sent when ads are shown on the webpage. The following information will be added to the search beacon:

1. id - ID for a search impression 2. ts - Timestamp for the search impression 3. q - Search keyword 4. u - URL on which ads/algo are shown 5. slotID - Ad/Algo unit name 6. ty - Type tag (defaults to ‘meta’ if not passed in the ad tag) 7. nq - Number of ads/algo requested for that unit/Slot 8. nr - Number of ads/algo returned for that unit/Slot 9. ut - Type of unit. 1 = Ad unit; 2 = Algo unit

Format of URL to add to the ad tag:

http:// <BeaconServer>/ <IMG file>? <Your parameters to be returned back> Beacon URL:

http://< BeaconServer>/< IMG file>?< Your parameters to be returned back>&id=< ID for an impression>&ts=< Timestamp for the impression>&q=< Search keyword>&u=< URL on which ads/algo are shown>&slotID=< unit_name>&ty=<type tag> &nq=<Number of ads/algo requested >&nr=<Number of ads/algo returned >&ut=<unit_type> There will be one search beacon sent for each unit position on the page. They will have the same ID and timestamp.

-61-


Click Beacon

The click beacon will be sent when an ad/algo is clicked. The following information will be added to the click beacon:

1. id - Impression Id from the search 2. ts - Timestamp for the search 3. cts - Timestamp for the Click 4. slotID - Unit name 5. rk - Rank of the ad/algo that was clicked within the unit/Slot 6. ut - Type of unit. 1 = Ad unit; 2 = Algo unit

The search and click beacons will have the same Id and timestamp, so you will be able to join the beacons based on those values, thereby associating clicks back to their searches. Format of URL to add to the ad tag:

http://< BeaconServer>/< IMG file>?< Your parameters to be returned back> Beacon URL:

http://< BeaconServer>/< IMG file>?< Your parameters to be returned back>&id=< ID for an impression>&ts=< Timestamp for the impression>&cts=<Timestamp for the click>&slotID=< ad_unit_name>&rk=<ad rank within the slot> &ut=<unit_type> Response IMG File:

The response to an HTTP GET beacon call should be an image file. The image should be a transparent 1 x 1 pixel GIF or PNG file.

-62-


Dynamic CSS

The YPA tool allows you to control the appearance and function of your ads and algo results. You can also specify a CSS URL to control the display properties of your ads/algo. You can add the URL for your CSS into the YPA tool while creating an ad tag. Your CSS will be used while serving ads for that ad tag. The CSS can be hosted by you or a sub-syndicate. The CSS should conform to the HTML classes used by YPA. The following table explains the classes that can be customized to control border, border color, font family, font size, font color, etc.

Class Use

ypaAdUnit This class houses all the ads/algo. Border for the unit can be configured for this class.

ypaAdTitle This class is for the ad/algo title.

ypaAdDesc This class is for the ad/algo description.

ypaAdURL This class is for the ad/algo URL.

ypaAdLAAddr1 This class is for the local ads extension, address line 1.

ypaAdLAAddr2 This class is for the local ads extension, address line 2.

ypaAdLACity This class is for the local ads extension, city name.

ypaAdKeyword This class is for the keywords returned for sitelinks extension.

ypaAdMRLabel This class is for the merchant ratings extension for merchant name.

ypaAdSiteLinkDescItem This class is for each line in the enhanced sitelink extension.

ypaAdSmartAnnotations This class is for the smart annotation extension.

ypaAdOfficialSiteBadge This class is for the official site badge extension.

ypaAdCallExtension This class is for call extension.

You can specify different styles for Ads and Algo in the same CSS file, if needed, by prepending unit type specific class name. For example,

● To change style of title for algo only, .ypaAdAlgo .ypaAdTitle {color : #ccc;}

● To change style of url for ads only, .ypaAdSS .ypaAdURL {color : #ccc;}

You could also use a separate CSS file for each unit.

-63-


Support for Third Party Image Providers for Image in Ads Ad Extension

The YPA tool allows integration with third party image providers for the image in ads ad extension. By default, Yahoo is configured as the default image provider. To use a third party image provider, the publisher should send sample image URLs from the image provider to their Partner Manager. The Partner Manager will then work with the publisher to get these configured in the YPA system.

-64-


A/B Experimentation Framework

YPA offers the capability of running A/B tests. This provides an opportunity for you to easily set up and run various experiments. A/B Experiment framework allows running of multiple experiments across all your implementations. Each experiment can define a behavior (aka “bucket”) on a given percent of your traffic. Experiments could vary from different look and feel of ads to enable/disable ad-extensions. For example, enable/disable of Site Links, change font/color/onHover behavior and much more without any code change needed by you. How to define an experiment?

● Name your experiment ○ Max char limit: 46 ○ All spaces will be replaced with underscore

● Where you want to run ○ Experiments can be configured for

■ AdTag(s) - particular web page ■ SiteGroup(s) - across website(s), or, ■ All implementations

● Do you want to run on specific traffic ○ Available conditions

■ Market - choose the markets for your experiment ■ Device Type - Mobile or Desktop ■ AND/OR on the above conditions

● What do you want to test ○ Name each bucket

■ Max char limit: 46 ■ All spaces will be replaced with underscore

○ Describe the behavior for each bucket ○ If you would like a control bucket, specify that as well. ○ Example 1

■ Bucket_1 - set color=’006655’ for title ■ Bucket_2 - set color=’FFFFFF’ for title ■ Control_bucket - Keep existing color

○ Example 2 ■ Bucket_1 - enable site links ■ Bucket_2 - disable site links

● How much traffic do you want to test ○ Specify for each bucket in % of total traffic ○ Total percentage of traffic for all buckets of an experiment should not exceed 100. ○ Example

■ Bucket_1 - 5% ■ Bucket_2 - 5% ■ Control_bucket - 5%

-65-


How do I get the performance data? You can get details on how each experiment is performing via type tag reports on Partner Insights. Experiment name and Bucket name will be available as the type tag in the following format e-Experiment_Name:b-Bucket_Name

If you pass a type tag in the ad call as well, it’ll be truncated to 100 chars and then the Experiment Name and Bucket Name will be appended to it in the following format <type_tag truncated to 100 chars>,e-Experiment_Name:b-Bucket_Name

Where do I set it up? Publishers can submit the set up request themselves through this link: https://goo.gl/FM6TEP Alternatively work with your Partner Manager to request setup of your experiment on your behalf.

-66-


https://goo.gl/FM6TEP

https://goo.gl/hkLAcv

Appendix

Table 1: Supported languages for Ad labels

Ad Label Language Default for the language

Label Id Ad Label Text

Bahasa Indonesian 50 Iklan oleh Yahoo

Bahasa Indonesian ✓ 51 Iklan yang terkait dengan

Chinese (Traditional) ✓ 40 廣告

Chinese (Traditional) 41 廣告推薦

Chinese (Traditional) 42 搜尋

Chinese (Traditional) 43 搜尋結果

Chinese (Traditional) 44 瀏覽廣告

Chinese (Traditional) 45 相關廣告

Chinese (Traditional) 46 廣告推介

Chinese (Traditional) 47 相關搜尋

Chinese (Traditional) 48 贊助網站

Chinese (Traditional) 49 雅虎贊助網站

Danish 80 Annonce

Danish ✓ 81 Annoncer

Danish 82 Sponsorerede annoncer

Danish 83 Sponsorerede Links

Danish 84 Sponsorerede resultater

Danish 85 Sponsoreret

Danish 86 Sponsoreret link

Danish 12 Sponsored by Yahoo

Dutch 90 Advertentie

Dutch ✓ 91 Advertenties

-67-


Dutch 92 Gesponsord

Dutch 93 Gesponsord resultaat

Dutch 94 Gesponsorde advertenties

Dutch 95 Gesponsorde Resultaten

Dutch 12 Sponsored by Yahoo

English 1 Ad

English 2 Ads

English 3 Ads by Yahoo

English ✓ 4 Ads related to <query>

English 5 Advertisement

English 6 Advertisements

English 7 Advertiser Links

English 8 Advertiser Sites

English 9 Advertisers

English 10 Featured Advertisements

English 11 Sponsored By

English 12 Sponsored by Yahoo

English 13 Sponsored Links

English 14 Sponsored Listings

English 15 Sponsored Results

English 16 Sponsored Sites

Finnish ✓ 100 Mainokset

Finnish 101 Mainos

Finnish 102 Sponsoritulokset

Finnish 103 Sponsoroidut hakutulokset

Finnish 104 Sponsoroidut mainokset

Finnish 105 Sponsoroitu

Finnish 106 Sponsoroitu tulos

Finnish 12 Sponsored by Yahoo -68-


French 110 Annonce

French ✓ 111 Annonces

French 112 Annonces sponsorisées

French 113 Lien sponsorisé

French 114 Parrainé

French 115 Recherche avancée

French 116 Résultats sponsorisés

French 12 Sponsored by Yahoo

German 120 Anzeige

German ✓ 121 Anzeigen

German 122 Erweiterte Suche

German 123 Gesponsert

German 124 Gesponserte Anzeigen

German 125 Gesponserte Ergebnisse

German 126 Sponsoren-Link

German 12 Sponsored by Yahoo

Italian ✓ 130 Annunci

Italian 131 Annunci sponsorizzati

Italian 132 Annuncio

Italian 133 Inserzioni

Italian 134 Ricerca Avanzata

Italian 135 Risultati Sponsor

Italian 136 Risultati sponsorizzati

Italian 137 Risultato sponsor

Italian 138 Sponsorizzati

Italian 139 Sponsorizzato

Italian 12 Sponsored by Yahoo

Norwegian 140 Annonse

Norwegian ✓ 141 Annonser -69-


Norwegian 142 Sponsede annonser

Norwegian 143 Sponsede resultater

Norwegian 144 Sponset

Norwegian 145 Sponsorlenke

Norwegian 146 Sponsorresultater

Norwegian 12 Sponsored by Yahoo

Portuguese 20 Resultados patrocinados

Portuguese 21 Links patrocinados

Portuguese 22 Patrocinado

Portuguese 23 Anúncios patrocinados

Portuguese ✓ 24 Anunciantes

Portuguese 2 Ads

Portuguese 13 Sponsored Links

Spanish 30 Anuncio

Spanish ✓ 31 Anuncios

Spanish 32 Anuncios patrocinados

Spanish 33 Enlace patrocinado

Spanish 35 Preferencias del Filtro Adulto

Spanish 2 Ads

Spanish 12 Sponsored by Yahoo

Spanish 13 Sponsored Links

Spanish 20 Resultados patrocinados

Spanish 21 Links patrocinados

Spanish 24 Anunciantes

Swedish 150 Annons

Swedish ✓ 151 Annonser

Swedish 152 Sponsrad

Swedish 153 Sponsrad Sökträffar

-70-


Swedish 154 Sponsrad sökträff

Swedish 155 Sponsrade annonser

Swedish 156 Sponsrade resultat

Swedish 12 Sponsored by Yahoo

Thai 60 โฆษณาจาก Yahoo

Thai ✓ 61 โฆษณาท่ีเก่ียวกับ

Vietnamese 70 Quảng cáo của Yahoo

Vietnamese ✓ 71 Quảng cáo liên quan đến

Table 2: Official Site Badge text for supported languages

Market Official Site Badge Text

Bahasa Indonesian Official Site

Chinese (Traditional) 官方網站

Danish Official Site

Dutch Official Site

English Official Site

Finnish Official Site

French Site officiel

German Offizielle Website

Indonesian Official Site

Italian Sito ufficiale

Norwegian Official Site

Spanish Sitio oficial

Swedish Official Site

Thai Official Site

Vietnamese Official Site

-71-


yahoo partner ads technical onboarding document

Documents