Upsight logo Back to top

Basic Messages

Application Added (apa)

Overview


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 Analytics side.

Application Added (apa)

URL


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

Application Added (apa)

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.

Application Added (apa)

Optional Parameters


Parameter Type Description
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 ins/inr, pst/psr, or nes/nei API calls that the install originated from.

Important! This variable is required if the installation occurred via an invite, notification email, or stream post. If this tag is not included for installs as a result of invite, notification, email, or stream post, this install will not be counted towards virality, which will result in a lower virality value than actuality.

sustring

An 8-digit unique hexadecimal string. If a click is from an advertisement, link, or partner site, use this parameter instead of the u parameter. Valid characters are a-f, A-F, 0-9. This parameter must match the su parameter in the associated ucc API call.

Important! This variable is required if the installation occurred from an undirected communication click (such as an ad or partner link) and must follow an ucc API message call. If this tag is not included from installs resulting from an undirected communication click, traffic source information will not be properly attributed. Additionally, there will never be a case where both the su and u parameters are used, as an user can only install an application through one communication channel.

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.

User Information (cpu)

Overview


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

User Information (cpu)

Best Practice


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.

User Information (cpu)

URL


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

User Information (cpu)

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.

User Information (cpu)

Optional Parameters


ParameterTypeDescription
bintThe year of the user's birth, in YYYY format.
gcharThe gender of the user. Accepted parameter values are: m (Male), f (Female), and u (Unknown, if no gender is specified).
lcstring

The 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 parameter included in the pgr message.

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 Analytics, 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.

fintThe number of friends a user has.
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 Request/User Location (pgr)

Overview


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&nocache=2009-4-22T04:08:35" width="0" height="0">

Page Request/User Location (pgr)

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 that the user is still actively participating in a session and allow for more granular tracking of short session length times.

Page Request/User Location (pgr)

URL


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

Page Request/User Location (pgr)

Required Parameters


ParameterTypeDescription
sunsigned 63-bit int

The UID of the user accessing the page.

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

nocacheintIf you are sending the message from the client side, set this parameter to a timestamp or other unique value to prevent browser caching.

Page Request/User Location (pgr)

Optional Parameters


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