Geodata ad feature – Amazon Ads Help Center

Note

Note: All of our ad features can be plugged into almost any ad format. For more information, see Amazon Ad Server ad formats.

Overview

The Geodata ad feature allows developers to acquire user location data through the built-in EB.API. Developers have access in the ad's code to a user’s country, city, region, and zip codes. In addition, there is access to a user’s latitude and longitude coordinates, values which can be passed into other features or APIs like weather, mapping, or store locator services. The Geodata ad feature is provided as a built-in service at no additional cost.

Bundle

Amz_GeoDataAdFeature_1_0_1_Bundle.zip

Files within the bundle:

README.txt

Amz_GeoDataAdFeature_1_0_1.zip

Included files:

File Name	Description	Required
`index.html`	HTML file for the banner.	Required
`config.js`	Configuration/Manifest file for the ad. Used for actions such as default ad settings, and dynamic creative.	Required
`styles/style.css`	Style sheet for the banner and its HTML elements.	Optional (if code is included in the HTML file)
`scripts/script.js`	JavaScript (logic and tracking) for the banner.	Required
`images/default.jpg`	Fallback image shown in unsupported browsers.	Required
`images/logo.png`	Logo	Optional

Prerequisite

AdKit loaded in a script tag in the <head> of the index.html file, and config.js file placed in the same folder as the main HTML file. Ads will not work without AdKit, or a config.js file, which for this ad feature needs to include only an empty define statement: define({});.
EB API Module should be included before AdKit in the <head> of the main HTML file, inside a script tag.

Supported operating systems and browsers

The following table shows the supported operating systems and browsers.

Operating System	Browser
Windows	IE 10+, Edge, Firefox, Chrome
Mac	Safari, Firefox, Chrome
iOS	iOS 8.0 and later
Android	Android 4 and later

Implementing the Geodata ad feature

The following steps describe how to obtain geo data from the EB.API in your creative Workspace.

Procedure

Add the EB.API module and AdKit to the head of your main HTML file.

<script type="text/javascript">EBModulesToLoad = ['EBAPI'];</script>
<script type="text/javascript" src="https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js"></script>

Create variables to store the data returned by the EB.API.

var countryCode;
var regionCode;
var cityCode;
var zipCode;
var latitude;
var longitude;

Check if AdKit is ready, and assign values from EB.API to the geo data variables created.

adkit.onReady(function() {  
countryCode = EB.API.Ad.getAdData("geoData").country; 
regionCode = EB.API.Ad.getAdData("geoData").region;  
cityCode = EB.API.Ad.getAdData("geoData").city;  
zipCode = EB.API.Ad.getAdData("geoData").zip;  
latitude = EB.API.Ad.getAdData("geoData").latitude;  
longitude = EB.API.Ad.getAdData("geoData").longitude;});

Use the geo data variables to display them in the ad, or pass them to, for example, a service, API, or feed.

Your ad can use the geo data parameters accessible through the EB.API as an input to any API or service that can intake these parameters. Examples include: mapping, weather, store locator services or APIs.

Note

Note: Geo data parameters can be accessed directly through the EB object as well, without including the EB.API module, although this is not recommended. The object holding all geo data parameters is EB._adConfig.geoData.

Known limitations

Access to geo data endpoints through the EB.API is available after the ad is built in Amazon Ad Server. When testing your ad locally, and to account for the fact that geo data cannot be retrieved locally, make sure to include failsafes in your code.
The EB.API on its own offers access to these geo data parameters:
- country code
- region code
- city code
- zip code
- latitude
- longitude

Note

Overview

Bundle

Prerequisite

Supported operating systems and browsers

Implementing the Geodata ad feature

Note

Known limitations

Comments