Sales tracking

Background

The Sales tracking API works by embedding different tracking 1x1 pixel images (Targets) on your website at different strategic places.

Points where these targets would make sense is often at the end of a given transaction. That could be:

  • After a completed signup (e.g. to an event or competition)
  • After a completed sale

The targets can be configured through the Ubivox system by going to Statistics then Targets in the top menu.

Adding sales numbers

If you are tracking sales, you might want to track the amounts in order to track the total sales or turnover generated by your newsletters.

Sales numbers can be added to the newsletters statistics by extending the normal image URL with these query string (GET) parameters:

Parameter Description Example
st_revenue The revenue from the transaction st_revenue=49.95
st_quantity Items in the transaction st_quantity=2
st_currency Currency of the transaction st_currency=USD
st_reference Transaction reference (unique) st_reference=12345678

Parameter details

  • At least one of st_revenue or st_quantity is required
  • Use period as decimal separator and do not use thousands separators. Decimals are optional. Valid examples: 5, 49.95, 14999.95.
  • Maximum trackable revenue amount is: 99999999.99.
  • The st_reference parameter is built to identify specific transactions or registrations hitting the target. The reference has to be unique (e.g. an order number); if we register multiple target hits with the same reference, only the first hit will be registered. The reference may be both numerical or text but has to be unique. (Maximum length: 100 characters)

Example

A full example of a target with added sales tracking details, could look like this:

<img src="https://example.clients.ubivox.com/target/<target_id>/?st_revenue=49.95&st_quantity=2&st_currency=USD&st_reference=12345678" height="1" width="1">

Ecommerce Tracking

If your account supports the Ecommerce Tracking API, you gain the option of registering each individual product in the set of products for each order as well as being able to segment on those products.

Parameter details

There’s multiple ways for the order data to enter the system, but all of them uses this common set of parameters.

Order parameters

et_products (required)
How many products are in the order.
et_currency (required)
What currency was the order made in. Use Upper case ISO 4217 three letter codes. Example: USD, DKK or GBP
et_customer_ref (required)
Your customer reference. Should uniqely identify the customer at your end.
et_order_ref (required)
Your order reference. Should uniqely identify the order at your end.
et_point_of_sale (optional)
Annotate the order with the point of sale for the transaction. Example: webshop.
et_added (optional)
If the order time is not simultaneous with the parameter generation, annotate the order with a RFC3339/ISO8601 timestamp to use for order If not time zone offset is included, UTC is assumed. Example: 2017-05-23T13:38:12+00:00.

Product parameters

For each product in the order, you need these parameters. Replace i with a zero indexed counter.

et_prod_i_id (required)
A unique product ID should never change for a product. If we see a different product (name, category) at a later time with the same product ID, we will update the earlier orders as well. This will allow you to propagate changes to the system.
et_prod_i_quantity (required)
How many instances of the product was sold.
et_prod_i_name (required)
The product name.
et_prod_i_category (required)
A comma separated list of categories for this product.
et_prod_i_unit_price (required)
The unit price of the product formatted as 12345.67.

Example parameter set

Here is an example parameter set of an order with two products with a total of seven items.

Key Value
et_customer_ref HS99332
et_order_ref 995AB220
et_point_of_sale webshop
et_currency USD
et_products 2
et_prod_0_id 9040493329
et_prod_0_quantity 5
et_prod_0_category socks,mens
et_prod_0_name Mens black socks
et_prod_0_unit_price 0.89
et_prod_1_id 8584922943
et_prod_1_quantity 2
et_prod_1_category tshirts,mens
et_prod_1_name Mens red tshirt
et_prod_1_unit_price 1.19

Sending order data using the XML-RPC API

