This article shows how to create dynamic admedia based on the contextual product search, which is part of the zanox Web Services. In general you can follow a server-side or client-side approach. Here we will do this client-side using JS, so all API calls are done by the visitors browser and you don’t need any serious code running on a web-server. This way it’s easy to adopt and integrate it into your next webpage-, blog- or widgets-project.
To develop a dynamic ad, we will take the following steps:
- Creating zanox Web Services credentials
- RESTful products resource & contextual product search
- Crossdomain: Calling zanox Web Services using JSONP
- Parse response data
1. Creating zanox Web Services credentials
Login to zanox, click on the new tab “Web Services BETA”. At the Web Services tab, create a new applicationId or grab an existing one. In this article, we just need the applicationId. The applicationId is responsible to get your tracking codes into the dynamic ads. You can make it public but don’t do this with your sharedKey, it’s nearly as mighty as your password.
Please note: If you don’t have an account yet, you have to register to continue. The first time using the Web Services tab, you have to press an apply for “zanox Web Services”-button and to re-enter the Web Services tab again.
2. RESTful products resource & contextual product search
zanox Web Services offer the same functionality for SOAP, REST-XML and REST-JSON, so you can choose case by case what’s matching your requirements. We’re going to use Java Script in our case, so we take the REST-JSON API. The products resource supports the simple URL parameter authentification, which allows to append the applicationId as a URL parameter. To give it a try, just type the following into your browser and replace ABC123 with your applicationId:
http://api.zanox.com/json/products?applicationid=ABC123&q=jeans
The response contains then number of products matching the query and by default shows the first 10 items. For each item there is at least name, price, description, up to three images available. In addition category and EAN if available.
The parameter “q” defines the search query. You can search for products by using a short string or a name of a product, or by using a longer text phrase for contextual matching. To specify the search, there are some more parameters like region, minPrice, maxPrice, category and programs and adspace.
Read more about the products resource in the zanox wiki:
http://wiki.zanox.com/en/Products_Resource#GET:_Contextual_product_search
3. Crossdomain: Calling zanox Web Services using JSONP
In our client-side scenario, the API calls to api.zanox.com are done by the browser of the visitors of your website. To support this scenario, zanox Web Services support JSONP. You just pass the name of a Java Script callback handler function as a parameter when calling the zanox Web Services. The JSON result is wrapped into a Java Script function call.
The idas is to implement the handler function and perform the API-call as a script refenrence from your web page:
< script src="http://api.zanox.com/json/products?applicationid=ABC123&q=jeans&callback=handler" > < / script >
The response will be a call of a function name “handler” and look like this:
handler(...json result of the query…);
To make it more dynamically, you can use the following helper function to add a script reference to your website:
function addScript(url) {
var script = document.createElement(“script”);
script.src = url + ‘&t=’+new Date().getMinutes();
script.type = “text/javascript”;
document.getElementsByTagName(“head”)[0].appendChild(script);
}
Using this helper function, all the functionality of the contextual product search is already implemented in JS:
function productSearch(version, applicationid, adspace, region, programs, minPrice, maxPrice, category, page, items, q, callback) {
var url = ‘http://api.zanox.com/json/’ + version + ‘/products?applicationid=’ + applicationid;
if (adspace) url += ‘&adspace=’ + adspace;
if (region) url += ‘®ion=’ + region;
if (programs) url += ‘&programs=’ + programs;
if (category) url += ‘&category=’ + category;
if (page) url += ‘&page=’ + page;
if (items) url += ‘&items=’ + items;
if (minPrice) url += ‘&minPrice=’ + minPrice;
if (maxPrice) url += ‘&maxPrice=’ + maxPrice;
if (callback) url += ‘&callback=’ + callback;
if (q) url += ‘&q=’ + q; addScript(url);
}
Read more about the Java Script helper functions and examples at:
http://wiki.zanox.com/en/JavaScript_Client_Library
4. Parse response data
In order to render the product search response, we have to access the product Items inside of the JSON response. You can just use the following lines of code:
function handler(data) {
if (data.productsResult) {
var productItems = data.productsResult.productItem;
for (var i = 0; i < productItems.length; i++) {
var productItem = productItems[i];
//..do something with productItem
}
}
}
So have fun with this code snippets, I hope this helps you creating widgets and gives you some ideas of integrating our contextual product search into your websites. Feel free to comment some of your implementations in our blog.
A lot of ideas whir around here for Web Service code examples. But we have to focus on the development of the Web Services. Nevertheless some nitty gritty pieces of software are to be found in the zanox Web Services Wiki. There is a special section “Quick-Start Tutorials” growing day by day. We would like to encourage you to provide some code examples to the zanox Web Service Developer community. Today we picked these three examples.
Permalink
