ShopLocal Partnerships
Best Practices & Content Strategy
Guidelines
Contents
Document History ......................................................................................................................................... 2
Overview ....................................................................................................................................................... 2
ShopLocal API ................................................................................................................................................ 2
Partner – API Developer Center Login ...................................................................................................... 2
ShopLocal Test API CampaignID – SandBox Retailer ................................................................................ 3
Common API Calls (Samples) .................................................................................................................... 3
Creative Best Practices.................................................................................................................................. 4
Establish a content strategy ...................................................................................................................... 4
Include Location Reference in Creative .................................................................................................... 4
Include Date Relevance............................................................................................................................. 5
Include Count Display ............................................................................................................................... 5
Count of Listings to Include....................................................................................................................... 5
Listings sort order ..................................................................................................................................... 5
Dark Period / No Content Default ............................................................................................................. 5
Images ....................................................................................................................................................... 5
Listing images ........................................................................................................................................ 5
Circular page images ............................................................................................................................. 5
Obtaining Alternate Image sizes (Dynamic Image Server) .................................................................... 5
Tracking ..................................................................................................................................................... 6
Deep Linking.............................................................................................................................................. 6
Link to listing item detail page .............................................................................................................. 6
Link to circular page .............................................................................................................................. 6
General linking to landing page ............................................................................................................ 6
Linking to ecommerce page .................................................................................................................. 6
Content Timing.............................................................................................................................................. 7
Circular Content Availability ..................................................................................................................... 7
Preview Hash............................................................................................................................................. 7
Content Strategies ........................................................................................................................................ 7
Ad Unit Performance Expectations ............................................................................................................... 8
Key performance indicators ...................................................................................................................... 8
Campaign/Initiative Lifecycle ........................................................................................................................ 8
Pre-Kick Off ............................................................................................................................................... 8
Kick-Off Call ............................................................................................................................................... 9
Pre-launch - Partner Status Meetings ....................................................................................................... 9
Pre-Launch - Client Status meetings ......................................................................................................... 9
Post-Launch - Performance Check Points ................................................................................................. 9
Post-Launch Demo ................................................................................................................................ 9
Campaign Wrap Up and Next Steps ........................................................................................................ 10
Document History
Date
5/10/2013
By
Sheila Balnis
Description
Created
Overview
This document is for ShopLocal partners, intended to serve as a guide for clients campaigns, initiatives,
or products in which we partner together to meet client’s needs for creative ways to distribute circular
and other deal content.
ShopLocal API
All ShopLocal partners should strive to use the most current version of the ShopLocal API to ensure they
may take advantage of the most up-to-date features and content, and to ensure optimal performance.
As of this writing, the most current released version is 2012.1. All versions that were release before
2010.1 are no longer actively supported (ie: SCAPI, SCRAPI)
Partner – API Developer Center Login
The login below will enable Partner team members to access the most current version of the API:
ShopLocal Developer Center: https://wiki.shoplocal.com/display/SHOPDEV/Home
username: As provided
password: As provided
When you log in, navigate to the ShopLocal Developer Center > API Documentation. You should navigate
to the latest version available, which will be the first displayed:
ShopLocal Test API CampaignID – SandBox Retailer
For testing purposes only, ShopLocal created a sandbox retailer so that developers can familiarize
themselves with the API and types of content. For testing purposes, Pointroll team members may use
the following:
Test CampaignID:
Retailer/pRetailerID:
As provided
Rob’s Retail / -97970
Common API Calls (Samples)
Note that all API calls require a location input. This can consist of a zip code, city state, storeid, store
reference number. If required, lat/long is also available (but for optimal performance, lat/long should be
used only to obtain the storeID, not in all subsequent calls).
For reference purposes only, here are a handful of common API calls that may be useful to a developer.
Each solution may call for varying api calls and/or parameters in order to pull in the appropriate content:
getStores
http://api.shoplocal.com/api/2012.1/xml/getstores.aspx?campaignid=[AsProvided]&citystatezip=60601
getPromotions
http://api.shoplocal.com/api/2012.1/xml/getpromotions.aspx?campaignid=[AsProvided]&citystatezip=6
0601
getCategories
http://api.shoplocal.com/api/2012.1/xml/getcategories.aspx?campaignid=[AsProvided]&citystatezip=60
601
getPromotionPages
http://api.shoplocal.com/api/2012.1/xml/getpromotionpages.aspx?campaignid=[AsProvided]&citystate
zip=60601&promotioncode=RobsRetail-TEST
getAllListings
http://api.shoplocal.com/api/2012.1/xml/getalllistings.aspx?campaignid=[AsProvided]&citystatezip=606
01&promotioncode=RobsRetailTEST&resultset=full&imagefilterflag=y&listingimagewidth=200&sortby=23&listingcount=10
getCategoryListings
http://api.shoplocal.com/api/2012.1/xml/getcategorylistings.aspx?campaignid=[AsProvided]&citystatezi
p=60601&promotioncode=RobsRetail-TEST&categorytreeid=4298
&resultset=full&imagefilterflag=y&listingimagewidth=200&sortby=23&listingcount=10
getRetailerTagListings
http://api.shoplocal.com/api/2012.1/xml/getretailertaglistings.aspx?campaignid=[AsProvided]&citystat
ezip=60601&promotioncode=RobsRetailTEST&retailertagid=2282&resultset=full&imagefilterflag=y&listingimagewidth=200&sortby=23&listingco
unt=10
Creative Best Practices
Initial draft of best practices:
Establish a content strategy
Establish a content strategy (along with campaign timing) and ensure this is communicated to the
ShopLocal client team; creating awareness ensures that the team closest to the content will help ensure
the campaign needs are met more seamlessly. If the implementation is permanent/ongoing, this is
manageable as well.
Include Location Reference in Creative
It is highly recommended to include location (city state, zip, etc) in the creative so that a consumer
realizes it is not generic offers, but offers that are relevant to their locale.
Include Date Relevance
It is highly recommended to include time relevance (such as valid thru date and/or countdown of days)
on the creative, and in some cases add valid thru date on the listings, in order to make clear to the
consumer that the deals are time sensitive.
Include Count Display
Counts of offers being displayed can encourage a user to expand and scroll listings.
Count of Listings to Include
There is no absolute for how many listings should appear in an ad unit, but in general – each selection
option presented to a user should contain a minimum of 5-10 listings. The client can add as many listings
as preferred, which users can scroll as desired.
Listings sort order
The most recommended sort order is Wisdom of Crowds (WoC) for those retailers that have a
ShopLocal-hosted SmartCircular site. WoC is constantly updated to identify the listings with most activity
on ShopLocal-hosted sites, and sort them accordingly. WoC sort can be applied to any of the ‘get listings’
calls (all listings, category listings, etc)
Dark Period / No Content Default
Since the deals content is localized and time sensitive, and tends to be quite volatile, it is ALWAYS
recommended to have graceful messaging / creative for cases where no content is returned. For
example, a retailer may have a dark day or dark week where there are no circulars or deals are available;
or they may omit a single geography from sales for a period of time. Any scenario that might result in a
consumer display issue should be planned for. This may be less necessary for closely managed
campaigns, and more necessary for turnkey, long running campaigns/inititaives.
Images
Listing images
Listing images are most frequently a key creative asset in the campaigns. For most clients, only
.jpg images are available. With these images, a white background exists, thus it is recommended
that the creative background take this into account. For some clients, .png images are available
as a standard (see documentation about client details), and these allow the flexibility of
alternate backgrounds. Note that some listings do not contain an image; there is a parameter
that enables these listings to be suppressed if desired. For some clients, .png images are
available with transparent background, allowing for more creative flexibility.
Circular page images
Circular page images are also available. If these are included, it is frequently the front cover
which a client may want displayed in the creative.
Obtaining Alternate Image sizes (Dynamic Image Server)
ShopLocal stores all circular page and listing images on the ShopLocal Dynamic Image Server.
Dynamic Image Serve URL Syntax
Sample URL:
http://akimages.shoplocal.com/dyn_li/WW.HH.QQ.0/Retailers/<CLIENTNAME>/<RandomImageName.JPG >
Where…
ClientName = the correct directory path for the specific retailer that image files are required for
WW = the image width, in pixels
HH = the image height, in pixels
QQ = the image quality (ranging from 0 - 100)
RandomImageName.jpg = a unique random image name created by ShopLocal
Note that by simply adjusting the image width, height and quality parameters, the outputted
image is dynamically generated to the requested size and quality on the fly.
Also, there is a FAQ page that gives some additional information about image sizes here:
https://wiki.shoplocal.com/pages/viewpage.action?pageId=4489242
(This link requires the API Developer Center login, provided above)
Tracking
As clients are interested in evaluating performance based on their objectives, tracking is embedded into
the ad units. It is ideal to track all interactions so that optimization opportunities can be readily
evaluated. It is also recommended to ensure that there is tracking established to each listing impression
and click, for deep evaluation into user views and interaction of offers.
Deep Linking
Link to listing item detail page
The ShopLocal key team members can guide Pointroll on appropriate deep links to the
SmartCircular site.
It is important to confirm if the client required adRef tracking in their deep link urls (this enables
tracking in the SmartCircular WebTrends account), and/or client custom tracking, such as
Omniture or DFA.
Link to circular page
General linking to landing page
Linking to ecommerce page
Content Timing
Circular Content Availability
Generally speaking, circular content for an upcoming ad is typically available to test just a few days prior
to the launch date. This is because the circular processing is on a schedule based upon the PDF assets
received from the client, and subsequent image and data entry processing to generate and quality check
the content.
Preview Hash
ShopLocal enables a preview hash feature, which allows a key to be generated to access data at a
specific time in the future. This data is not available to the public, this it is only available to those
granted a hash.
Preview hashes do expire, and should be requested to cover the entire test period for a given future
date.
If a preview hash remains in an api call after the content is live, it will be ignored (as live content is
publicly available, so the preview key is no longer required to access the date.
Content Strategies
Some standard discussion points for content strategies are identified below. The most commonplace
are: Obtaining store location via user zip code; Sorting listing by WoC; Selecting listing by key categories;
Selecting listings using Retailer Tagging.
-
-
-
-
Location
o National, or targeted markets
o Versioned content per market, or national un-versioned content
Category
o Display listings by category groupings
Brands
o Display listings by brand
Retailer Tags
o Explicitly selected content; can include very manual (the client manually selects
each listing to include) to fairly automated based on rules (only front page items
with a specified image quality, etc)
o Retailer Tagging requires data manipulation by ShopLocal operations.
All listings
Page Listings (ie: listings from page 1)
Promotion types
o It may be necessary to include or omit promotions by type (ie: if a retailer has
catalogs and circulars, pull only circular type)
Promotion codes
o
-
-
-
It may be necessary to explicitly obtain content for a particular promotion based on
code
Sneak Peek
o It may be necessary to use date logic or other flagging to exclude (or include) sneak
peek content
Images
o Availability
o Types
Count of listings
Sort order
Ad Unit Performance Expectations
Key performance indicators
-
Impressions
Interactions
Interactions rate
Clicks
Click through rate
Specific interaction tracking
Specific listing tracking
In Store Sales
Ecomm Sales
Other?
Campaign/Initiative Lifecycle
Pre-Kick Off
This may consist of emails and/or conference calls, and should include:
-
-
Identify key team members for client campaign. For ShopLocal this may include:
o Director, Partner Services
o Sales Director
o Client Services Director
o Operations Manager
Communicate initial knowledge about client’s campaign objectives and initial creative direction,
including any mocks, if they exist
Answer any initial questions such as
o Client’s promotion schedule in relation to the campaign
o Promotions / promotions types
o Content details/strategy
o
Client destination site(s), features and functionality as available
Kick-Off Call
This call may include the client, Partner, and ShopLocal key team members, and should serve to
establish/confirm:
-
Campaign/Initiative objectives
Shared understanding of content and content strategy
Initial creative elements to be included
Schedules for
o Initial mocks (if required)
o Creative assets
o Test content
o Ongoing pre-launch status meetings, if needed
Pre-launch - Partner Status Meetings
Internal checkpoint meetings for Partner/ShopLocal may be established as needed. These can be short
15 min meetings, serving like a stand-up. Frequency set by team depending on timing.
Pre-Launch - Client Status meetings
Client meetings with Partner and ShopLocal may be established as needed to ensure any
questions/updates/issues can be communicated and understood across teams.
Post-Launch - Performance Check Points
Post-launch, regular meetings may or may not be necessary. This depends on the campaign or initiative,
to be determined by the team.
Interim results should be provided to the ShopLocal key contacts.
Post-Launch Demo
For a campaign that has a limited life, oftentimes there are request to continue availability of a demo
after the campaign has ended. This requires two primary steps: 1) the campaignID powering the ad must
be enabled, and 2) there must be content available, based on the content strategy for the ad, in order to
populate it. If the client does not have a live circular, or if the specific categories/tag IDs, etc used to
power the ad are not available, it will be necessary to request content from ShopLocal operations.
Depending on complexity, time may be needed to enable required data.
Since localized deal content tends to be volatile and changing, the best recommendation is to create a
Demo Video which visually displays real content, features, and functionality of the product that was
built. Having a video will ensure that you can always revisit the demo without relying on appropriate
real-time content.
Campaign Wrap Up and Next Steps
A post-campaign wrap up with the client should include Partner and ShopLocal to gain shared
understanding of results, and identify opportunities for future campaigns.