Upsight logo Back to top

Enterprise JavaScript

Quick Start Guide

The Basics


This is a JavaScript SDK around Upsight Analytics's Data Collection API. It provides methods to make the API calls for all the different message types supported by Upsight.

Download SDK

To get started with the Upsight Analytics library, you will need to download the JavaScript SDK from the SDK Downloads page and include it in your project.

You will also need to instantiate and configure an instance of the Kontagent object.

// include the library
<script src="./kontagent_api.js"></script>

<script>

// configure and instantiate Kontagent object
var ktApi = new KontagentApi(ktApiKey);

</script>

Quick Start Guide

Using the Library


Overview

Once you've got your Kontagent object instantiated and configured you can start using the library. Essentially, there are two types of methods provided in the library: tracking methods and helper methods.

Tracking Methods

The tracking methods should get called by your application whenever you need to report an event to Upsight Analytics. There is a tracking method available for every message type in the Kontagent Data Collection API. A few examples are:

<script>

ktApi.trackPageRequest('1234567890', {pageAddress : '/game.html'}, function() {
    // request has been successfully sent
    console.log('pageview tracked');
});

ktApi.trackEvent(
    '1234567890',
    'mission_1',
    {
        subtype1 : 'user_action',
        subtype2 : 'game_played'
    },
    function() {
        console.log('event tracked');
    }
);

</script>

When events happen within your application, you should make the appropriate call to Upsight Analytics. We will then crunch and analyze this data in our systems and present them to you in your dashboard.

For a full list of the available tracking methods, refer to the JS SDK specification below.

Helper Methods

The library provides a few helper methods for common tasks. Currently the only ones available are:

<script>

var uTag = ktApi.genUniqueTrackingTag();

var shortUTag = ktApi.genShortUniqueTrackingTag();

</script>

These methods will help you generate the tracking tag parameters required to link certain messages together (for example: invite sent -> invite response -> application added).

Quick Start Guide

Facebook


If you are not instrumenting with the Upsight Analytics Facebook SDK and instead instrumenting with this wrapper, you may run into some issues. Please see our Facebook Best Practices page for troubleshooting tips.

Quick Start Guide

HTTPS


If sending a request to HTTPS, set optionalParams.useHttps to TRUE in the constructor, just as would set useTestServer to true when using the test server.

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.

Basic Messages

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.

Basic Messages

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.

Advanced Messages

Application Removed (apr)


Function

