retail search exchangedeveloper.hooklogic.com/developers/docs/retailsearch...retail search exchange...

Retail Search Exchange Publisher Technical Implementation Guide (JavaScript) Version: 2.2.2 -- Last Revised: 6/17/2015

Retail Search Exchange Publisher Implementation Guide

V2.2.2 -- Last Revised: 6/17/2015 Confidential of 15

Retail Search Exchange Implementation

How Retail Search Exchange Works

When a shopper visits a Retail Search Exchange enabled retail web page, HookLogic receives an

asynchronous request via JavaScript. The function acquires and passes page specific properties that allow

HookLogic's system to determine what, if any, product ads should be returned to the shopper's browser

and seamlessly inserted within the page as it loads. Throughout the shopper's journey, HookLogic records

every request along with whatever content was displayed for reporting and billing purposes. When the

shopper purchases products, HookLogic identifies which are attributable to the ad interaction in order to

provide the Advertiser with aggregated reporting showing their Return On Ad Spend (ROAS) for their

campaigns across the network.

Implementation Process Overview

Activity Task Owner Tasks

Implementation

Kick-off Meeting

HookLogic &

Publisher

Identify product ad placement location and creative requirements

Walk through implementation guide

Establish project plan and timeline

Implementation

Publisher Provide data feed via FTP

Instrument HookLogic scripts in lower environment

HookLogic Consume product data feed

Configure Retail Search Exchange product ad delivery

QA of product ads on lower environment

Acceptance

Testing Publisher

Signoff on product ad placement and creatives

Confirm go live date

Go Live Publisher Deploy HookLogic instrumentation to production

HookLogic QA of product ads on production

Publisher Site Tagging

Enabling the Retail Search Exchange on your website requires placing a call on every page to the HookLogic

JavaScript library file, creating optional <div /> elements where the ads are to be displayed, and setting page

specific properties. The properties vary by type of page, and are necessary to determine ad selection, content

delivery and reporting processes.

Description Code Snippet

1 Load JavaScript Library Place the HookLogic JavaScript library on all pages of the site in the <head>. Minimum required pages are search results, product listings, product detail, and order confirmation pages.

<script

src="//www.hlserve.com/Delivery/ClientPaths/Library/hook.js?apiK

ey=CLIENTGUID&channel=web"></script>

The Client GUID will be provided during the implementation kickoff call. For a mobile

implementation, please replace "web" with "mobile".

2 Optional: place <div /> tag Place <div /> tag(s) within the page at the precise location(s) where Retail Search Exchange product ads are to be displayed. HookLogic can insert <div /> tags by adding the element to the DOM using JavaScript.

One <div /> for each product ad module on the page (multiple products can be shown

per module such as a row). Note, for pages with multiple ad modules, please

