Universal Variable¶

The nToklo recommendation engine uses UV(Universal Variable) objects to create the recommendations. UV is a type of JSON object that has a specfic set of keys to manage ecommerce entries. You can check the specification here

For example Universal Variable in JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

uv = {
        "version": 1.2, # If his doesn's exist, the connector will assume latest
        "user": {
                "user_id": "nicole12@example.com",
                "name": "Nicole Watts",
                "username": "nicoleuser123"
        },
        "events": [
                {
                        "category": "conversion_funnel",
                        "action": "preview"
                }
        ],
        "product":{
                "id": "1234",
                "url": "http://www.fashionbay.com/women/shoes/french_sole_flats_1021.html",
                "name": "French Sole: Classic Ballet",
                "unit_price": 99,
                "unit_sale_price": 69,
                "description": "This is beautifully soft, unstructured ballet flat is ..."
                "category": "shoes"
        }
}

For example Universal Variable in PHP:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

$uv = array('
                "version"       => "1.2",
    "user"              => array("user_id" => "112"),
    "product"   => array(
        "id"                            => "10201",
        "name"                          => "Gabardine A-line skirt",
        "category"                      => "Womens > Skirts",
        "currency"                      => "GBP",
        "unit_sale_price"       => 98
    ),
    "events"    => array(
        (object)[
        "category" => "conversion_funnel", "action" => "browse"
        ]
    )
  );

Products¶

To keep track of the products, you have to send them first. It’s not a requirement but if you have a big catalog it will allow you to preprocess the data before starting to send events.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

require "vendor/autoload.php";
$api = new NtokloApi( 'nToklo API key', 'nToklo API secret' );

$uv = array(
                "version"       => "1.2", // If this doesn't exist, the connector will assume lastest
    "product"   => array(
        "id"                            => "10201",
        "name"                          => "Gabardine A-line skirt",
        "category"                      => "Womens > Skirts",
        "currency"                      => "GBP",
        "unit_sale_price"       => 98

    )
  );

$response = $api->postProduct($uv);

echo $response;  //return true if post is successful

Events¶

An event in the nToklo recommendation system means some kind of action that has performed by the user.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

require "vendor/autoload.php";
$api = new NtokloApi( 'nToklo API key', 'nToklo API secret' );

$uv = array('
                "version"       => "1.2", // If this doesn't exist, the connector will assume lastest
                "user_id"       => "112",
    "product"   => array(
        "id"                            => "10201",
        "name"                          => "Gabardine A-line skirt",
        "category"                      => "Womens > Skirts",
        "currency"                      => "GBP",
        "unit_sale_price"       => 98
    ),
    "events"    => array(
        (object)[
        "category" => "conversion_funnel", "action" => "browse"
        ]
    )
  );

$response = $api->postEvent($uv);

echo $response; // Return true if post is successful

Recommendations¶

This is the core of the system, the recommendations. This function will return to you a JSON objects with the reommended products for your user and a temporary token.

Example:

1
2
3
4
5
6

require "vendor/autoload.php";
$api = new NtokloApi( 'nToklo API key', 'nToklo API secret' );

$recommendation = $api->recommendations($userID = null, $productId = '10201', $scope = null, $value = null);

print_r( $recommendation );

It should return something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
        "tracker_id": "2b169680-aa86-12e5-9c37-600308a4f234",
        "items": [
        {
                "id": "10242",
                "name": "Campbell capri in wave print",
                "currency": "GBP",
                "unit_sale_price": 98
        },
        {
                "id": "22832",
                "name": "Andie chino",
                "currency": "GBP",
                "unit_sale_price": 79.5
        },
        {
                "id": "12955",
                "name": "Collection cropped trouser in antique floral",
                "currency": "GBP",
                "unit_sale_price": 298
        }
        ]
}

Blacklist¶

The blacklist functionality allows you to add products to a blacklist so they don’t show up on the recommendations.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

require "vendor/autoload.php";
$api = new NtokloApi( 'nToklo API key', 'nToklo API secret' );

// Add one product tot he blacklist.
$api->addBlacklist( '12' );

// Remove a product from the blacklist.
$api->removeBlacklist( '12' );

//List all the currently blacklisted products
$api->fetchBlacklist();

Charts¶

Charts allows you to pull information regarding your analytics. It’s not a full report, for that you will have to use the nToklo Console. Charts contains a number of options that will be useful to you for filtering the information. Please refer to the Reference.

Example:

1
2
3
4
5
6
7

require "vendor/autoload.php";
$api = new NtokloApi( 'nToklo API key', 'nToklo API secret' );

$chart = $api->chart( $timestamp = '1364169600000', $scope = null, $value = null, $action = null , $tw = nulll , $maxItems = null );


print_r( $chart );