trackApplicationRemoved(userId, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdstringThe UID of the user removing 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.
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.

Advanced Messages

Custom Event (evt)


Function

trackEvent(userId, eventName, optionalParams, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdunsigned 63-bit int

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

Note! Upsight Analytics 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
optionalParamsobjectAn object containing paramName => value.
optionalParams.valueintAn arbitrary value you assign to associate with the event. The default value is 0.
optionalParams.levelintA 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.
optionalParams.subtype1stringAn 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.subtype2stringAn 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.subtype3stringAn alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
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.

Advanced Messages

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 Analytics 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, 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.goalCount1intThe value to increase goalCount1 by. This value can be any integer in the range of -16384 to 16384.
optionalParams.goalCount2intThe value to increase goalCount2 by. This value can be any integer in the range of -16384 to 16384.
optionalParams.goalCount3intThe value to increase goalCount3 by. This value can be any integer in the range of -16384 to 16384.
optionalParams.goalCount4intThe value to increase goalCount4 by. This value can be any integer in the range of -16384 to 16384.
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.

Advanced Messages

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 wil reflect this as two actual invites.

Function

trackInviteSent(userId, recipientUserIds, uniqueTrackingTag, optionalParams, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdint

The UID of the user sending the invitation. For app to user notifications, set this value to 0.

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

recipientUserIdsstring

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

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

uniqueTrackingTagstringA 16-digit unique hexadecimal string that is used to match Invite Sent messages to Invite Response 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
optionalParamsobjectAn object containing paramName => value.
optionalParams.subtype1stringAn 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.
optionalParams.subtype2stringAn 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.
optionalParams.subtype3stringAn 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 _.
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.

Advanced Messages

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, successCallback, validationErrorCallback)

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
optionalParamsobjectAn object containing paramName => value.
optionalParams.recipientUserIdstring

The UID of the responding user.

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

optionalParams.subtype1stringInvite 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.subtype2stringInvite 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.subtyp3 is used.
optionalParams.subtype3stringInvite 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 _.
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.

Advanced Messages

Notification Email Sent (nes)


Function

trackNotificationEmailSent(userId, recipientUserIds, uniqueTrackingTag, optionalParams, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdstring

The UID of the user initiating the action to send an email newsletter.

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

recipientUserIdsstring

The recipient UID(s) of the user(s) receiving the email newsletter, separated by commas.

Note! Upsight Analytics 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
optionalParamsobjectAn object containing paramName => value.
optionalParams.subtype1stringEmail 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.subtype2stringEmail 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.subtype3stringEmail 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 _.
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.

Advanced Messages

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, successCallback, validationErrorCallback)

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
optionalParamsobjectAn object containing paramName => value.
optionalParams.recipientUserIdstring

The UID of the responding user.

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

optionalParams.subtype1stringEmail 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.subtype2stringEmail 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.subtype3stringEmail 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 _.
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.

Advanced Messages

Revenue Tracking (mtu)


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

Function

trackRevenue(userId, value, optionalParams, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdunsigned 63-bit int

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

Note! Upsight Analytics 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
optionalParamsobjectAn object containing paramName => value.
optionalParams.typestringThe 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.subtype1stringA 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.subtype2stringA 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.subtype3stringA 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 _.
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.

Advanced Messages

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, successCallback, validationErrorCallback)

Required Parameters

ParameterTypeDescription
userIdstring

The UID of the user who made the post.

Note! Upsight Analytics 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
optionalParamsobjectAn object containing paramName => value.
optionalParams.subtype1stringStream post subtype 1, up to 31 characters long, must match the optionalParams.subtype1parameter 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.subtype2stringStream 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.subtype3stringStream post subtype 3, up to 31 characters long, must match the optionalParams.subtype3parameter in the corresponding trackStreamPostResponse() method. An alpha-numeric label to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.
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.

Advanced Messages

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

trackStreamResponse(type, uniqueTrackingTag, optionalParams, successCallback, validationErrorCallback)

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

The UID of the responding user.

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

optionalParams.subtype1stringStream 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.subtype2stringStream 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.subtype3stringStream 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 _.
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.

Advanced Messages

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, shortUniqueTrackingTag, optionalParams, successCallback, validationErrorCallback)

Required Parameters

As the user may not have yet installed your application, a UID may not be sent. 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 is then required, and must match the same parameter in the trackApplicationAdded() method.

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
optionalParamsobjectAn object containing paramName => value.
optionalParams.shortUniqueTrackingTagstringA 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.userIdstring

The UID of the user who clicked on the ad or partner link.

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

optionalParams.subtype1stringAn 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.subtype2stringAn 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.subtype3stringAn alpha-numeric label, up to 31 characters long. Valid characters are a-z, A-Z, 0-9, -, and _.
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.

Helper Methods

Constructor


Important! This function returns the generated tracking tag as a string.

URL

This method does not wrap any Data Collection API call.

Required Parameters

ParameterTypeDescription
apiKeystringYour application's Upsight Analytics API key.

Optional Parameters

ParameterTypeDescription
[optionalParams]objectAn associative array containing paramName => value.
[optionalParams.useTestServer]boolDetermines if data is sent to the Upsight Analytics Test or Production servers. For QA, use the Test server, and set this value as TRUE. To send data to Production, set this value as FALSE.
[optionalParams.useHttps]boolDetermines if data is sent to the Upsight Analytics servers using HTTPS.
[optionalParams.validateParams]boolDetermines if parameters passed into the tracking methods will be validated by Upsight Analytics servers. If set to TRUE, the tracking methods will call the successCallback function to validate the successful execution of that method, or return a validation error via the [validationErrorCallback] function. If set to FALSE, no validation checking will be present.

Helper Methods

Unique Tracking Tag


genUniqueTrackingTag() Function to automatically generate a unique tracking tag. Unique tracking tags are used to correlate advertisement and partner link clicks with any user installs that occur through these channels.

Important! This function returns the generated tracking tag as a string.

URL

This method does not wrap any Data Collection API call.

Required Parameters

No Required Parameters

Optional Parameters

No Optional Parameters

Helper Methods

Short Unique Tracking Tag


genShortUniqueTrackingTag() Function to automatically generate a short unique tracking tag. Unique tracking tags are used to correlate advertisement and partner link clicks with any user installs that occur through these channels.

Important! This function returns the generated tracking tag as a string.

URL

This method does not wrap any Data Collection API call.

Required Parameters

No Required parameters.

Optional Parameters

No optional parameters.