Purchase Tracking Web Service Technical Documentation Document Version 1.6 Revision date 02/28/2014
2 1 Overview The PriceSpider Where-to-Buy (WTB) is an online and local retailer locator. Manufacturers will implement a WTB on their website to redirect users to retailers websites. Often times, users will make purchases at these retailers websites as a direct referral from the WTB. Purchase Tracking Web Service enables online retailers who do not participate in commission-sharing programs, like Commission Junction or LinkShare, to submit details of the WTB-referred purchase to PriceSpider. Please note that purchases from users not redirected through a PriceSpider WTB cannot be submitted to this tracking service. The tracking is implemented on the order confirmation page, such as the Thank You page, after the order has been completed. 2 PriceSpider Redirect ID (PSRID) PriceSpider dynamically appends a unique redirect parameter and redirect ID (psrid) to every outbound URL from a PriceSpider WTB to a retailer s website. For example: http://www.myonlinestore.com/product/54321/?psrid=123456 The psrid is dynamically populated and will vary from session to session, and user to user. Once a user is redirected to a retailer s site, the psrid must be retained by the retailer s site for the entire duration of the user s session. When the user has completed their order, the psrid, as well as purchase details, must be passed from the Thank You order confirmation page to PriceSpider. 3 Submitting Purchase Details Purchase details should be submitted from the order confirmation page with the psrid to PriceSpider after the user has completed their order using either a tracking GIF pixel or a tracking script. 3.1 Tracking GIF Pixel Tracking GIF pixels are flexible and can be used with many web programming languages, such as PHP, JavaScript, CGI Scripting, ASP, Perl, and Java. Construct an <img> tag and programmatically populate the values in the parameters. The psrid needs to be retrieved and retained from the redirect URL in order to populate in the pixel URL source. The remaining parameters will need to be populated with sales data from the user s purchase. Example tracking GIF pixel: <img alt="." src="http://embedded.pricespider.com/purchase.gif?psrid=123456&date=2011-08- 30%2010:47am&purchaseTotal=128&d.1=sku=SKU01;mfg=MfgName1;productName=First%20Pro duct;unitprice=100.00;qty=1&d.2=sku=sku02; ;mfg=mfgname2;productname=second%20product;unitprice=14.00;qty=2" style="width:1px; height:1px" />
3 Parameters: Parameter values must be encoded. See section 3.3, Purchase Query Parameters for a list of optional and required parameters. Result: If the pixel URL source is accepted a 200 OK will be served with the image data for a blank 1x1 GIF image. Otherwise a 400 Bad Request will be returned if there are missing or badly formatted parameters. 3.2 Tracking Script The tracking script is an alternative approach to implementing the PriceSpider Purchase Tracking through JavaScript. It is based on the tracking GIF pixel, but removes the requirement to construct a proper pixel URL source. In addition, it offers the option to filter out order line items based on their manufacturer. This is a standalone script and does not require any additional third party libraries. The script must be programmatically populated with values in the parameters. The psrid needs to be retrieved and retained from the redirect URL in order to populate in the script. The remaining parameters will need to be populated with sales data from the user s purchase. Values should be programmatically populated in the tracking pixel. Below is a JavaScript illustrating the general concept of how this is done. This example is based on an order with two line-items, filtered to send purchase details for products manufacturer by ABC Co. only. Example of tracking script: <script type="text/javascript" src="//embedded.pricespider.com/repository/common/js/purchasetracking. js"></script> <script type="text/javascript"> // set order var order = { psrid: '123456', date: '2014-01-25 10:47am', purchasetotal: 61.98, currency: 'USD', detail: [] }; // set order details order.detail.push({ sku: '987654321', manufacturer: 'ABC Co.', name: 'ABC Co. Dictionary', unitprice: 4.99, qty: 1 }); order.detail.push({ sku: '012345678', manufacturer: 'XYZ Inc.', name: 'XYZ 123 Hammer', unitprice: 56.99,
4 }); qty: 1 pswtb.purchasetracking.submit(order, ['ABC', 'ABC Co.']); </script> To submit an unfiltered order, use: pswtb.purchasetracking.submit(order); To submit a filtered order (where certain products should be included or excluded based on the manufacturer), use: pswtb.purchasetracking.submit(order, ['ABC', 'ABC Co.']); Parameters: Do not encode parameter values. See section 3.3, Purchase Query Parameters for a list of optional and required parameters. Result: If there were errors during the submission of the order, the script will raise exceptions. 3.3 Purchase Query Parameters Both the full and short versions of the parameter names are acceptable in the tracking GIF pixel and tracking script. - All parameter values in the tracking GIF pixel must be URL encoded. - Parameter values do not need to be encoded in the tracking script. Parameter Short Type Description redirectid psrid Integer; The psrid which was passed to the seller upon rid redirecting the user through PriceSpider redirect date t Date or DateTime String; Optional engine to the seller s website. The date of the order expected must be in a yyyymm-dd hh:mm{am pm} format. Time is presumed PST. For example, if the date and time are January 1, 2014 at 10:47 am, send it in the expected format encoded as follows: currency c String; Optional purchasetota l orderdiscoun t detail.1 detail.2 detail.3 pt od d.1 d.2 d.3 Numeric; Numeric; Optional String; 2014-01-01%2010:47am The currency of the transaction. The accepted values are: USD, GBP, EURO, CAD. The default currency is USD. The order total before any final discounts. Can be decimals if purchase total has cents. The order discounts applied to the checkout total amount. Can be decimals if purchase total has cents. The detail parameters describe each line item from the order. Each contains a semi-column (;) delimited list of name-value pairs of detail describing each line item from the order. Example:
5 d.1=sku=sku01;productname=led%20tv;u nitprice=499;qty=1 For details, see Purchase Detail Parameters. Purchase Detail Parameters Parameter Short Type Description manufacturer mfg String; * The product s manufacturer or brand name. * for tracking script if excluding products by certain manufacturers. sku s String; The product s SKU. Manufacturer part number or UPC are preferable. productname n String; The product name. name Optional unitprice up Number; The unit price. Can be decimals if the unit price has cents. quantity qty q Integer; The quantity purchased. 4 Security All purchase tracking services support SSL (HTTPS) requests. PriceSpider does not return any executable content in the tracking responses and cannot obtain any additional information from the checkout page apart from what was intentionally passed through the tracking parameters. 5 Testing Manually trigger a test purchase, then let PriceSpider and/or the manufacturer you are working with know about this test purchase to make sure the implementation was successful. Please keep in mind that even if a call was made successfully with the test purchase, the details themselves need to be verified. For example, if the call included two purchases but PriceSpider is only sent the first purchase, then the syntax may need review. 6 Implementation Considerations During the implementation process of purchase tracking on your site, there are a few things you may need to watch out for to make sure the purchase details are passed from your site to PriceSpider. 6.1 Excluding Purchase Details It is preferable that purchase details for the entire order are sent in the call, but if there are restrictions on what details can be sent, feel free to only include certain purchase details as they
6 align with your company s business rules. For example, if you would like to include details for products made by Manufacturer A, but exclude details for products made by Manufacturers B, you will need logic in place that only populates the call with details for Manufacturer A s products. The actual implementation will vary based on the programming languages and web platforms used. Please keep in mind that the totals for quantity and price must reflect the total of only the purchase details in the call. For example, if three items were purchased in one order, but you only want to send us details for one of those items, the total price and total quantity must be only for that one item. 6.2 Purchase Details Provided Only data from the purchase details provided directly through the tracking GIF pixel will be sent to PriceSpider. For example, if PriceSpider is only passed the product name, quantity, and price of the purchased product(s), only those three pieces of information will be known to us. Likewise, if we are not passed the product name, we will not have this data in our system. 6.3 Syntax If incorrect syntax or unknown parameters are used, the tracking call may not be successful and result in no details or incorrect details being passed to PriceSpider. 6.4 Dynamic PSRIDs The psrid is not static. The psrid is unique to every user session and is retrieved directly from the redirect URL. Please make sure your website is able to retrieve the psrid every time a user visits your website. 6.5 Retrieving PSRIDs Since users have a tendency to navigate many webpages on a retailer s website, the psrid must be retrieved from the redirect URL and saved until the user places an order. At this point, the psrid and purchase details should be sent to PriceSpider directly from the order confirmation page.