PRODUCT
Follow

Overview

Introduction and Screenshots

The HTML5 Store Locator Ad Feature that lets you search for the closest stores based on a user’s location via GPS, zip code or city, state. The default mapping service uses Leaflet to display the results within a map in the ad, but you can also select Google Maps or MapQuest Maps to customize your ad.

Important: Please note that the Store Locator is a Premium Ad Feature and requires a Creative Service Engineer or other Sizmek Account Representative to assist in setting up the Store Locator backend. Please refer to the Setting Up Your Store Locator in Gizmo section for more information. 

Additionally, while the default map service, Leaflet, is free, using either the Google or MapQuest mapping services will require a working API key. Failing to do so could result in capping responses from both Google or MapQuest. Please see the following for prices and plans:

This guide describes how to use any of these mapping services. As part of this ad feature, we offer four total options:

  • Store Locator utilizing Leaflet Maps to map out the closest locations.
  • Store Locator utilizing Google Maps to map out the closest locations.
  • Store Locator utilizing MapQuest Maps to map out the closest locations.
  • Store Locator List to provide a scrollable text list of the closest locations (no maps).

The following illustration shows the Store Locator feature. Users can enter their ZIP codes, City, State or use their current location and click FIND to interact with the feature. 

                                                   

The feature can also show users a scrollable list of the nearest stores to their location, or plot them on Leaflet Maps as follows.

     

Additionally, similar mapping functionality may be shown using the Google Maps or MapQuest map as shown below.

     

After the map or list results are returned, you’ll be able to get directions to any of the closest locations returned.  Furthermore, you will have the option to go back and enter either a new zip code, city or select your current location. 

This feature uses the Sizmek Gizmo service to store online location information for all three map providers. 

Demos/Downloads

The following table provides links to the template and demo for the HTML5 Store Locator Ad feature.

Template

store_locator_6_0_0.zip

Demo

Preview Demo

Supported Platforms

Platform

Supported Version

Windows

Internet Explorer 10+, Edge, Firefox, Chrome, Safari

Mac

Firefox, Chrome, Safari

iPhone

iOS 8.0 and later

iPad

iOS 8.0 and later

Android

Android 4.1 and later( including tablets)

 

Ad Feature's creative environment capabilities comparison

Functionality Ad builder Workspace
SAS Support Yes Yes
Responsive Scaling Yes Yes
Full Responsive Support No Yes
Google Maps Yes Yes
Leaflet  No Yes
Mapquest  No Yes
List View No Yes
Search by Postal Code  Yes Yes
Search by User Location Yes Yes
Search by City, State Yes Yes
Max Number of Results No Yes
Ad Size Impacted by Number of Stores* Yes No
Store Directions Yes Yes
Premium Cost Yes Yes

 *Workspace version does not require the full .csv to be loaded into the ad and count against the total ad size.

Assets

Workspaces Available

The HTML5 Store Locator Ad Feature includes four HTML5 Workspaces built using the HTML5 Polite Banner. 

Included Workspace Files

Leaflet Template

Filename

Description

images/backup.jpg

Sizmek Ad Feature default backup Image and demo background

images/locator.png

Sizmek Ad Feature demo images

images/main.jpg

Sizmek Ad Feature demo images

index.html

Sizmek Ad Feature HTML file.

store_locator/modules/leafletModule.js

Store Locator Leaflet maps script file

store_locator/store_locator_ui_images/loader.gif

Sizmek Ad Feature demo image

store_locator/store_locator_ui_images/sprite.png

Map Controls

store_locator/store_locator.css

Store Locator Stylesheet

store_locator/store_locator.js

Store Locator Javascript file

 

Google Template

Filename

Description

images/backup.jpg

Sizmek Ad Feature default backup Image and demo background

images/locator.png

Sizmek Ad Feature demo images

images/main.jpg

Sizmek Ad Feature demo images

index.html

Sizmek Ad Feature HTML file.

store_locator/modules/googleModule.js

Store Locator Google maps script file

store_locator/store_locator_ui_images/loader.gif

Sizmek Ad Feature demo image

