Implementing external actions

Sales-n-Stats supports two major types of actions: pattern driven and external. For pattern driven actions you have to set up action variants - patterns of a visitor's activity on the site which can be qualified as actions. Sales-n-Stats receives data about page views and form submits from the site and then, based on that information, determines what kind of action it is. Pattern driven actions are a fairly reliable way of getting information about what the visitors are doing. However, in some cases it may be impossible to unambiguously define an action by means of action variants. For such cases external actions can be used. Unlike pattern driven actions, external actions are recognized directly on the website by a piece of software hard-coded into the web application (e.g. a shopping cart), and only then are passed to Sales-n-Stats. When adjusted to function that way, Sales-n-Stats does not need to perform action recognition by interpreting basic data (page URLs and form fields), but receives actions already determined externally. In this sense external actions are more reliable and should be given preference when deciding on the way of setting up actions for your system. To implement external actions, some coding skills are required. If you are not sure, turn to our technical support specialists.

Note: Sales-n-Stats integration modules for LiteCommerce and X-Cart software are based on external actions, so if you are using these shopping systems you need not worry about coding: as a result of the integration module installation all the necessary external actions get implemented automatically. Find the list of shopping cart specific external actions used by LiteCommerce and X-Cart integration modules in the 'Appendices' section of this manual.

If you decide you want external actions for your system, the first thing you should do is go to the 'Actions' section of the 'System settings' (Main Menu -> Tools -> System settings -> Actions) and create the actions you need. For more details refer to section 'Creating actions' in the 'Setting up action patterns' chapter. Then proceed to modifying your web application so it can determine actions.

From the client's point of view, an External action is a POST request from the web application to the Data Collector script at the following address: {CollectorRoot}/event.php. At the moment only a .php version of Data Collector is provided.

•	clientId - is taken from the cookie named personal_client_id

•	timestamp - current timestamp (that is, number of seconds since Unix epoch (January 1st 1970)

•	passphrase - the passphrase you used during the collector installation.

•	action[1] - Parameters of the second action in the list and so on

As is seen above, you can include several actions into one query. The actions included into a query must be numbered (beginning with zero); the action numbers must come in brackets.

Each action[n] variable must contain (a) the name of the action, and (b) values of the parameters of this action in the following form:

The name variable specifies the action name. The action name matches the contents of the 'Class name' field in the action setup dialog except the trailing Action. For example, if the class name is AddToCartAction, only the AddToCart part should be passed to the collector. Action parameter names should correspond to the names of Action fields in the action setup dialog. All variable values must be URL encoded.

The data passed to the collector in the action variable as a result of adding to the shopping cart of a product Java In a Nutshell (Product ID: 70, Category: Books/Internet) may look like this:

name=AddToCart&ProductID=70&Product_name=Java+In+a+Nutshell&Category_name=Books%2FInternet

As an example and working implementation of an external action logic in PHP we provide Sales-n-Stats PHP API library. Obtain it from your HelpDesk account. The library facilitates the process of Sales-n-Stats integration with a website. PHP API library consists of a few components:

•	SnsIntegration.php – the main integration module you must include in your scripts; it contains the func_sns_request function that is used to send actions from the website to Sales-n-Stats collector and the func_get_sns_client_id function that identifies a visitor using his cookie data on your site;

•	HTTP/Request.php – a standard PEAR HTTP/Request module used to post data to collector;

•	Net/URL.php and Net/Socket.php – PEAR modules used by HTTP/Request.php;

•	PEAR.php – the standard PEAR unit (You can replace it with your system-wide version). It is required by the previous PEAR modules;

•	func_sns_request($collectorURL, $collectorLanguage, $clientId, $actions, $passphrase)

•	$collectorURL is the full-qualified URL of the collector directory without the trailing '/',

•	$clientId - visitor ID. It can be acquired with the help of function func_get_sns_client_id

$actions is an array of actions, each element of which is a string in the following format:

The cookie variable is generated by the tracker JavaScript code and identifies the visitors of your site.

The file sample.php contained in the library provides an example of external actions' implementation:

<?php

    require_once("SnsIntegration.php");

    // this cookie is set by tracker.js.php when including in your site
    $snsClientId        = func_get_sns_client_id();

    // let's add a product to cart
    $itemsCount         = 1;
    $productName        = "Sample product";
    $productId          = "123";
    $categoryName       = "Sample category";

    // do not include the trailing '/' in collector URL
    $collectorURL       = "http://www.your_domain/your_collector_path"
    $collectorLanguage  = "php";
    $passphrase         = "letmein";

    $actions = array();   // you may bundle several actions in the same query

    // the action name must match one of the actions' class names
       // listed in your 'setup/actions' dialog
    $action = "name=AddToCart";
    $action .= "&productId=".urlencode($productId);
    $action .= "&productName=".urlencode($productName);
    $action .= "&categoryName=".urlencode($categoryName);
    $actions []= $action;

    $action = "name=CartChanged";
    $action .= "&itemsCount=" . $itemsCount;
    $actions []= $action;

    // performs an HTTP post to event.php (or event.aspx, depending on
    // $collectorLanguage variable)
    $result = func_sns_request($collectorURL, $collectorLanguage, $snsClientId,
                               $actions, $passphrase);
?>