Upsight logo Back to top

Enterprise PHP

Quick Start Guide

The Basics


This is a PHP SDK around Upsight Data Collection API. It provides methods to make the API calls for all the different message types supported by Upsight Analytics.

Download SDK

To get started with the Upsight library, you will need to check-out the kontagent_api.php file from our GitHub and include it in your project. You will also need to instantiate and configure an instance of the Kontagent object.

<?php

// include the library
require_once('./kontagent_api.php');

// configure and instantiate Upsight object
$ktApi = new KontagentApi($ktApiKey, array('useTestServer' => true, 'validateParams' => true));

?>

Quick Start Guide

Using the Library


Overview

Once you've got your Upsight object integrated and configured you can start using the library. There are two types of methods provided in the library: tracking methods and helper methods.

Tracking Methods

The tracking methods should get called by your application whenever you need to report an event to Upsight. There is a tracking method available for every message type in the Upsight API. A few examples are:

<?php

$ktApi->trackApplicationAdded($userId);
$ktApi->trackPageRequest($userId); 
$ktApi->trackEvent($userId, $eventName, array('value' => 5));
$ktApi->trackRevenue($userId, $value, array('type' => 'credits'));

>?

When events happen within your application, you should make the appropriate call to Upsight. We will then crunch and analyze this data in our systems and present them to you in your dashboard.

For a full list of the available tracking methods, refer to the PHP SDK specification.

Helper Methods

The library provides a few helper methods for common tasks. Currently the only ones available are:

<?php

$ktApi->genUniqueTrackingTag();
$ktApi->genShortUniqueTrackingTag();

>?

These methods will help you generate the tracking tag parameters required to link certain messages together (for example: invite sent -> invite response -> application added).

Quick Start Guide

Facebook


If you are not instrumenting with the Upsight Facebook SDK and instead instrumenting with this wrapper, you may run into some issues. Please see our Facebook Best Practices page for troubleshooting tips.

Quick Start Guide

HTTPS


If sending a request to HTTPS, set optionalParams.useHttps to TRUE in the constructor, just as would set userTestServer to true when using the test server.

Basic Messages

Application Added (apa)


Send this API call when a user installs an application.

The presence of a tracking tag (u) or short tracking tag (su) is used to determine the source of the installation. If the install click was from a Facebook Discovery Feed link, app dashboard link, search results, or bookmarks panel, only the s parameter is required. apa messages are deduped on the Upsight side.

Function

trackApplicationAdded($userId, $optionalParams = array(), &$validationErrorMsg = null)

The $optionalParams['uniqueTrackingTag'] and $optionalParams['shortUniqueTrackingTag'] parameters are used to determine the source of the installation.

  • If the install was sourced from an invitation, post, or notification, the $optionalParams['uniqueTrackingTag'] is required.
  • If the install was sourced from an advertisement or partner link click, the $optionalParams['shortUniqueTrackingTag'] is required.
  • If the install click was from a Facebook Discovery Feed link, Top Search, or Bookmarks panel, only the $userId parameter is required.

Required Parameters

ParameterTypeDescription
$userIdstringThe UID of the user installing the application. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['uniqueTrackingTag']stringA 16-digit unique hexadecimal string that is used to match installs to the corresponding invite, post, or notification. Valid characters are a-f, A-F, 0-9. This must match the uniqueTrackingTag parameter in the trackInviteSent()/trackInviteResponse(), trackStreamPost()/trackStreamPostResponse(), or trackNotificationSent()/trackNotificationResponse() methods.
$optionalParams['shortUniqueTrackingTag']stringAn 8-digit unique hexadecimal string that is used to match installs to corresponding advertisement or partner link clicks. Valid characters are a-f, A-F, 0-9. This must match the $optionalParams['shortUniqueTrackingTag'] parameter in the trackThirdPartyCommClick() method.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Kontagent system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Basic Messages

User Information (cpu)


This API call is sent to provide information regarding a specific user, such as birth year, gender, country, state, and friend count.

You should place the code that retrieves and sends user information in a common place in your application, such as a landing page or post-login page, and include the call to send this CPU message on these pages. Additionally, we recommend a cookie is also set to check if the user data was retrieved and sent for that day.

