Ecommerce Tracking

padams edited this page Mar 21, 2015 · 4 revisions

OWA can track e-commerce transactions that visitors make on your web sit or via third party payment systems such as PayPal.

Overview

To track e-commerce transactions you must use OWA's commerce tracking methods as outlined below. These methods exist in both the Tracker and OWA's owa_client PHP class.

  1. Describe the E-commerce Transaction - using the addTransaction method to tell OWA about the overall e-commerce transaction including it's unique order id, the total amount, total tax, and total shipping.

  2. Add Line Items to the Transaction - using the addTransactionLineItem method, tell OWA about the line items that make up this transaction. A good way to think of line items is as the rows on a paper invoice that describe the products being purchased, their unit prices and the quantities being ordered. Like offline transactions that might occur at a grocery store, a single e-commerce transaction can contain multiple products each of which is represented in OWA as it's own transaction line item. Line items are stored in OWA associated with their parent transaction using the ''order id'' supplied when you described the transaction.

  3. Track the Transaction - using the trackTransaction method, will send the transaction and it's line items to OWA for processing.

  4. Turn on E-commerce reporting for your site - you need to turn on e-commerce reporting for each site that you want to see the reports and metrics. This is a site setting and can be accessed by visiting ''Administration -> Tracked Sites -> your site -> settings'' in OWA's interface.

Javascript Example

<!-- Start Open Web Analytics Tracker -->
<script type="text/javascript">
//<![CDATA[
var owa_baseUrl = 'http://your.domain.com/path/to/owa/';
var owa_cmds = owa_cmds || [];
owa_cmds.push(['setSiteId', '67b3053d792527f6b62e55b20453ad2c']);
owa_cmds.push(['trackPageView']);
owa_cmds.push(['trackClicks']);
owa_cmds.push(['trackDomStream']);
owa_cmds.push(['addTransaction', 
           'order123', // the id of the order, comes from your ecommerce system -required
           'test-app',  // the source or store name that originated the transaction
           '100.50', // the total amount of revenue - required
           '1.25', // amount of tax
           '3.50',  // amount of shipping
           'paypal', // transaction gateway name
           'United States', // country
           'CA', //state
           'Palo Alto' //city
]);
owa_cmds.push(['addTransactionLineItem', 'order123', 'SKU123', 'widget', 'things', 10.00, 5]);
owa_cmds.push(['addTransactionLineItem', 'order123', 'SKU456', 'widget', 'things', 10.10, 5]);
owa_cmds.push(['trackTransaction']);

(function() {
    var _owa = document.createElement('script'); _owa.type = 'text/javascript'; _owa.async = true;
    _owa.src = owa_baseUrl + 'modules/base/js/owa.tracker-combined-min.js';
    var _owa_s = document.getElementsByTagName('script')[0]; _owa_s.parentNode.insertBefore(_owa, _owa_s);
}());
//]]>
</script>
<!-- End Open Web Analytics Code -->        

PHP Example

<?php       
require_once('owa/owa_php.php');

$owa = new owa_php();
$owa->setSiteId('67b3053d792527f6b62e55b20453ad2c');
$pv = $owa->makeEvent();
$pv->setPageTitle('Commerce PHP API Test Page - 布啦布啦BlaBla.cn');
$owa->trackPageView($pv);
$order_id = xyz321;
$owa->addTransaction(
          $order_id, // the unique order id generated by your shopping cart/commerce application
          'My Online Store', // the source of the transaction, often the name of the store 
          '100.23', // the total revenue amount. Rounded to two decimal places. 
          '20.20', // the total tax amount. Rounded to two decimal places. 
          '15.30', // the total shipping amount. Rounded to two decimal places.  
          'paypal', // the name of the transaction gateway or payment service used
          'http://domain.com/page/that/transaction/occured', // optional for use in batch mode. This is the url of the page that the transaction occurred on. only used when not also calling $owa->trackPageView() in the same request
          'some_session_id' // optional for use in batch mode
);

// repeat this as many times as their are products/line items
$owa->addTransactionLineItem(
          $order_id, // the unique order id of the parent transaction generated by the shopping cart/commerce application
          'sku123', // the unique  SKU id assigned o this product by your shopping cart/commerce application
          'My Product Name', // the name of the product
          'My Category', // the name of the category this product s associated to with
          '14.95', // the unit price of the product. Rounded to two decimal places.
          '10' // the quantity of the product ordered
);

// sends the transaction and line items for processing
$owa->trackTransaction();

?>

Tracking Delayed E-commerce Transactions

The PHP version of addTransaction method contains two additional arguments that allow you to record transactions that happened in prior sessions. Use the $page_id and $original_session_id parameters when playing e-commerce transactions into OWA that could not be fully authorized during the user's web request. This sometimes happens when a credit card provider has non-real-time card authorization (such as PayPal IPN).

To record relayed transactions you must store the user's OWA ''session id'' and the full URL of the "success" or "thank you" page that the user saw at the time that they perform the transaction so that they can be passed into addTransaction at a later time. You can retrieve the user's session_id from their session cookie using PHP:

$session_id = owa_coreAPI::getStateParam('s', sid');

or using the OWA javascript method getState like so:

var session_id = OWA.util.getState('s', 'sid');

== Tracking E-commerce Event via the log.php REST Interface ==

You can use OWA's REST based logging interface to record ecommerce transactions by posting them to log.php. The following example shows the name value pairs necessary to use that interface for tracking an ecommerce transaction and a single line item:

http://domain/path/to/owa/log.php?
        owa_event_type=ecommerce.transaction&
        owa_ct_order_id=foo&
        owa_ct_order_source=foo&
        owa_ct_total=100.23&
        owa_ct_tax=10.21&
        owa_ct_shipping=20.11&
        owa_ct_gateway=paypal&
        owa_page_url=some_encoded_url&
        owa_ct_line_items[0][li_order_id]=foo&
        owa_ct_line_items[0][li_sku]=foo&
        owa_ct_line_items[0][li_product_name]=foo&
        owa_ct_line_items[0][li_category]=foo&
        owa_ct_line_items[0][li_unit_price]=10.34&
        owa_ct_line_items[0][li_quantity]=10&
        owa_original_session_id=some_session_id&
                owa_siteId=yoursiteid