Upsight logo Back to top

Basic Messages

Application Added (apa)


Function

trackApplicationAdded(userId, optionalParams, successCallback, validationErrorCallback)

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
userIdintThe UID of the user installing the application.
Note Upsight Analytics will only be able accept 63-bits integers. For information on converting UIDs to fit the requirement, click here.

Optional Parameters

ParameterTypeDescription
optionalParamsobjectAn object containing paramName => value.
optionalParams.uniqueTrackingTagstringA 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.shortUniqueTrackingTagstringAn 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.
successCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, the SDK will call this callback function to execute once the message has been sent successfully.
validateErrorCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, and an invalid parameter is detected, the SDK will call this function to execute on validation failure.
optionalParams.datastringAdditional 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)


Function

trackUserInformation(userId, optionalParams, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIDstring

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

Optional Parameters

ParameterTypeDescription
optionalParamsobjectAn object containing paramName => value.
optionalParams.birthYearintThe year of the user's birth, in YYYY format.
optionalParams.genderstringThe gender of the user. Accepted parameter values are: m (Male), f (Female), and u (Unknown, if no gender is specified).
optionalParams.countrystringThe 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.friendCountintThe number of friends a user has.
successCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, the SDK will call this callback function to execute once the message has been sent successfully.
validateErrorCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, and an invalid parameter is detected, the SDK will call this function to execute on validation failure.
optionalParams.datastringAdditional 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 Requests/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, Top Searches, 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 Analytics 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 Analytics 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, successCallback, validationErrorCallback)

Required Parameters

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

Optional Parameters

ParameterTypeDescription
optionalParamsobjectAn object containing paramName => value.
optionalParams.pageAddressstringThe 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.ipAddressstringThe IP address of the user requesting the page. If this message is sent to the Upsight Analytics API server directly from your server, you must set this parameter.
successCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, the SDK will call this callback function to execute once the message has been sent successfully.
validateErrorCallBackfunctionIf the optionalParams.validateParams parameter in the KontagentApi constructor method is set to TRUE, and an invalid parameter is detected, the SDK will call this function to execute on validation failure.
optionalParams.datastringAdditional data, a JSON object string representing a dictionary or map of key-value pairs. It must be base64-encoded. Click here for more information.