Upsight logo Back to top

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.