store_locator/store_locator_ui_images/sprite.png

Map Controls

store_locator/store_locator.css

Store Locator Stylesheet

store_locator/store_locator.js

Store Locator Javascript file

 

MapQuest Template

Filename

Description

images/backup.jpg

Sizmek Ad Feature default backup Image and demo background

images/locator.png

Sizmek Ad Feature demo images

images/main.jpg

Sizmek Ad Feature demo images

index.html

Sizmek Ad Feature HTML file.

store_locator/modules/mapquestModule.js

Store Locator MapQuest maps script file

store_locator/store_locator_ui_images/loader.gif

Sizmek Ad Feature demo image

store_locator/store_locator_ui_images/sprite.png

Map Controls

store_locator/store_locator.css

Store Locator Stylesheet

store_locator/store_locator.js

Store Locator Javascript file

 

List Template

Filename

Description

images/backup.jpg

Sizmek Ad Feature default backup Image and demo background

images/locator.png

Sizmek Ad Feature demo images

images/main.jpg

Sizmek Ad Feature demo images

index.html

Sizmek Ad Feature HTML file.

store_locator/modules/listModule.js

Store Locator List script file

store_locator/modules/jquery.tinyscrollbar.min.js

Sizmek Ad Feature jQuery file for scroll bar

store_locator/store_locator_ui_images/loader.gif

Sizmek Ad Feature demo image

store_locator/store_locator_ui_images/sprite.png

Map Controls

store_locator/store_locator.css

Store Locator Stylesheet

store_locator/store_locator.js

Store Locator Javascript file 

 

Implementing the Ad Feature

How to Add the Ad Feature to your Workspace Code

Procedure

The following steps illustrate how to add the Store Locator Ad Feature to your creative Workspace.

  1. Add the following to the head of your index file including the EBAPI component. The EBAPI component in necessary for location services to work properly.

         Note: The file path has been shortened for simplification.


    <script> EBModulesToLoad = ['EBAPI'];<script>
    <script type="text/javascript" src="http://ds.serving-sys.com/…/adkit.js"><script>
    <script language="JavaScript" src="store_locator/store_locator.js"><script>

  1. Listen for adkit.onReady.
    <script type="text/javascript">
        adkit.onReady(function(){...};);
    </script>

  1. Add and edit the following code to add the Store Locator Config object to your HTML’s body element. Included is the id of the div you wish to place your store locator, the width and height of your store locator and the id for the Gizmo account for your store locator. Then we instantiate and pass the config object to the store locator script.
    <script type="text/javascript">
	var myStoreLocatorConfig = {
		container: "storeLocator",
		width: 290,
		height: 240,
		hostedDataTable: "XXX",
		actionRegister: function(){
			EB.userActionCounter("Store_Locator_SearchByUserInput");
			EB.userActionCounter("Store_Locator_SearchByUserLocation");
			EB.userActionCounter("Store_Locator_LocationMarkerClicked");
			EB.clickthrough("Store_Locator_GetDirectionsClicked");
		}
	};
	var myStoreLocator = new StoreLocator(myStoreLocatorConfig);
    </script>

Configurations 

Property

Type

Description

Default

container

String

Id of div container

“storeLocator”

width

Number

Width of Store Locator container div. Enter 0 on both height and width full-screen map 290

height

Number

Height of Store Locator container div. Enter 0 on both height and width full-screen map 240

hostedDataTable

Number

The unique id of the Gizmo API service you have been issued  

 Customizations

  1. Customize your Store Locator landing div by editing the following two lines in the code pasted in step 2.

         <div id=”storeLocator”></div> (remove)

          container: “storeLocator”, (edit)

        Edit “storeLocator” to the div id you plan for your Store Locator to load.