It should return something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "tracker_id": "d91a6a80-a181-12e5-9c37-600308a4f234",
  "items": [
    {
      "currentPosition": 1,
      "previousPosition": 2,
      "peakPosition": 1,
      "score": 58,
      "timesOnChart": 6,
      "product": { ... }
    },
    {
      "currentPosition": 2,
      "previousPosition": 1,
      "peakPosition": 1,
      "score": 45,
      "timesOnChart": 12,
      "product": { ... }
    },
   {
      "currentPosition": 3,
      "previousPosition": 0,
      "peakPosition": 3,
      "score": 39,
      "timesOnChart": 1,
      "product": { ... }
    }
  ]
}

NtokloApi class¶

class NtokloApi¶

property $api_base¶

__construct($key, $secret)¶

postEvent($data)¶

This function will allow to post a decoded json object into the nToklo api @uses array | decode json object Example: $data = array(“version” => “1.2”,

“user” => array(“user_id” => “112”), “product” => array(“id” => “10201”,

“name” => “Gabardine A-line skirt”, “category” => “Womens > Skirts”, “currency” => “GBP”, “unit_sale_price” => 98),

“events” => array((object)[“category” => “conversion_funnel”, “action” => “browse” ]) );

@return bool

postProduct($data)¶

This function will allow to post a decode json object into the nToklo api @uses array | decode json object Example: $data = array(“version” => “1.2”,

“product” => array(“id” => “10201”,

“name” => “Gabardine A-line skirt”, “category” => “Womens > Skirts”, “currency” => “GBP”, “unit_sale_price” => 98 )

);

@return bool

getProduct($id)¶

This function will allow to post a decode json object into the nToklo api @param int product id. @return bool

recommendations($userId = null, $productId = null, $scope = null, $value = null)¶

This function will fetch the recommendations from nToklo api @param string $userId optional. Uniquely identifies the user for which the recommendations are intended.

The userId can be any value of string type. Examples: dan@gmail.com, 11245901, user_123

@param string $productId optional. The product for which to base recommendations from. The productId can be any string value. Example: 10201,prod8513 @param string $scope optional. A product attribute for which to scope recommendations.

For example scope=category will consider the product category when returning recommendations. Supports: category, manufacturer, vendor, action.

@param string $value optional. The value for the recommendation scope.

For example scope=category&value=shoes will consider the shoe category when returning recommendations. The value parameter can be any string value. Example: shoes, category12, nike, shoes.com

@return Json

chart($timestamp = null, $scope = null, $value = null, $action = null, $tw = null, $maxItems = null)¶

This function will fetch the charts from nToklo api @param string $timestamp Optional. The date for which to retrieve a chart. The date should be an epoch timestamp in milliseconds, truncated to midnight Example: 1364169600000 @param string $scope Optional. A product attribute for which to scope recommendations.

For example scope=category will consider the product category when returning recommendations. Supports: category, manufacturer, vendor, action.

@param string $value Optional. The value for the recommendation scope.

For example scope=category&value=shoes will consider the shoe category when returning recommendations. The value parameter can be any string value. Example: shoes, category12, nike, shoes.com

@param string $action Optional Filters the requested chart by conversion_funnel actions. If it’s not specified then the chart returned is all actions, equivalent to action=all. @param string $tw Optional. The time window for which the charts are requested. If not specified then the chart returns daily chart, equivalent to tw=DAILY. Supports: DAILY, WEEKLY. @param srting $maxItems Optional. The max number of items in the charts. Default is 10. Valid range is 1-100.

@return Json object

addBlacklist($productId = null)¶

This function will post an product id to nToklo api to blacklist @param string $productId The unique identifier for the product which will added/removed from the blacklist.

The productId can be any string value. In order to add/remove products in batches the productId can be specified multiple times.

@return bool

removeBlacklist($productId = null)¶

This function will post an product id to nToklo api remove prodct from blacklist @param string $productId The unique identifier for the product which will added/removed from the blacklist.

The productId can be any string value. In order to add/remove products in batches the productId can be specified multiple times.

@return bool

fetchBlacklist()¶

This function will fetch all the blacklisted products @return json object

NtokloApiBase¶

class NtokloApiBase¶

property $key¶

property $secret¶

property $endpoint¶

__construct($key, $secret)¶

api_request($method, $uri, $data = null)¶

This class will take care of authentication and exceptions of the API, retuning the required codes to the functions that use it.

@param string $method http method POST GET DELETE @param string $uri @param array $data post the json object to the nToklo api

@return int status code

getResponse()¶

Curl¶

class Curl¶

property $curl¶

property $error¶

property $error_code¶

property $error_message¶

property $curl_error¶

property $curl_error_code¶

property $curl_error_message¶

property $http_error¶

property $http_status_code¶

property $http_error_message¶

property $request_headers¶

property $response_headers¶

property $response¶

__construct()¶

__destruct()¶