Function

trackUserInformation($userId, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIDstringThe UID of the user. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['birthYear']intThe year of the user's birth, in YYYY format.
$optionalParams['gender']stringThe gender of the user. Accepted parameter values are: m (Male), f (Female), and u (Unknown, if no gender is specified).
$optionalParams['country']stringThe country code of the country in which the user is located. The country code must be in upper case format and conform to the ISO 3166-1 alpha-2 standard. If not sent, it will be based on the user's IP. Note! The Facebook locales ar_AR and es_LA do not follow the ISO standard. Facebook uses them to denote umbrella locales for Arabic and Spanish speaking regions. If you send the last two characters of these locales to Upsight, they will map to Argentina and Laos. As a best practice, if you see these locales, do not pass the country code. For additional information on Facebook locales, refer to Facebook's internationalization documentation.
$optionalParams['friendCount']intThe number of friends a user has.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Basic Messages

Page Request/User Location (pgr)


This message is sent when a page request is made by a user. You should implement this as an embedded pixel on the browser side. Please note that the browser IP is used to determine the location of the user, and as such, it is critical that the pixel be loaded by the browser and not the application server. An example of how to embed the pgr call into an img tag is shown below:

img src="http://api.geo.kontagent.net/api/v1/0123456789abcdef0123456789abcdef/pgr/?s=456&ts=2009-4-22T04:08:35" width="0" height="0"

Best Practice

The pgr should be sent after each user login to an application. If you wish to track user clicks from the Facebook Discovery Feed, App Request panel, search results, and bookmarks panel, send this call after a click is detected from any of those sources. This call will also automatically attribute installs from the Discovery Feed and App Request panel. For Facebook, if you are sending this from the server side, you should also append the fbx_ref and fbx_type parameters, where fbx_ref is the value of the ref parameter from Facebook, and fbx_type is the value of the type parameter from Facebook. If the pgr call is being sent from the client side, you do not need to specify and append the these parameters.

Important! Some applications, such as Flash games, do not refresh the page very often. pgr messages represent a page request and is used by Upsight to calculate the session length metric. If your application does not refresh the page often, it would be difficult to know when a user has ended their session and in turn, provide incorrect session lengths. To prevent this, set up your application so that it sends a pgr message every 30 seconds to Upsight. This will indicate to Upsight that the user is still actively participating in a session and allow for more granular tracking of short session length times.

Function

trackPageRequest($userId, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIDstringThe UID of the user accessing the page. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['pageAddress']stringThe page address to be recorded can be set manually using this parameter. If this message is posted to the server directly from the end user's browser, it is not necessary to set this parameter, as the page address can be derived from the information in the HTTP header. The value of this parameter, if present, should be URL-encoded.
$optionalParams['ipAddress']stringThe IP address of the user requesting the page. If this message is sent to the Upsight API server directly from your server, you must set this parameter.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Application Removed (apr)


When a user removes the application, send this API message to track the application removal.

Function

trackApplicationRemoved($userId, &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdstringThe UID of the user removing the application. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Custom Event (evt)


This message is sent when an user triggers an application-defined action. Please note that the maximum number of events that can be tracked is 32759.

Function

trackEvent($userId, $eventName, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdunsigned 63-bit intThe UID of the user performing the action, or initiating the event. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$eventNamestringThe event name, up to 31 characters long, describing the event. Valid characters are a-z, A-Z, 0-9, -, and _.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['value']intAn arbitrary value you assign to associate with the event. The default value is 0.
$optionalParams['level']intA level value, which can be associated to an action to indicate what game level the use is on. It is possible to view aggregate event counts by level. The level must always be a positive integer in the range from 0 to 255. The default value is 0.
$optionalParams['subtype1']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
$optionalParams['subtype2']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 is used.
$optionalParams['subtype3']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Kontagent system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Goal Counts (gci)


You can use goal counts to track when users reach defined milestones. The four goal counts can be mapped to any user action.

One example of using a goal count would be to track the number of players that have reached a certain level or purchased a certain item. Every time a player reaches the level or purchases the item, you would send a goal count message. As an example, the structure of a gci Data Collection API call is as follows:

http://api.geo.kontagent.net/api/v1/API_KEY/gci/?s=123456&gc1=1

This message will increment the first goal count by 1 and let Upsight know that player s=123456 has achieved this goal. At a maximum, four goal count variables can be used: gc1, gc2, gc3 and gc4. This will allow you to track 4 custom in-app goals.

Function

trackGoalCount($userId, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIDstringThe UID of the user. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['goalCount1']intThe value to increase goalCount1 by. This value can be any integer in the range of -16384 to 16384.
>$optionalParams['goalCount2']intThe value to increase goalCount2 by. This value can be any integer in the range of -16384 to 16384.
$optionalParams['goalCount3']intThe value to increase goalCount3 by. This value can be any integer in the range of -16384 to 16384.
$optionalParams['goalCount4']intThe value to increase goalCount4 by. This value can be any integer in the range of -16384 to 16384.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Kontagent system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Invite Sent (ins)


Send this API call when an invite to add an application occurs. You can specify multiple recipients in this message using the r parameter.

For example, if ins with r=s1,s2 is sent, the dashboard will reflect this as two actual invites.

Function

trackInviteSent($userId, $recipientUserIds, $uniqueTrackingTag, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdstringThe UID of the user sending the invitation. For app to user notifications, set this value to 0. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$recipientUserIdsstringA list of recipient UIDs, separated by commas. Must be URL-encoded. Note! Upsight only accepts integers up to 64-bits. For information on converting UIDs greater than 64-bits, click here.
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match Invite Sent messages to Invite Response trackInviteResponse messages. Valid characters are a-f, A-F, 0-9. If an install occurs, this must match the $uniqueTrackingTag parameter in the trackApplicationAdded method.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['recipientUserId']stringThe UID of the responding user. Note! Upsight only accepts integers up to 64-bits. For information on converting UIDs greater than 64-bits, click here.
$optionalParams['subtype1']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype1 of the corresponding Invite Response message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype2 of the corresponding Invite Response message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype3 of the corresponding Invite Response message. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Invite Response (inr)


This message is sent when an invite recipient responds to an invite to add (install) an application. The subtype parameters in this API call must match the subtype parameters in the corresponding ins API call.

Function

trackInviteResponse($uniqueTrackingTag, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match sent invite messages to invite responses. Valid characters are a-f, A-F, 0-9. If an install occurs, this must match the $uniqueTrackingTag parameter in the trackApplicationAdded() method. See the genUniqueTrackingTag() helper method for more information.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['recipientUserId']stringThe UID of the responding user. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$optionalParams['subtype1']stringInvite subtype 1, up to 31 characters long, must match subtype 1 of the corresponding Invite Sent message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringInvite subtype 2, up to 31 characters long, must match subtype 2 of the corresponding Invite Sent message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringInvite subtype 3, up to 31 characters long, must match subtype 3 of the corresponding Invite Sent message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Notification Email Sent (nes)


Send this API call when an email newsletter is sent. Multiple recipients can be specified.

URL

trackNotificationEmailSent($userId, $recipientUserIds, $uniqueTrackingTag, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdstringThe UID of the user initiating the action to send an email newsletter. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$recipientUserIdsstringThe recipient UID(s) of the user(s) receiving the email newsletter, separated by commas. Note! Upsight only accepts integers up to 64-bits. For information on converting UIDs greater than 64-bits, click here.
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match sent email notifications to responded email notifications. Valid characters are a-f, A-F, 0-9. If an install occurs, this must match the $uniqueTrackingTag parameter in the trackApplicationAdded() method. See the genUniqueTrackingTag() method.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['subtype1']stringEmail notification subtype 1, up to 31 characters long, must match the $optionalParams['subtype1'] parameter in the corresponding trackNotificationEmailResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringEmail notification subtype 2, up to 31 characters long, must match the $optionalParams['subtype2'] parameter in the corresponding trackNotificationEmailResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringEmail notification subtype 3, up to 31 characters long, must match the $optionalParams['subtype3'] parameter in the corresponding trackNotificationEmailResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Notification Email Response (nei)


Send this message when an email newsletter recipient clicks on the email newsletter link and visits the application.

Function

trackNotificationEmailResponse($uniqueTrackingTag, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match email notification responses to the original sent email notification. Valid characters are a-f, A-F, 0-9. If an install occurs, this must match the $uniqueTrackingTag parameter in the trackApplicationAdded() method. See the genUniqueTrackingTag() helper method for more information.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['recipientUserId']stringThe UID of the responding user. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$optionalParams['subtype1']stringEmail notification subtype 1, up to 31 characters long, must match the $optionalParams['subtype1'] parameter in the corresponding trackNotificationEmailSent() method. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringEmail notification subtype 2, up to 31 characters long, must match the $optionalParams['subtype2'] parameter in the corresponding trackNotificationEmailSent() method. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringEmail notification subtype 3, up to 31 characters long, must match the $optionalParams['subtype3'] parameter in the corresponding trackNotificationEmailSent() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Revenue Tracking (mtu)


Send this API call to track revenue and monetization transactions by users.

Function

trackRevenue($userId, $value, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdunsigned 63-bit intThe UID of the user for which revenue is being tracked. Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.
$valueintThe revenue value which must be passed in cents. Example: $1.25 should be passed as 125. Can be either a positive or negative integer. The maximum value that can be passed is 1000000 ($10,000).

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['type']stringThe type of transaction that occurred. If a subtype is used, this parameter is required. This parameter takes the following values: direct, indirect, advertisement, credits, or other.
$optionalParams['subtype1']stringA subtype to further categorize the revenue source, up to 31 characters long. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringA subtype to further categorize the revenue source, up to 31 characters long. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringA subtype to further categorize the revenue source, up to 31 characters long. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Stream Post (pst)


Send this API call when a user posts to a stream. For Facebook, the tu parameter is required, and must be set as tu = stream.

Function

trackStreamPost($userId, $uniqueTrackingTag, $type, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$userIdstring

The UID of the user who made the post.

Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

$typestringFacebook stream, or non-Facebook stream equivalent (for other social networks) channel type. Pass stream in this parameter.
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match stream posts to stream post responses. Valid characters are a-f, A-F, 0-9. If an install occurs from this Stream post, the install's uniqueTrackingTag must match this one.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['subtype1']stringStream post subtype 1, up to 31 characters long, must match the $optionalParams['subtype1'] parameter in the corresponding trackStreamPostResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringStream post subtype 2, up to 31 characters long, must match the $optionalParams['subtype2'] parameter in the corresponding trackStreamPostResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringStream post subtype 3, up to 31 characters long, must match the $optionalParams['subtype3'] parameter in the corresponding trackStreamPostResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Stream Response (psr)


Send this message when a user clicks on a post from one of the channels used in the pst API call.

Function

trackStreamPostResponse($uniqueTrackingTag, $type, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

ParameterTypeDescription
$typestringThe Facebook channel type. Pass stream in this parameter.
$uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match email notification responses to the original sent email notification. Valid characters are a-f, A-F, 0-9. If an install occurs, this must match the $uniqueTrackingTag parameter in the trackApplicationAdded() method. See the genUniqueTrackingTag() helper method for more information.

Optional Parameters

ParameterTypeDescription
$optionalParamsobjectAn object containing paramName => value.
$optionalParams['recipientUserId']string

The UID of the responding user.

Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

$optionalParams['subtype1']stringStream post response subtype 1, up to 31 characters long, must match the $optionalParams['subtype1'] parameter in the corresponding trackStreamPost() method. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringStream post response subtype 2, up to 31 characters long, must match the $optionalParams['subtype2'] parameter in the corresponding trackStreamPost() method. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringStream post response subtype 3, up to 31 characters long, must match the $optionalParams['subtype3'] parameter in the corresponding trackStreamPost() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Advanced Messages

Third Party Comm. Clicks (ucc)


This message is sent when a click from a third party source, such as an advertisement or partner link, is detected. Note that the user may not have yet installed the application, so a UID may not be sent. If the user chooses to install the application, an apa API message call must be sent following the ucc API message call.

Best Practice

  1. When you buy ads, regardless of the provider, or set up cross promotion links (You use ad for when you have CPC type agreements and partner for when you have cross promotion or links within other apps or you have CPM type of arrangement), the following parameters need to be added to your ad/partner links:
    • tu = ad (this value can only be ad or partner)
    • st1 = Ad Provider Name
    • st2 = Category (i.e. US_SanFrancsco_18-25)
    • st3 = Content (i.e. Banner A)
  2. As soon as a user clicks on your ad and comes to your landing page (even before the facebook permissions page), the URL will have these 4 parameters.
  3. You will need to take these four parameters from the URL and include the values in the st1, st2, st3 and tu (kt_type) parameters of the ucc message. You will also provide the other parameters required. See examples in the attached spreadsheet. The su parameter is a unique short tracking code that your system creates every time you send us a ucc message.
  4. If the user continues to install the application, you must include the same short tracking code in the su parameter of the apa (Application Install) API call. This way we can ensure that the install is attributed to the ad that brought the user to your application.

Function

trackThirdPartyCommClick($type, $optionalParams = array(), &$validationErrorMsg = null)

Required Parameters

If the user chooses to install the application, you must call the trackApplicationAdded() method immediately following install. Additionally, the $optionalParams['shortUniqueTrackingTag'] parameter in this method and the trackApplicationAdded() method must match.

ParameterTypeDescription
$typestringThe source of the user click, either an advertisement or partner link. If the click is from an advertisement, pass the string ad in this parameter. If the click is from a partner link, pass the string partner.

Optional Parameters

ParameterTypeDescription
$optionalParamsarrayAn associative array containing paramName => value.
$optionalParams['shortUniqueTrackingTag']stringA 8-digit unique hexadecimal string that is used to match installs to corresponding advertisement or partner link clicks. Valid characters are a-f, A-F, 0-9. This must match the $optionalParams['shortUniqueTrackingTag'] parameter in the trackApplicationAdded() method.
$optionalParams['userId']string

The UID of the user who clicked on the ad or partner link.

Note! Upsight will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

$optionalParams['subtype1']stringAn alpha-numeric label, up to 31 characters long. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype2'] is used.
$optionalParams['subtype2']stringAn alpha-numeric label, up to 31 characters long. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if $optionalParams['subtype3'] is used.
$optionalParams['subtype3']stringAn alpha-numeric label, up to 31 characters long. Valid characters are a-z, A-Z, 0-9, -, and _.
$validationErrorMsgstringIf the $optionalParams['validateParams'] parameter in the __construct() method is set to TRUE, the Upsight system will validate this method and return any error codes into this parameter. Otherwise, no action is taken.
$optionalParams['data']stringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.

Helper Methods

Constructor


__construct Constructor class method.

Important This function returns the generated tracking tag as a string.

URL

This method does not wrap any Upsight Data Collection API call.

Required Parameters

ParameterTypeDescription
$apiKeystringYour application's Upsight API key.

Optional Parameters

ParameterTypeDescription
$optionalParamsstringAn associative array containing paramName => value.
$optionalParams['useTestServer']boolDetermines if data is sent to the Upsight Test or Production servers. For QA, use the Test server, and set this value as TRUE. To send data to Production, set this value as FALSE.
$optionalParams['useHttps']boolDetermines if data is sent to the Upsight servers using HTTPS.
$optionalParams['validateParams']boolDetermines if parameters passed into the tracking methods will be validated by Upsight servers. If set to TRUE, the tracking methods will return the appropriate error code into the $validationErrorMsg parameter in each method. If set to FALSE, no validation will be set and no error codes will be sent to the $validationErrorMsg parameter.

Helper Methods

Unique Tracking Tag


genUniqueTrackingTag() Function to automatically generate a unique tracking tag. Unique tracking tags are used to correlate advertisement and partner link clicks with any user installs that occur through these channels.

Important! This function returns the generated tracking tag as a string.

URL

This method does not wrap any Upsight Data Collection API call.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Helper Methods

Short Unique Tracking Tag


genShortUniqueTrackingTag() Function to automatically generate a short unique tracking tag. Unique tracking tags are used to correlate advertisement and partner link clicks with any user installs that occur through these channels.

Important! This function returns the generated tracking tag as a string.

URL

This method does not wrap any Upsight Data Collection API call.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.