increment the number (hl_#) for each div.



<div id="hl_1"></div>

3 Call top level function(s) HookLogic's library provides functions that operate independently to request ads, update product price and availability, and provide attribution details via order details and logging shopper actions.

One .newRequest() for each product ad module on the page. Call the function just

after the <div> has been placed. Note, for pages with multiple ad modules, please

change the id (eg. .submit("hl_#");) for each .newRequest()

<script>

HLLibrary.newRequest()

.setTaxonomy("43")

.setKeyword("laptop computer")

.setModule("AboveGrid")

.setProperty("hlPageType", "S")

.setProperty("brand", "sony")

.setProperty("minPrice", "750")

.setProperty("maxPrice", "999.99")

.setFilter("Screen Size", "13-14 inches")

.submit("hl_1");

</script>

Top Level Functions

All HookLogic top level functions operate independently. There are occasions such as a product detail page with

an ad module when multiple different function calls would be made using the same or a similar set of required

properties for different purposes.

Function Description Example

newRequest Used on any type of page to request ads given context of targeting functions and properties. Multiple ad placements on a single page would have separate .newRequests()




<script>


.setTaxonomy("4563")



// set of appropriate properties

.submit("hl_1");

</script>

newUpdate Used on product detail pages to provide intra-day pricing and availability updates. Also enables HookLogic to learn from Shopper behavior between search listing pages to associate keywords to SKUs based on your site traffic.

If there is to be an ad module on the product detail page, a newRequest would also be used.



<script>

HLLibrary.newUpdate()


.submit();

</script>

newOrder Used on order confirmation pages to provide order details to be used over a 30 day look back window to attribute sales of products associated with an impression or click on an ad.

If there is to be an ad module on the order confirmation page, a newRequest would also be used.



<script>

HLLibrary.newOrder()


.submit();

</script>

newEvent Typically used on product detail or listing pages to track shopper behavior as other signs of engagement with the Advertiser's products after a click on a product ad.



<script>

HLLibrary.newEvent()


.submit();

</script>



SubFunctions

HookLogic's library has functions to communicate ad targeting and configuration information within the top

level functions. Note: the setTaxonomy, setKeyword, setModule, and setFilter functions only work with the

newRequest top level function.

SubFunction Description Examples

setTaxonomy Used to target ads against a given taxonomy that the Shopper browses to, or filters search results by. Must match values provided in the 'taxonomy' field in the feed specifications.

If the page is not targeted by a taxonomy, pass 'null'.

Only available on newRequest calls.

Targeting a taxonomy key:

.setTaxonomy("43")

No taxonomy set:

.setTaxonomy(null)

setKeyword Used to target ads against a given keyword or phrase the shopper uses, or filters results by. For a search that is also narrowed by category, you would set both a taxonomy and keyword.

Do not encode the keyword phrase.



setProduct Used to ensure that this product (SKU and/or parentSKU) is not displayed in a product ad placement on its own page.


.setProduct("12345","12345a"|"12345b")

setModule Used to identify the creative template that will be used to render an ad module and pass specific details to ad module location and details for use in HookLogic's machine learning algorithms.



setProperty Globally understood properties used to further refine the ads to be displayed, or to update product and order information. Strongly encouraged to set as many properties as possible.

Available for all top level functions.

.setProperty("brand", "sony")

setFilter Retailer specific filters used to further refine the ads to be displayed. Strongly encouraged to set as many filters as possible.


.setFilter("Screen Size", "13-14 inches")



Functions and Required Properties

Below is a table that identified which properties are required or optional for each of the library functions. These

properties are passed to HookLogic via the setProperty and setFilter functions as appropriate. X = required, O =

optional

Property newRequest newUpdate newOrder newEvent

cUserID X X X X

hlPageType X X X X

pCount X

pgSize X

organicSKUs X

pgN X

view X

sort O

[filters] X

brand X

minPrice X

maxPrice X

minRating X

sku X X X

parentSku X X X

price X X

regularPrice X

inStock X

availability O

quantity X

orderId X

eventType X

addId O O



Page Property Glossary

Property Name Req Description Examples

cUserId Yes Your unique identifier for the authenticated Shopper. If a shopper is unauthenticated set this as an empty value.

("cUserId", "u270109003952")

hlPageType Yes This is the canonical page type for where the product ads placement is rendered.

S: Search - any listing page that is limited by a keyword (including browse pages filtered by keyword)

B: Browse - all listing pages which do not include a user search term

Q: Quick View - modal for product details on a listing page

P: Product detail page

T: Topic Page - any page which contains a hand-selected set of SKUs as a destination

M: Merchandising Page - browse page that does not include a product listing (list or grid) on the page

H: Home page of the site

C: Cart/Checkout - includes anything from the view cart through checkout and order confirmation

L: Registry/Wishlist

R: Unknown Retail

O: Off-network Media

U: Unknown

("hlPageType", "S")

pCount Yes Number of organic products displayed on the listing page.

("pCount", "11")

pgSize Yes Number of products that a Shopper can see per page. ("pgSize", "12")

organicSKUs Yes An ordered list of all SKUs on the page. This is used to associate keywords and filter values to maximize coverage when the Shopper filters listings. For variation products, please set the parent SKU value.

("organicSKUs", "1|2|3|4|5|6|7")

pgN Yes Identifies the current page number being viewed when a search or category result returns multiple pages.

("pgN", "2")

view Yes Page view style for product listing pages. Typical values are "grid" or "list" view.

("view", "grid")

sort Opt The sort order that is applied on the listing page. For instance "price ascending / descending" and/or "rating ascending / descending." If this value is not passed, it assumes "default."

("sort","default")

("sort","price-asc")

("sort","price-desc")

("sort","rating-asc")

("sort","rating-desc")

[filters] Yes Set one filter for each filter that is applied. If a filter is removed, remove that filter. When a product filter has is applied by the Shopper create a setFilter with the exact name/value as provided in the 'descriptive_attributes' column of the data feed. If no attributes are provided in the data feed, they will be automatically associated from Shopper traffic.

Single filter, single value:

setFilter("Color", "Black");

Multiple filters, multiple values:

setFilter("Screen Size", "13-14

inches");

setFilter("Color", "Black|Silver");

brand Yes The value(s) the Shopper has selected to limit the results by brand. Pipe (|) delimit values for multiple brands.

("brand", "sony")

("brand", "sony|panasonic")

minPrice Yes Minimum price to match a product for display. Match is inclusive (>=). For example, the Shopper selects "$10 -

("minPrice", "10")



$25".

maxPrice Yes Maximum price to match a product for display. Match is inclusive (<=). For the example, the Shopper selects "$10 - $25".

("maxPrice", "25")

minRating Yes Minimum rating to match (>=) a product for display. For example, the Shopper selects 3 stars, we may return products with 3 or more star ratings.

("minRating", "3")

availability Opt Setting the availability property allows HookLogic to know if a product is in stock in other channels (i.e. on pre-order, or if an item is in-store eligible however not available on web).

("availability","preorder")

("availability","storeeligible")

("availability","web|storeeligible")

sku Yes Unique SKU identifier for the product. Pipe (|) delimit values for multiple products on an order confirmation page.

Product Page:

("sku", "333960")

("parentSku", "333000")

("price", "79.99")

("regularPrice", "84.99")

("inStock", "1")

Important: If HookLogic directs a Shopper to a product detail page using a sku that is no longer in stock, please ensure in that page's call, you pass that as item sku=[out of stock SKU] with a inStock=0 and we will remove that product from being displayed.

Order Confirmation:

("sku", "333960|337307|786304")

("parentSku", "333000||")

("price", "79.99|205.49|9.99")

("quantity", "1|1|2")

("orderId", "1883843891")

parentSku Opt For variation items such as a XL Blue Polo Shirt, this is identifier for this child SKU's parent.

price Yes Sale price for each product on the order. Pipe (|) delimit values for multiple products on an order confirmation page.

regularPrice Yes Non-sale price for each product on the order. Pipe (|) delimit values for multiple products on an order confirmation page.

inStock Yes Flag to identify if the product is available for purchase on the site. "0" = out of stock, "1" = in stock.

quantity Yes Units of each product in each order. Pipe (|) delimit values for multiple products on an order confirmation page.

orderId Yes The Order ID or Transaction ID

eventType Yes Details of the event types are available in the Event Based Secondary Attribution section of this document.

("eventType", "add|registry")

addId Opt The registry or wishlist id that the product was added to. ("addId", "123456789")

HookLogic Tagging Examples

newRequest - Product Listing Page (search and browse) 


<script>





.setProperty("cUserId", "u270109003952")

.setProperty("hlPageType", "S")

.setProperty("pCount", "11")

.setProperty("pgSize", "12")

.setProperty("organicSKUs", "1|2|3|4|5|6|7|8|9|10|11|12")

.setProperty("pgN", "2")

.setProperty("view", "grid")

.setProperty("sort", "price-asc")



.setFilter("Color", "Black|Silver")

.setFilter("Screen Size", "13-14 Inches")

.submit("hl_1");

</script>

newRequest - Product Details Page




<script>


.setProduct("12345")


.setModule("carousel")


.setProperty("hlPageType", "P")



.submit("hl_1");

</script>

newUpdate - Product Detail Page 

<script>



.setProperty("availability", "web|storeeligible")

.setProperty("sku", "401886")

.setProperty("parentSku", "401800")

.setProperty("price", "79.99")

.setProperty("regularPrice", "84.99")

.setProperty("inStock", "1")

.submit();

</script>

For a variation item (such as available in multiple sizes/colors): 

<script>



.setProperty("availability", "storeeligible")

.setProperty("sku", "6133730003|6133730004|6133730005")

.setProperty("parentSku", "6133730000||")

.setProperty("price", "14.99|14.99|17.99")

.setProperty("regularPrice", "19.99|19.99|22.99")

.setProperty("inStock", "1|1|0")

.submit();

</script>

newOrder - Order Confirmation Page 

<script>



.setProperty("hlPageType", "C")

.setProperty("parentSku", "4525943||")

.setProperty("sku", "401886|651363|444209")

.setProperty("price", "799.99|199.99|79.99") // unit price only

.setProperty("quantity", "1|1|2")

.setProperty("orderId", "1883843891")

.submit();

</script>

Event Based Secondary Attribution

A purchase is not always the end point of a Shopper's journey, there are often other actions that a Shopper takes that are either an indication of the Shopper moving deeper in the buying funnel, or as an alternate form of "success" to the Advertiser. If a significant portion of your Shoppers use functionality such as adding products to a baby or wedding registries, or sharing products on social sites, this section is highly recommended.

eventTypes:

In order to track events for a specific type that can be aggregated across the Retail Search Exchange we have

created the below declared eventTypes. Please try and use the defined events whenever you can; however,

since each Publisher may have custom solutions we have engineered they system to support any value.

1. add – The Shopper added this product to a registry or list

a. subtypes: add|cart, add|registry, add|list, add|[custom type name]

b. Properties: addId – A unique identifier which will identify this cart/registry/list. Note that in the

case that more than one subtype is in use, the id should be unique across all subtypes.

2. social – The Shopper shared this product using a social link

a. subtypes: social|facebook, social|pintrest, social|twitter, social|[custom type name]

3. offline – The Shopper took action leading to an in-store purchase

a. subtypes: offline|store locator, offline|find in store, offline|print, offline|[custom type name]

4. research – The Shopper took an action to consider a purchase in the future

a. subtypes: research|email, research|follow price, research|[custom type name]

Event Instrumentation:

The script can be made within an existing onClick event, or HookLogic can use callback function serially. Please

contact your HookLogic Implementation Manager to work through the details specific to your needs.

newEvent - Add to Registry event (with registry ID):

HookLogic supports setting the ID of the Registry the product was added to in order to allow for the sale to be

attributed to the event. Note, the order confirmation instrumentation should be updated to pass the 'addId'

for each product that was purchased for a registry.



<script>




.setProperty("eventType", "add|registry")

.setProperty("addId", "123456789")

.submit();

</script>

newEvent - Custom event:

For extensibility to support emerging and custom events, you can pass a custom string as the value for any of

the standard eventTypes that can be set.



<script>




.setProperty("eventType", "research|where to buy")

.submit();

</script>

Secondary Attribution Order Confirmation:

In order to attribute a sale of a product from an "Add" event, please add the additional property "addId" to the

order confirmation page instrumentation. This is to account for an item purchased for a Registry from a mixed

cart by any Shopper who has purchased a product for a specified list.

newOrder - Additional Order Confirmation property:

Single item example: 

<script>




.setProperty("price", "799.99")

.setProperty("quantity", "1")

.setProperty("addId", "123456789");


.submit();

</script>

Multi-item example: 

<script>



.setProperty("sku", "401886|651363|444209")

.setProperty("price", "799.99|199.99|79.99")

.setProperty("quantity", "1|1|2")

.setProperty("addId", "123456789||");


.submit();

</script>

If an order contains no products for a registry, you should omit the "addId" property.



3rd Party Analytics

HookLogic can leverage the Publisher's existing analytics and reporting services by rendering tracking details within with the ad creative. Please provide scripts or URL parameters with detailed instructions to the HookLogic implementation manager, and they will be included.

Product Data Feed

The product data feed is required for the Retail Search Exchange in order to render the Product Ads in a

matching, or very similar manner to your organic product listings as well as the ability to attribute sales.

Additional data may be required based on the creative requirements and design elements of the ad module.

Name Req Data Type

Max Length Description Example

sku Yes string 50 Unique product identifier. A feed cannot contain duplicate SKUs. Products with duplicate SKUs will be marked as invalid.

60237

parent_sku Yes string 50 For variation items such as a XL Blue Polo Shirt, this is identifier for this child SKU's parent. Often referred to as the product ID.

401999

collection_id Opt string 100 For products that are part of a collection, this is the identifier for the collection.

853453

brand Yes string 50 The name of the brand/manufacturer of the product

Canon

mpn Yes string 50 The Manufacturer Part Number A1300BLK

model_number Opt string 50 The Model Number for the item A1300

upc Yes string 14 Universal Product Code or GTIN 013803146714

google_product_category Yes string 500 The categorization for each product to Google Product Category hierarchy. The value you send in field to Google Shopping.

Cameras & Camcorders > Digital

Cameras

taxomy_key Yes String 500 The identifier you can pass in the .setTaxonomy subFunction. Each key in the hierarchy needs to be delimited by " > ". If a product is available in multiple taxonomies, please send pipe delimited with the primary taxonomy first in the array.

Single:

3 > 70 > 466 > 4051

Multiple:

3 > 70 > 466 > 4051

|11 > 121 > 3211

breadcrumb Yes string 500 Your merchandising category for this product. Each level in the hierarchy needs to be delimited by " > ". If a product is available in multiple categories, please send as pipe delimited with the primary category first in the array.

Single:

Computing > Keyboards and

Mice > Mice > Wireless Mice

Multiple:

Computing > Keyboards and

Mice > Mice > Wireless

Mice|Gifts > For Dad > Mice

title Yes string 200 The product title Powershot A1300 Black 16

Megapixel Digital Camera

description Yes string 2000 Detailed description of the product PowerShot A1300 digital camera

is comfortable to use and

comfortably affordable! Its

Optical Viewfinder....

https://support.google.com/merchants/answer/160081?hl=en



bullets Opt string 500 Bulleted list of product features used in ad copy without <ul> or <li> markup. Multiple values are piped delimited

16.0 megapixels|8x optical/4x

digital zoom|3.0-inch TFT Color

LCD screen

promo_text Yes string 60 Promotional text for this product Special Buy

product_rating Yes numeric 8 Average rating of product 3.5

number_of_reviews Yes numeric 8 Number of reviews for the rating 67

image_url Yes string 2048 Thumbnail product image (size to be displayed within search/browse results product grid). If possible, please provide details on how to resize the image to a specified height and width.

http://www.azamon.com/image

s/products/

A1300BLK.jpg?h=180&w=180

click_url Yes string 2048 URL from where a web user can purchase the product. This can include your site analytics tracking parameters.

http://www.azamon.com

/product/60237/Canon-

A1300BLK.html

currency Opt string 3 ISO 4271 standard currency code. Required if not in US Dollars.

USD

regular_price Yes numeric 15 Price the product normally is, typically displayed as strike-through. Can be MSRP.

119.99

sale_price Yes numeric 15 Unit price the product can be purchased for. Do not include shipping cost.

109.00

map_price Opt numeric 15 Minimum Advertised Price of the SKU. 119.00

shipping_cost Opt numeric 15 Value must be numeric, no dollar signs or special characters supported. Decimal places not required.

0.00

in_stock Yes Boolean 1 "1" indicates product is in stock, "0" indicates product is out of stock. If a product has been previously sent, but is not in this data feed, it will be marked as "0" out of stock.

1

condition Opt string 20 Condition of the product "new", "used", or "refurbished". Default value is "new".

new

variation_attributes Yes string 4000 Variations are attributes that you designate to discern the differences between children SKUs. Delimited list of attribute name value pairs. (eg. Name1=value1|Name2=value2)

Color=Black|Size=XL

descriptive_attributes Opt string 4000 Recommended to explicitly declare filters that will be displayed, and ensure 100% of products have filter values set. Delimited list of attribute name value pairs. (eg. Name1=value1|Name2=value2)

Color=Black|Megapixels=12

rendering_attributes Opt string 4000 Required to explicitly declare product specific data that is required to be rendered in the ads. Delimited list of attribute name value pairs. (eg. Name1=value1|Name2=value2)

ClearanceFlag=1|StorePickupElig

ible=1



Feed and FTP Information FTP: HookLogic will set up either FTP or SFT credentials for delivery of the product data feed. The credentials will be provided during the kickoff meeting.

FTP Host: hookftp.hooklogic.com

Username: [TBD]

Password: [TBD] Feed Name: [RetailerName]_Products_[Date].txt.gz Example: Azamon_Products_20130227.txt.gz

File Format: Tab delimited text, quote enabled, with column headers. Feed is required to be compressed using

gzip in order to minimize file transfer times and ensure that only complete files are processed.

File header: The data feed should contain the header row using the column names in the order specified.

Delivery frequency: The product data feed should be uploaded to HookLogic FTP server daily, and should be

delivered by 1:00am ET / 6.00am BT.

Update type: HookLogic's operates using the "flush and reload" paradigm and does not process "delta" feeds. If a product is not in the data feed, it will be marked as out of stock.

Quality Assurance and Testing There are several performance and quality control measures in place to ensure error free implementation

and usage of the HookLogic solution.

The following QA process is undertaken when the HookLogic solution is implemented:

(i) Code changes are first deployed on HookLogic's staging servers and run through our robust testing process. HookLogic uses proprietary browser testing tools to run its code changes against a publisher's test or live environment (depending on process agreed with publisher's QA team). This allows HookLogic to check any code changes on its staging servers before installing them on the live environment. At this stage, no changes are visible to end users.

(ii) Code is then moved to HookLogic's staging or live servers (depending on process agreed with publisher's QA team) where the same testing process is performed. Again, at this stage, no changes are visible to end users.

(iii) After HookLogic's internal testing is complete, code changes are published for publisher QA team for testing. Only user browsers with HookLook's special “test cookie” are served new code. This allows both HookLogic and the publisher to QA without exposing code changes to the end users.

(iv) Once publisher QA team gives approval, HookLogic updates the systems so end users can experience latest code updates.

(v) HookLogic continues to monitor performance and data collection statistics ensuring that end users experience is as intended.

Contact HookLogic For implementation support, please contact [email protected] or by call (646) 467-8222.

mailto:[email protected]

retail search exchangedeveloper.hooklogic.com/developers/docs/retailsearch...retail search exchange...

Documents