You can use iOS and Android SDK to use Personyze on mobile devices. But under certain circumstances you may want to implement a Personyze tracker by yourself. This may be needed if you use a platform different from Android and iOS, or if you want to use a programming language or a framework that Personyze doesn't support.
Implementing full-featured tracker, like we did in our SDKs is not trivial, but if you want to use limited features subset, it can be relatively easy. Here we will show you how to implement an application that will use only recommendations feature of the Personyze system.
You will need to create a “Product recommendations in JSON format” action, or “Content recommendations in JSON format” in the Personyze panel, and your application will receive the JSON array with information about what products or articles are recommended to current user.
This application will query Personyze server through REST API.
All these operations are done through one REST API call like this:
curl --header 'User-Agent: Superagent/1.0' --header 'Content-Type: application/json' --data '{"user_id": 123456, "commands": [["Product viewed", "Chair"], ["Navigate", "urn:personyze:doc:Default"]]}' 'https://api:17A9187F88BDBEA9957EBDD4F56B5C2B54354952@app.personyze.com/rest/tracker-v1'
[["Product Viewed", "Product 1"], ["Product Added to cart", "Product 2"]]
. Our application will support the following commands:["User Profile", "first_name", "John", "industry": "e-commerce"]
- set user's profile data (in this case set two fields “first_name” and “industry” - you can create user fields in the account)["Product Viewed", "Internal ID"]
- product viewed["Product Added to cart", "Internal ID"]
- product added to cart["Product Liked", "Internal ID"]
- product liked (added to wish list)["Product Purchased", "Internal ID"]
- product purchased["Product Removed from cart", "Internal ID"]
- product removed from cart["Product Unliked", "Internal ID"]
- product unliked (removed from wish list)["Products Purchased"]
- all products in cart purchased["Products Unliked"]
- wish list cleared["Article Viewed", "Internal ID"]
- article viewed["Article Liked", "Internal ID"]
- article liked["Article Commented", "Internal ID"]
- article commented["Article Unliked", "Internal ID"]
- article unliked["Article Goal", "Internal ID"]
- article reached it's goal, as understood by your application (e.g. lead to purchase)["Articles Unliked"]
- mark all previously liked articles as not liked["Product Viewed", "Internal ID", "action_id", 10]
- means product “Internal ID” is viewed through action 10.["Navigate", "urn:personyze:doc:DocumentName"]
- logs navigation to a new “page”. We need to send this command with each request where we want to receive back recommendations (and other actions). This is because Personyze doesn't execute the same action several times on single page. DocumentName can be any URL-encoded text. It will appear in the dashboard.<?php // Usage: // php personyze-recom.php --viewed="Product 1" --viewed="Product 2" # log products view ("Product 1" and "Product 2" are product Internal IDs) // php personyze-recom.php --viewed="Product 1" --viewed="Product 2" --action=10 # products viewed from action ID 10 (will show contribution rate in dashboard) // php personyze-recom.php --cart="Product 1" # log product added to cart // php personyze-recom.php --liked="Product 1" # log product liked (added to wish list) // php personyze-recom.php --purchased="Product 1" # log product purchased // php personyze-recom.php --removed="Product 1" # log product removed from cart // php personyze-recom.php --unliked="Product 1" # log product unliked (removed from wish list) // php personyze-recom.php --purchased-all # log all products in cart purchased // php personyze-recom.php --unliked-all # log wish list cleared // Put your Personyze API key here. You can obtain it from https://personyze.com/site/tracker/condition/index#cat=Account%20settings%2FMain%20settings%2FIntegrations // from the "Full-featured API" section. define('PERSONYZE_KEY', '17A9187F88BDBEA9957EBDD4F56B5C2B54354952'); // This User-Agent will appear in Personyze dashboard in Live Visits - https://personyze.com/site/tracker/condition/index#cat=Dashboard%2FReal%20time%20visitors define('USER_AGENT', 'Superagent/1.0'); // Proceed main(); exit; function main() { try { // We need to use permanent storage for session information. // Always store the "session_id" field from each response from Personyze, and send the last stored value with each request. // In this example we will store it in a file. $file = sys_get_temp_dir()."/personyze_session.dat"; // Build the request $request = get_system_constants(); $request['session_id'] = is_file($file) ? file_get_contents($file) : null; $request['commands'] = get_commands(); // Send the request and get the response $response = tracker_v1($request); // Store the "session_id" file_put_contents($file, $response['session_id']); // Find out what actions matched foreach ($response['actions'] as $action) { // There can be various types of actions. Some of them can contain HTML to be presented. // We are only interested in actions that have product recommendations in JSON format. // To create such actions, go to Personyze panel, create new Campaign of "Targeting and Personalization" type, and add action of type "Product recommendations in JSON format". // Such actions will have $action['data']['data'] set to the JSON string. if (isset($action['data']['data'])) { $action_id = $action['id']; // Actually the resulting JSON string will not have surrounding square brackets. // "data" field of each resulting action only contains varying part of the action's content. // We can request the constant wrapping part with another REST API call. // But for the "Product recommendations in JSON format" actions the wrapping part will always be square brackets, so we can just add them by ourselves. $action_data = '['.$action['data']['data'].']'; // It's JSON $action_data = json_decode($action_data, true); if ($action_data !== null) // json_decode will return null if that was not a JSON { // Action $action_id matched. // Here we just print it. echo "Action $action_id: ", json_encode($action_data), "\n"; } } } } catch (Exception $e) { exit($e->getMessage()."\n"); } } /** The user of this script must supply the commands through command-line options. **/ function get_commands() { $options = getopt("", ['viewed:', 'cart:', 'liked:', 'purchased:', 'removed:', 'unliked:', 'purchased-all', 'unliked-all', 'action:']); $names = [ 'viewed' => 'Product Viewed', 'cart' => 'Product Added to cart', 'liked' => 'Product Liked', 'purchased' => 'Product Purchased', 'removed' => 'Product Removed from cart', 'unliked' => 'Product Unliked', 'purchased-all' => 'Products Purchased', 'unliked-all' => 'Products Unliked', ]; $action_id = intval($options['action'] ?? 0); $commands = []; foreach ($options as $option => $item_ids) { $command_name = $names[$option] ?? null; if ($command_name) { foreach ((is_array($item_ids) ? $item_ids : [$item_ids]) as $item_id) { $command = $item_id===false ? [$command_name] : [$command_name, $item_id]; if ($action_id > 0) { $command[] = 'action_id'; $command[] = $action_id; } $commands[] = $command; if ($item_id === false) { break; } } } } if (!$commands) { throw new Exception("One of the following is required: --viewed=PRODUCT_ID or --cart=PRODUCT_ID or --liked=PRODUCT_ID or --purchased=PRODUCT_ID or --removed=PRODUCT_ID or --unliked=PRODUCT_ID or --purchased-all or --unliked-all"); } $commands[] = ['Navigate', 'urn:personyze:doc:Default']; return $commands; } /** You need to scan the current device for it's properties, like device ID, system languages, screen resolution, etc. These information will be presented in Personyze dashboard in Live Visits - https://personyze.com/site/tracker/condition/index#cat=Dashboard%2FReal%20time%20visitors and it can be used in Campaign rules to trigger specific actions to specific users. Here is the code that will detect system properties on Linux systems. If you want to run this script on different environment, you'll need to correct this function. **/ function get_system_constants() { // Any signed or unsigned 32-bit integer, which is constant for each user. Can be device ID (on single-user devices), vendor ID, etc. $user_id = crc32(is_file('/etc/machine-id') ? file_get_contents('/etc/machine-id') : '-'); // e.g. en, es $languages = substr(getenv('LANG'), 0, 2); // e.g. -4 (means GMT-4) $time_zone = date('Z')/3600; // e.g. 1920x1080 preg_match('~\n\s*dimensions:\s*([0-9x]+)~', `xdpyinfo`, $screen); $screen = $screen[1]; // e.g. Android/9 $os = php_uname('s'); // e.g. Linux x86_64 $platform = PHP_OS.' '.php_uname('m'); // One of: regular, phone, tablet $device_type = 'regular'; return [ 'user_id' => $user_id, 'languages' => $languages, 'time_zone' => $time_zone, 'screen' => $screen, 'os' => $os, 'platform' => $platform, 'device_type' => $device_type, ]; } /** Make the REST API call. **/ function tracker_v1($post_data) { $hurl = curl_init("https://app.personyze.com/rest/tracker-v1"); curl_setopt($hurl, CURLOPT_POST, true); curl_setopt($hurl, CURLOPT_POSTFIELDS, json_encode($post_data)); curl_setopt($hurl, CURLOPT_HTTPHEADER, ['Content-Type: application/json', 'Authorization: Basic '.base64_encode("api:".PERSONYZE_KEY)]); curl_setopt($hurl, CURLOPT_USERAGENT, USER_AGENT); curl_setopt($hurl, CURLOPT_RETURNTRANSFER, true); curl_setopt($hurl, CURLOPT_ENCODING, ''); $response_str = curl_exec($hurl); if ($response_str === false) { $err_msg = curl_error($hurl); curl_close($hurl); throw new Exception($err_msg); } $status = curl_getinfo($hurl, CURLINFO_RESPONSE_CODE); curl_close($hurl); if ($status == 500) { throw new Exception($response_str); } if ($status != 200) { throw new Exception("HTTP Status $status"); } return json_decode($response_str, true); }