Upsight logo Back to top

Advanced Messages

Application Removed (apr)

Overview


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

Application Removed (apr)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/apr/?<PARAMETER>=<DATA>

Application Removed (apr)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user removing the application.

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

Application Removed (apr)

Optional Parameters


ParameterTypeDescription
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.

Custom Event (evt)

Overview


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 32,759.

Custom Event (evt)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/evt/?<PARAMETER>=<DATA>

Custom Event (evt)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user performing the action, or initiating the event.

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

nstringThe event name, up to 31 characters long, describing the event. Valid characters are a-z, A-Z, 0-9, -, and _.

Custom Event (evt)

Optional Parameters


ParameterTypeDescription
vsigned intAn arbitrary value you assign to associate with the event. The default value is 0.
lunsigned 8-bit intA level value, which can be associated to an action to indicate what game level the user 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.
st1stringAn 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.
st2stringAn 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.
st3stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
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.

Goal Counts (gci)

Overview


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 Analytics know that player 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.

Goal Counts (gci)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/gci/?<PARAMETER>=<DATA>

Goal Counts (gci)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user.

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

gc1, gc2, gc3, or gc4intThe goal count identifier, a value assigned to this goal count, in the range of -16384 to 16384.

Goal Counts (gci)

Optional Parameters


ParameterTypeDescription
datastring Additional 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)

Overview


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.

Invite Sent (ins)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/ins/?<PARAMETER>=<DATA>

Invite Sent (ins)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user adding the application.

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

rcomma-separated string

A list of recipient UIDs, separated by commas. Must be URL-encoded.

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

ustring

A 16-digit unique hexadecimal string to track an invite, notification email, or stream post; generated if the user installed the application as a result of clicking on an invite, notification, email, or post. Valid characters are a-f, A-F, 0-9. This parameter must match the u parameter in the associated apa API calls that the install originated from.

Invite Sent (ins)

Optional Parameters


ParameterTypeDescription
st1string An 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 st2 is used.
st2string An 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 st3 is used.
st3string An 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 _.
datastring Additional 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)

Overview


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.

Invite Response (inr)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/inr/?<PARAMETER>=<DATA>

Invite Response (inr)

Required Parameters


ParameterTypeDescription
ibyte Indicates whether the recipient has already installed the application. This parameter should always be 0. If set to 1, Upsight Analytics will ignore any apa call with a matching tag and it will be assumed that the user has already installed.
ustring A 16-digit unique hexadecimal string that is used to match Invite Response messages to Invite Sent (ins) messages. Valid characters are a-f, A-F, 0-9. If an application install occurs, the u parameter in the apa API call must match this string.

Invite Response (inr)

Optional Parameters


ParameterTypeDescription
rcomma-separated string

The UID of the user that is responding. This parameter will contribute to the DAU count. Additionally, it is important to ensure all r parameters are valid UIDs. If using Facebook IDs, this means the UID used in this parameter should return a valid Facebook profile page.

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

st1string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype1 of the corresponding Invite Sent message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
st2string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype2 of the corresponding Invite Sent message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 is used.
st3string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype3 of the corresponding Invite Sent message. Valid characters are a-z, A-Z, 0-9, -, and _.
datastring Additional 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)

Overview


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

Notification Email Sent (nes)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/nes/?<PARAMETER>=<DATA>

Notification Email Sent (nes)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user adding the application.

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

rcomma-separated string

A list of recipient UIDs, separated by commas. Must be URL-encoded.

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

ustring

A 16-digit unique hexadecimal string to track an invite, notification email, or stream post; generated if the user installed the application as a result of clicking on an invite, notification, email, or post. Valid characters are a-f, A-F, 0-9. This parameter must match the u parameter in the associated nei API calls that the install originated from. If an install occurs, the u parameter in the apa API call must match this string.

Notification Email Sent (nes)

Optional Parameters


ParameterTypeDescription
st1string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype1 of the corresponding Notification Email Response (nei) message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
st2string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype2 of the corresponding Notification Email Response (nei) message. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 is used.
st3string An alpha-numeric label, up to 31 characters long, to categorize the event. Must match subtype3 of the corresponding Notification Email Response (nei) message. Valid characters are a-z, A-Z, 0-9, -, and _.
datastring Additional 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)

Overview


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

Notification Email Response (nei)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/nei/?<PARAMETER>=<DATA>

Notification Email Response (nei)

