Aptimus Advertiser Specifications

XML Transformation

Overview
This document details the Aptimus 'Private Label' XML integration including the various integration options and data descriptions.

Offer Request:

For each consumer visit a request will be made to the Aptimus HTTPHandlerServlet, returning Aptimus XML data with all information necessary to present Aptimus offers on your site.
Example: http://network.aptimus.com/AptiNet/HTTPHandlerServlet?pid={APTIMUS_TO_PROVIDE}&page=pvlmain&output=text/xml
If consumer information is avaiable prior to the Aptimus offer request this information should be appended to the request URL for targeting and optimization (GET/POST).
Standard Optimization Parameters:
postal_code (XXXXX-XXXX)
gender (M/F)
birthday_day_drop (DD), birthday_month_drop (MM), birthday_year (YYYY)
Contained within the XML are each offer's image paths, copy and data collection information (parameters). As you see in the XML example link above, each offer's details are contained within the <OFFERLIST> nodes.
We typicaly present each offer using the offer <TITLE>, <SHORT_DESCRIPTION>, <MEDIA TYPE="120x90">. Here is an example of the Aptimus display: View

Order/Data Transfer:

There are two types of offers, those containing a REDIRECTHREF in the REDIRECT node (Redirect Offer Type), and those that do not (Standard Offer Type). Each Standard Offer Type requires data collection, as detailed in the <OFFER_QUESTIONS> node and <FIELD> tags. Registration data captured for Standard offer Types will be submitted to an Aptimus servlet, whereas the Redirect Offers do not require data collection and will NOT be submitted to the Aptimus servlet; Instead Redirect Offers will be submitted to a pop-up window using the REDIRECTHREF.
The servlet used for the Standard Offer Type, the OrderAction servlet, expects all required <FIELDSET> data to be transfered via a form GET/POST.
The URL for Standard Offer Type data submittal is: https://network.aptimus.com/AptiNet/OrderAction
In addition to the offer question field set, you will need to submit the following parameters to the OrderAction page:
Parameter Name: poid, Parameter Value: (POID value in the OFFER node)
Parameter Name: position, Parameter Value: (POID|POSITION values from the offer node, concatenated and seperated by a vertical bar)
Parameter Name: page, Parameter Value: orderconfirm
Parameter Name: output, Parameter Value: text/xml
Parameter Name: ipaddr, Parameter Value: (Consumer IP Address)
Parameter Name: transdate, Parameter Value: (YYYYMMDD.HH:MI:SS, required only for orders submitted in batch)

Alternate Order Collection, Aptimus Hosting:

Conversely, Aptimus can host the order processing and validation. With this option offer(s) selected by each consumer are passed to an Aptimus page along with any user data collected for pre-population. The Aptimus data page can be launched in the current broswer window or within a pop-up, In addtion, the Aptimus page can be set-up using your site colors and branding details for a seamless look and feel.
Example Request: http://network.aptimus.com/AptiNet/HTTPHandlerServlet?page={APTIMUS_TO_PROVIDE}&poid={OFFER_SELECTED}
Standard Pre-population Parameters:
first_name
last_name
email_address
address
address_2
city
state (XX)
postal_code (XXXXX-XXXX)
gender (M/F)

Order Response:

Every GET/POST to the 'OrderAction' page will return an XML reponse page containing 'ORDER' tags for each order submitted. Within the 'ORDER' tag will be an 'ORDER_RESULT' with a 'TYPE' value of either "SUCCESS" or "FAILURE" for each submittal.
Order Response XML Example (See bottom of document)
If the 'TYPE' is "FAILURE" there will be a 'DESCRIPTION' parameter with the error information to be displayed to the consumer.

Example:
<ORDER_RESULT DESCRIPTION="One or more of the following answers are invalid or missing. Please double check your Second Mortgage Balance. This can not exceed the Home Value. Unable to record order." TYPE="FAILURE" />

As you see above, there is only one order result description, whereas there may be many errors on an order submittal. Given this, each order submitted will also contain a listing of each question, again within the 'ORDER' tag. Each question with an error will contain the parameters, 'INVALID', 'INVALIDLABEL' and 'INVALIDMESSAGE'.

Example:
<ANSWER ATTRIBUTEID="1172" FIELDID="13352" INVALID="INVALID" INVALIDLABEL="Rate" INVALIDMESSAGE="Answer appears to be invalid." PARAMETERNAME="rate1|12_8681_7_23|13352" PARAMETERVALUE="10%" />

Typically the invalid question is highlighted (in red) and the INVALIDMESSAGE is displayed on the top of the data collection page.
If the order is successful the 'ANSWER' attributes will not contain the 'INVALID="INVALID"' parameter, and the 'ORDER_RESULT' tag will only contain a 'TYPE' value of "SUCCESS".

Example:
<ORDER_RESULT TYPE="SUCCESS" />

Cross-Sell Offers:

The Order Response XML (as detailed on the previous page), returns 3 targeted cross-sell offers. The format of these offers is the same as the offers in the primary request. Each upsell offer is contained within the <OFFERLIST> nodes.

Typically cross-sell offers are presented on an success page below the ORDER_RESULT messages. The order process for these cross-sells should be the same method as choosen for the standard offer display.