Upsight logo Back to top

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.

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.

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.