Note: All contents of the div will be replaced by the Store Locator content.

  1. Customize your Store Locator configuration variable by editing the following two lines in the code pasted in the following step.

         var myStoreLocatorConfig = {

         var myStoreLocator = new StoreLocator(myStoreLocatorConfig);

         Edit the “myStoreLocatorConfig” to the name you prefer. 

  1. Customize your Store Locator event name. The Event name can be customized by changing the event name prefix. To do so, edit the following four lines of the code pasted in the following step.

        EB.userActionCounter("Store_Locator_SearchByUserInput");

        EB.userActionCounter("Store_Locator_SearchByUserLocation");                                            

        EB.userActionCounter("Store_Locator_LocationMarkerClicked");                                  

        EB.clickthrough("Store_Locator_GetDirectionsClicked");

           Edit “Store_Locator” to the name you prefer.    

Note: You MUST add eventNamePrefix to the options if you change the name prefix. 

  1. Customize your Store Locator by adding options and templates. Change the following configurations as needed. The configuration will construct in the following format:
     <script type="text/javascript">
	
        var myStoreLocatorConfig = {
            container: "storeLocator",
	    width: 290,
	    height: 240,
	    apikey: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	    hostedDataTable: "XXXXXX_XXXXXXXXXXXXXX",
	    actionRegister: function(){
		EB.userActionCounter("Store_Locator_SearchByUserInput");
		EB.userActionCounter("Store_Locator_SearchByUserLocation");
		EB.userActionCounter("Store_Locator_LocationMarkerClicked");
		EB.clickthrough("Store_Locator_GetDirectionsClicked");
	    },
            options: {
               maxMatches: 3,
               eventNamePrefix: “myStoreLocator”
            },
            templates: {
               getDirections: “Get Directions”,
            }
          };
    </script>

Available Options

Options

Type

Description

Default

zipCodeValidation

Boolean

Verify the user input is valid US zip code before a search, the default is false. Set this to true if you only allow the user to search location using a zip code.

False

countryCode

String

Enter the ISO Country Code if you want to force the Store Locator to search a specific country. By default, Sizmek uses the built in Geo Data to determine the country from which the user is searching; however, using this option allows you to override that default. Ex. Enter "840" to search the US market only. Enter "276" to search the German market only.

If this option is not included, the user's country code is automatically determined by the API. 

maxMatches

Integer

Number of max search results will be displayed. 3

radius

Integer

The radius of search in miles. 20

eventNamePrefix

String

The prefix of the custom click through event name and user interaction name. Store_Locator

displayMap

String

Define which maps service should be used for search results.

Available options are:

  • mapquest: MapQuest Map
  • google: Google Map
  • leaflet: Leaflet Map
  • none: List Only
Mapquest

directionsService

String

Define which directions service should be used when clicking on Get Directions in search results.

Available options are:

  • mapquest: MapQuest Directions
  • google: Google Directions 

* This option only available for Leaflet and List version.  When "displayMap" is "mapquest", the "directionsService" will force to use mapquest only; when "displayMap" is "google", the "directionsService" will force to use google only. 

mapquest

(google if "displayMap" is set to google, and google if iOS)

initialZoom

Integer

The initial zoom level of the results map.

10

panDistance

Integer

The number of pixels of the pan distance when use customized pan buttons.

100

numberedMarker

Boolean

Show number on location marker based on the distance to the search location.

false

(true for the MapQuest)

markerIcon

String

The image path to the marker, use this to customize your location marker, for a numbered marker, use {n} for the number, for example: "poi-{n}.png", {n} will be replaced with the number from search results.

 

zoomControl

Boolean

Show the zoom control from map API.

false

zoomControlPosition

String

Zoom control position supports following:

"TL" for top left

"TR" for top right

"BL" for bottom left

"BR": for bottom right

TL

customZoomControl

Boolean

Show custom zoom control buttons.

false

panControl

Boolean

Show custom pan control buttons.

false

closeControl

Boolean

Show custom close map button.

false

mouseHoverInfo

Boolean

Display info window when the mouse hovers over the location marker.

* This is MapQuest version only. The mouse hover event will conflict with the click event on mobile devices, so we design to turn this off, if your ad is for desktop only, you can set this option to true to turn on the mouse hover info.

false

customScrollbar

Boolean

Use custom scrollbar for the list result.

false

scrollbarWidth

Integer

The width of the custom scrollbar.

12

scrollbarTrackColor

String

The color of the custom scrollbar track

#beedfc

scrollbarHandlerColor

String

The color of the custom scrollbar handler

#3fc2ec

googleMapKey

String

API key for Google Map. This is required if your Store Locator is using Google Map.

 

searchEngagedCallback

Function

The function that will be triggered when search engaged.

 

showMapCallback

Function

The function that will be triggered when search results are shown.

* This applies to both Map and List versions

 

showMessageCallback

Function

The function that will be triggered when message shown

 

collapseMapCallback

Function

The function that will be triggered when map closed.

* This applies to both Map and List versions

 

collapseMessageCallback

Function

The function that will be triggered when message closed

 

  1. Customize your Store Locator by editing the CSS in store_locator/store_locator.css

Available Styles

Style

Description

.storeLocator.mapStage<c/ode>

The style of inner div that writes the Store Locator Block.

.storeLocator.mapLoader

Style for loading image.

.storeLocator.infoWindow

Style for info window. (List item for List)

.storeLocator. collapseMapButton

The style for close map button.

.storeLocator.zoomInButton

Style for custom zoom-in control button.

.storeLocator.zoomOutButton

Style for custom zoom-out control button.

.storeLocator.panEastButton

Style for custom pan east control button.

.storeLocator.panWeatButton

Style for custom pan west control button.

.storeLocator.panNorthButton

Style for a custom pan north control button.

.storeLocator.panSouthButton

Style for custom pan south control button.

.storeLocator.messageWindow

Style for message pop-up.

.storeLocator.userLocationFailed

Style for user location failed message.

.storeLocator.closeMessage

Style for close message button.

.storeLocator.multiMatchesFound

Style for "multiple matches found" message.

.storeLocator.noMatchesFound

Style for "no matches found" message.

.storeLocator.invalidZipCode

Style for "invalid zip code" message.

.storeLocator.tryAgain

Style for try again button.

  1. Customize your Store Locator by adding options and templates. Change the following configurations as needed. The configuration will construct in the following format:

    <script type="text/javascript">
	
        var myStoreLocatorConfig = {
            container: "storeLocator",
	    width: 290,
	    height: 240,
	    apikey: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	    hostedDataTable: "XXXXXX_XXXXXXXXXXXXXX",
	    actionRegister: function(){
		EB.userActionCounter("Store_Locator_SearchByUserInput");
		EB.userActionCounter("Store_Locator_SearchByUserLocation");
		EB.userActionCounter("Store_Locator_LocationMarkerClicked");
		EB.clickthrough("Store_Locator_GetDirectionsClicked");
	    },
            customCSS: [
               “.storeLocator.mapStage = .myStage”,
		“.storeLocator.mapLoader = .myMapLoader”

            ]
          };
    </script>

The customCSS is an array contains the element using the format of [DEFAULT_CSS_NAME] = [CUSTOM_CSS_NAME]. For available styles, please refers to this step.

Available Methods

Method

Description

search

Search the location with supplied parameter. You may pass a zip code as a parameter so the function will search the location based on the zip code; you may also pass a “location” string so the function will search based on current user location. For example:

  • myStoreLocator.search(10019);
  • myStoreLocator.search("location");

showMap

Show the resulting map.

hideMap

Hide the resulting map.

collapseMap

Collapse result map and clear all the result map contents.

showPanControl

Show custom pan buttons.

hidePanControl

Hide custom pan buttons.

showCustomZoomControl

Show custom zoom buttons.

hideCustomZoomControl

Hide custom zoom buttons.

showCloseControl

Show custom close map button.

hideCloseControl

Hide custom close map button.

Common Customizations

Configuring Search Results

By default, the Store Locator returns three store locations within a radius of 20 miles. However, this can be changed by updating the "maxMatches" and "radius" properties. For example, the Store Locator will return up to 10 locations within 40 miles if the "maxMatches" and radius are changed to 10 and 40 respectively. 

Configuring the Map Tiles

The mapping service used to display results depends on the Store Locator template you chose. For instance, if you prefer to use Leaflet to display results, you must either start with the Leaflet template provided or update "displayMap" in the Store Locator config object to "leaflet" and include the corresponding leafletModule.js file in the modules directory.

Configuring Direction Services

By default, when using the Google and MapQuest map templates, the directions services will use Google Directions and MapQuest Directions respectively. However, if you choose the Leaflet or List template, unless you choose otherwise, the default will be MapQuest. For those two templates, you have the option to choose either Google or MapQuest Directions services by updating the "directionsService" property.

Configuring the Location Marker

Each Mapping service has their own unique marker icon but an option is provided that allows you to update it with a customized image, for example, a different color or company logo. To update this image, edit the "markerIcon" with the image path to the image you would like to use.

Setting Up Your Store Locations in the Sizmek Gizmo Service

The HTML5 Store Locator is a Premium Ad Feature as it requires the use of third party services and may incur additional fees. In addition to third party mapping services, the Store Locator uses Sizmek's Gizmo, a full-service feature provided to our clients, that we use to maintain store locations.

Please note that when using the Store Locator Ad Feature, an additionally call to the Gizmo servers will be fired per search. 

To complete the setup of your Store Locator, an account must be created and your store locations entered into your Gizmo account. Please contact your Sizmek Creative Services Engineer or Account Representative and ask them to create a QB request including the necessary data and required fields (name, address, city, state, postal code) to do the geocoding, in an excel or CSV file. 

Custom Interactions

Interaction Name

Description

Store_Locator_SearchByUserInput

User search location by input a zip code

Store_Locator_SearchByUserLocation

User search location by using user location

Store_Locator_LocationMarkerClicked

User click on location marker from search results map

Store_Locator_GetDirectionsClicked

User click on Get Directions link

 

Direction Services

Please note that by default, the Get Directions link will open in Google Maps when the Google Maps tiles are used and MapQuest will open when MapQuest tiles are used. When using an Android device, the Get Directions link will open in the Google Maps app. When using the Leaflet or List template, developers have the option of choosing Google or MapQuest by using the "directionsService" option. 

Using Google Maps

When using the Google Maps template, it is important to update your Google credentials with our server information. Do so by logging into your google account API Manager and under Credentials > Key Restrictions, enter the Sizmek server domain names so that the service can only be used when served from the Sizmek servers.

storelocator.jpg

Known Issues

  • Local Preview will not work for the demo - must view panel only.
  • Local Preview only works for zip code search.
  • Local Preview does not work for MapQuest Template.
  • Searching for City State may return results from outside the country searching if results fall within proximity provided
  • Searching for City name may return similar names from different countries. Ex: Searching for Berlin may return results for Germany and the United States if proximity allows and data exists. 
  • MapQuest map is not responsive. You need to resize map as page resizes. 
  • Page scrolls slightly (momentum scrolling) in iOS when scrolling List template results. 
  • In some Android devices, MapQuest map can't be moved by finger touch. It can only be zoomed in or out by "+" or "-". User can't drag the map up or down, left or right.

Change Log

September 1, 2017

  • Updated Zip Code verification to include postal codes for Germany, Canada, and the UK 
  • Switched to using EB.API for location services removing the need for user permission for Geo Location
  • Added Map Responsiveness
  • Overall performance issues

 

February 8, 2017

  • Added option for country code override 
  • Added option for full width and height map 
  • Fixed bug that caused map to fail to load on the second load when using the Leaflet module

December 10, 2016

  • Updated for adkit
  • Updated for secure protocol
  • Updated to use Gizmo as backend location provider

 

March 4, 2016

  • Added Ad Feature Tracking 

February 25, 2016

  • Updated steps for entering Store Location data into new MapQuest site changes.

April 7, 2015

  • Branding updates
  • Added note regarding usage (implement on expanded state only)

 

April 23, 2014

  • Updated to use MapQuest V2 API
  • Improved search capabilities to include City Search (the previous release included GPS and zip code only)
  • Sizmek rebranding

 

May 22, 2013

Initial Release

 

Was this article helpful?
0 out of 1 found this helpful
Have more questions? Submit a request

Comments