Required Parameters


ParameterTypeDescription
ibyte Indicates whether the recipient of the email has already installed the application. This parameter should always be 0. If set to 1, Upsight Analytics will ignore any apa call with a matching tag and it will be assumed that the user has already installed.
ustring

A 16-digit unique hexadecimal string to track an invite, notification email, or stream post; generated if the user installed the application as a result of clicking on an invite, notification, email, or post. Valid characters are a-f, A-F, 0-9. This parameter must match the u parameter in the associated nes API calls that the install originated from. If an install occurs, the u parameter in the apa API call must match this string.

Notification Email Response (nei)

Optional Parameters


ParameterTypeDescription
rcomma-separated string

The UID of the recipient responding to the email newsletter. This may not be available if the user has not yet added the application.

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

st1stringNotification Email subtype 1, up to 31 characters long, must match subtype 1 of the corresponding Notification Email Sent (nes) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
st2stringNotification Email subtype 2, up to 31 characters long, must match subtype 2 of the corresponding Notification Email Sent (nes) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 i used.
st3stringNotification Email subtype 3, up to 31 characters long, must match subtype 3 of the corresponding Notification Email Sent (nes) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
datastring Additional 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)

Overview


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

Revenue Tracking (mtu)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/mtu/?<PARAMETER>=<DATA>

Revenue Tracking (mtu)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user for which revenue is being tracked.

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

vintThe 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).

Revenue Tracking (mtu)

Optional Parameters


ParameterTypeDescription
tustringThe 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.
st1stringA subtype of 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 st2 is used.
st2stringA subtype of 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 st3 is used.
st3stringA subtype of 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 _.
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.

Stream Post (pst)

Overview


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.

Stream Post (pst)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/pst/?<PARAMETER>=DATA

Stream Post (pst)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user who made the post.

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

tustringFacebook stream, or non-Facebook stream equivalent (for other social networks) channel type. Pass stream in this parameter.
ustringA 16-digit unique hexadecimal string that is used to match Stream Post messages to Stream Response (psr) messages. Valid characters are a-f, A-F, 0-9. If an install occurs, the u parameter in the apa API call must match this string.

Stream Post (pst)

Optional Parameters


ParameterTypeDescription
st1stringPost subtype 1, up to 31 characters long, must match subtype 1 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
st2stringPost subtype 2, up to 31 characters long, must match subtype 2 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 is used.
st3stringPost subtype 3, up to 31 characters long, must match subtype 3 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
datastring Additional 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)

Overview


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.

Stream Response (psr)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/pst/?<PARAMETER>=DATA

Stream Response (psr)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user who made the post.

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

tustringFacebook stream, or non-Facebook stream equivalent (for other social networks) channel type. Pass stream in this parameter.
ustringA 16-digit unique hexadecimal string that is used to match Stream Post messages to Stream Response (psr) messages. Valid characters are a-f, A-F, 0-9. If an install occurs, the u parameter in the apa API call must match this string.

Stream Response (psr)

Optional Parameters


ParameterTypeDescription
st1stringPost subtype 1, up to 31 characters long, must match subtype 1 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st2 is used.
st2stringPost subtype 2, up to 31 characters long, must match subtype 2 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _. Not optional if st3 is used.
st3stringPost subtype 3, up to 31 characters long, must match subtype 3 of the corresponding Stream Post Response (psr) message. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
datastring Additional 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)

Overview


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.

Third Party Comm. Clicks (ucc)

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.

Third Party Comm. Clicks (ucc)

URL


http://api.geo.kontagent.net/api/v1/<API KEY>/ucc/?<PARAMETER>=<DATA>

Third Party Comm. Clicks (ucc)

Required Parameters


ParameterTypeDescription
ibyte Indicates whether the recipient has already installed the application. This parameter should always be 0. If set to 1, Upsight Analytics will ignore any apa call with a matching tag and it will be assumed that the user has already installed.
tustringThe undirected communication type. Either an advertisement or partner link. Valid values are ad and partner
sustringAn 8-digit hexadecimal string sent with each user click originating from an ad or partner link. Valid characters are a-f, A-F, 0-9. If you wish to track application installs originating from an ad or partner link, this parameter is required in the apa API call. The su parameter in the apa API call must match this string.

Third Party Comm. Clicks (ucc)

Optional Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user who responded to an ad or partner link.

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

st1stringAn 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.
st2stringAn 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.
st3stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
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.