The first, and recommended option, is to send the order data using the XML-RPC API. A complete integration consists of the following steps:

  1. On the order confirmation page (after the sale is done), call the mailer.ecommerce_tracking_html() API method to retrieve a HTML snippet that must be printed on the page.

    This call must be made for each order (may even be called multiple time per order) as this snippet will be configured for this particular customer and order. It will be both encrypted and tampering-proof, so you wont accidentally leak any details.

    The HTML snippet will be a small 1x1 transparent GIF image to allow us to read a tracking cookie that may have been set when your subscriber clicked a link in a newsletter on your account.

  2. At your decision, call the API method mailer.ecommerce_tracking_new_order() either during the ordering process or at a later time. The sooner you call this, the sooner you will have the data available in the system for segmentation and analytics.

    The params parameter of the XML-RPC method, is an XML-RPC struct with the above parameters.

    This step is completely server side and thus is not prone to blocking or tampering by the client.

  3. In case your customer cancels their order, consider marking it as such in our data as well, so you don’t risk ending up sending out unsolicited follow-up e-mails for your customer’s orders.

    This is done by calling mailer.ecommerce_tracking_cancel_order() as soon as possible after the order has been cancelled.

If you complete thise steps, we will be able to associate the sale with the:

  • Contact
  • Subscription
  • List
  • Newsletter
  • Link

The contact does not need to have a subscription to your newsletter yet. We will still store the data in your account and if the contact at some point subscribes to your newsletter, you will have all of the sales history available.

It is possible to only implement step 2, but then you will not be able to track sales to specific newsletters and links. Furthermore, if you don’t implement step 3, you might risk accidentally sending unwanted follow-up e-mails to contacts that cancelled their orders.

Note

As with all calls to remote systems, please consider what happens if the API is unavailable and make sure your end handles the failure gracefully. Your customer should be able to complete their order even in the rare circumstance that the API is unavailble. See Service windows

Sending order data using tracking image

The second option is to use only the tracking image to transfer all parameters of the order to the system in an URL encoded query string.

In this mode, we will have the contact details for your subscriber available in a tracking cookie sent when they last clicked on a link in your newsletter, and we will associate the sale with the:

  • Contact
  • Subscription
  • List
  • Newsletter
  • Link

This also means that, if a sale happens and the user has not clicked on a link in your newsletter or is blocking our cookies, the sale will not be recorded.

The tracking GIF is available on your account from:

https://[account-hostname]/et/

Here is a complete example:

<img src="https://account.uxmail.io/et/?et_products=1&et_currency=USD&et_customer_ref=12345678&et_order_ref=12345678&et_prod_0_id=54491472&et_prod_0_quantity=1&et_prod_0_name=Coca+Cola+500ml&et_prod_0_category=Softdrinks&et_prod_0_unit_price=1.50" height="1" width="1">

Anti-tampering

Since this mode of transferring order data happens on the client side of the transaction you are leaving your order data open for examination and possibly tampering in transit.

You may configure your account with an anti-tampering key, you and digitally sign the parameters to at least avoid anyone changing them in transit. Use the following procedure:

  1. Take the complete URL encoded parameter list (e.g. bar=baz&foo=quux sorted by the key name.
  2. Feed this string into an HMAC-SHA256 keyed by the anti-tampering key from your account.
  3. Hex encode the resulting digest and add as the et_digest parameter.

Here’s the above example with the added et_digest parameter:

<img src="https://account.uxmail.io/et/?et_currency=USD&et_customer_ref=12345678&et_order_ref=12345678&et_prod_0_category=Softdrinks&et_prod_0_id=54491472&et_prod_0_name=Coca+Cola+500ml&et_prod_0_quantity=1&et_prod_0_unit_price=1.50&et_products=1&et_digest=..." height="1" width="1">

Warning

You must calculate the HMAC-SHA256 digest server side for the digest to have any effect. Otherwise your secret key would be compromised.

Debugging

If results fail to show up in the statistics, there might be some problems with registering the sales. In case of an error, the resulting 1x1 pixel tracking GIF will contain an extra HTTP header called ST-Error with any errors encountered during sales registration.