Upsight logo Back to top

Data Collection API

Quick Start Guide

Engagement Tracking


What metrics are important?

  • DAU/WAU/MAU
  • Number of Pageviews
  • Number of Sessions
  • Session Length

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters Where
pgrs, nocacheu Landing pages

Note For Facebook, the u parameter is pulled automatically from client side calls using Facebook fbx_type and fbx_ref references. Add the optional u parameter if you send this message server side, or if you wish to override the call.

Quick Start Guide

Install Tracking


What metrics are important?

  • DAU/WAU/MAU
  • New Installs
  • Installs

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters Where
apas None On application install

Quick Start Guide

User Insights


What metrics are important?

  • Age
  • Gender
  • Location
  • Number of Friends (Facebook specific)

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters Where
cpusb, g, lc, f Landing pages
pgrs, nocacheip On application install

Note The ip parameter is pulled automatically from client side calls using the machine's IP address. If you are sending this call server side, you must explicitly include the ip parameter.

Quick Start Guide

Acquisition Tracking: Invites


What metrics are important?

  • Invites Sent
  • Invites Response
  • Invites Acceptance Rate
  • Invites Install

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters1 Where
inss, u, r2st1, st2, st3 Invite
inru, i3r, st1, st2, st3 Invite Response
apau, s None Invite Install

1 During app usage, users are presented with the chance to invite their friends to join them. At the time when the user invites his/her friends, the app sends the ins API call to Upsight Analytics.

2 If a recipient clicks on the link in the invitation and arrives on the app permissions landing page, the app sends the inr API call to Upsight Analytics with the same u parameter that was present in the ins call. Do not wait until an install has occurred to send the inr API call.

3 If the user then installs the application, the app sends the apa call with the sameu parameter that was in both the ins and inr calls. Proper attribution of install and virality metrics will only be tracked if the u parameter is the same across all three messages: ins, inr and apa.

Example API Call

ins

s=1234567&u=1111DCBA1111DCBA&r=100000432&st1=gift&st2=apple&st3=green

inr

i=0&u=1111DCBA1111DCBA&r=100000432&st1=gift&st2=apple&st3=green

apa

s=100000432&u=1111DCBA1111DCBA

Quick Start Guide

Acquisition Tracking: Streams


What metrics are important?

  • Stream Stories Posted
  • Stream Stories Clicked
  • Stream Installs

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters1 Where
psts, u, tu='stream'st1, st2, st3 Stream Post
psru, tu='stream', i2r, st1, st2, st3 Stream Post Click
apau, s None Stream Post Install

1 Any optional parameters sent from the original pst message must be sent in the pst message exactly the same.

2 The i parameter should be set to 0, to indicate that the user clicking the stream post has not installed the application.

Workflow Example

  1. During app usage, users are presented with the chance to post updates to their wall based on an event in the app. At the time when the user posts an update to their wall from within the app, the app sends the pst API call to Upsight Analytics.

  2. If one of the users' friends clicks on the post link and arrives on the app permissions landing page, the app sends the psr API call to Upsight Analytics, along with the same u parameter that was present in the pst API call. Do not wait until an install has occurred to send the psr API call.

  3. If the user then installs the application, the app sends the apa call with the sameu parameter that was in both the pst and psr calls. Proper attribution of install and virality metrics will only be tracked if the u parameter is the same across all three messages: pst, psr and apa.

Example Call

pst

s=1234567&u=ABCDEEEEABCDEEEE&tu=stream&st1=levelup&st2=share

psr

i=0&u=ABCDEEEEABCDEEEE&tu=stream&st1=levelup&st2=share

apa

s=100000987&u=ABCDEEEEABCDEEEE

Quick Start Guide

Acquisition Tracking: Traffic


What metrics are important?

  • Ad Clicks and Installs
  • Cohort Metrics

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters Where
uccsu, tu='ad' or tu='partner', i1st1, st2, st3 Detect on landing pages if from an undirected communication source click
apasu, s None Install from undirected communication source click

1 The i parameter should be set to 0, to indicate that the user has not already installed the application.

Workflow Example

When you buy ads (regardless of the provider) or want to track user acquisition from a partner link (i.e. any arrangement like a cross promotion or links within other apps or you pay on a CPM basis instead of a CPC basis), the parameters below will need to be added to your ad links:

  1. As soon as a user clicks on your ad/link and comes to your landing page (this is typically the permissions page of your app), the link URL will have these 4 parameters:
    • kt_type: The value of this parameter must be ad or partner. You use ad for when you have CPC type agreements, and partner for when you have cross promotion or links within other apps, or if you have a CPM type of arrangement.
    • st1: This is the Campaign Name, which usually is denoted by the Ad/Partner's name.
    • st2: This is the Category, usually denoting the target demographic. For example: US_SanFrancisco_18-25.
    • st3: This is the Content of the ad. The st3 parameter enables you to differentiate between ad content shown. For example: Banner A, Banner B, Banner C.
  2. You will need to take the above four parameters from the link URL, and include the values in the st1, st2, st3 and tu (kt_type) parameters of the ucc API call, in addition to the other required parameters. The su parameter is a unique short tracking code that your system creates every time you send a ucc API call. Please note that you send the ucc API call to Upsight when the user lands on the landing page. Do not wait until an install occurs to send a this call.
  3. If the user continues to install the application, you must include the same short tracking code in the su paramater of the apa API call. This way we can ensure that the install is attributed to the ad that brought the user to your application. If the su parameter is not included in the apa API call, Upsight will not be able to attribute the install to the appropriate source.

Quick Start Guide

Monetization Tracking


What metrics are important?

  • Revenue Total
  • ARPU
  • ARPPU
  • % Paying Users

What API calls do I instrument to capture the metrics above?

Data Collection API Call Required Parameters Optional Parameters Where
mtus, v1tu2, st1, st2, st3 Revenue transaction

1 The v parameter must be set in cents, and can be either a positive or negative number. For example, a transaction of $1.25 should be set as v = 125.

2 The parameter tu is required if st1 is used. The possible values for tu are direct, indirect, advertisement, credits, or other.

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.

URL

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

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.

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.

Basic Messages

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.

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.

URL

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

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.

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.

Basic Messages

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">

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.

URL

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

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.

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.

Advanced Messages

Application Removed (apr)


Overview

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

URL

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

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.

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.

Advanced Messages

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.

URL

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

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

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.

Advanced Messages

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.

URL

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

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.

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.

Advanced Messages

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.

URL

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

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.

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.

Advanced Messages

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.

URL

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

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.

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.

Advanced Messages

Notification Email Sent (nes)


Overview

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

URL

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

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.

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.

Advanced Messages

Notification Email Response (nei)


Overview

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

URL

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

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.

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.

Advanced Messages

Revenue Tracking (mtu)


Overview

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

URL

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

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

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.

Advanced Messages

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.

URL

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

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.

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.

Advanced Messages

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.

URL

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

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.

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.

Advanced Messages

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.

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.

URL

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

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.

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.