Implementing external actions

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. 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 'Preconfigured actions' 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 'Defining new actions' in the 'Actions' 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.

The POST query must contain the following variables:

•	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[0] - Parameters of the first action in the list

•	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:

name=<action name>&<param1_name>=<param1_value>&...

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.

Example

The action 'Add to cart' has the following fields:

integer23

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:

clientId=126985332&timestamp=1171876555&actions[0]=name%3DAddToCart%26productId%3D70%26productName%3DJava%2BIn%2Ba%2BNutshell%26categoryName%3DBooks%252FInternet

Sales-n-Stats PHP API

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;

The func_sns_request call uses the following syntax:

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

where

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

•	$collectorLanguage is the script extension (use 'php'),

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

•	$actions - set of actions for sending.

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

name=<action name>&<param1 name>=<param1 value>&…

•	$passphrase - passphrase for Data Collector.

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);
?>