Upsight logo Back to top

Enterprise Facebook

Facebook Best Practices


These Best Practices can assist you in troubleshooting any issues that may arise if you are instrumenting a Facebook application with the Upsight Analytics Data Collection API or one of our Web SDKs.
We highly recommend that you use either the Facebook PHP or Facebook JavaScript SDKs, as many issues that commonly arise will be taken care of by the SDK. However, we understand that this may not be the most suitable or flexible option for everyone.

How do I instrument Application Removes/Uninstalls?

To instrument Application Removes, you will first need to go into your Facebook application settings (Advanced). Specify a Deauthorize Callback, a URL that Facebook will ping when a user removes your application. On that page, send off an Application Removed message to Upsight Analytics along with the userID provided by Facebook.

How do I pass Upsight Analytics data across Facebook?

When instrumenting Upsight Analytics, you may notice that there is a need to pass data from one page to another or to maintain a state. Typically, this is achieved using URL variables (get parameters) as most of Facebook's methods allow for a callback URL to be specified by the application. This can be used, for example, to pass subtype or unique tracking tag data between pages.

An exception to this is Facebook "Requests" dialog, which is used to invite friends to your application. Facebook automatically redirects the recipients of invites and this prevents any way to pass data via URL variables. Fortunately, Facebook has provided a convenient data field in the Request object. The data field allows for additional data that you may pass for tracking. This method may be used for the same purpose such as obtaining u-tag information for example.

How do I know if it is a first time users install?

Facebook no longer specifies whether a given user is authorizing for the first time or they are already an existing user. Upsight Analytics addresses this issue by performing this check on our processing servers. Therefore, we recommend just sending the Upsight Analytics servers an apa message on every login and our processing servers will work out whether this is a new install or reinstall.

How do I access the App Request object if a user has not yet authorized?

When tracking invite responses, applications need to send an inr message to Upsight Analytics after a user has clicked through an invite. At this point, the user may not have authorized your application yet and therefore you may not have permission to access the Request object. However, the trick here is that you need to retrieve the object on the server side (using Facebook's PHP SDK). Due to security limitations, it cannot be accessed using the JavaScript SDK. The reason for this is that there are 2 types of tokens; the user_access_token and the app_access_token. If the user is not yet authorized, the app_access_token must be used. This token is not exposed on the clientside.

How do I track when a user visits my application from a link on Facebook.com (i.e. App Center, Feed, Timeline, etc.)?

When a user visits your application via a link on Facebook, a URL variable fb_source will be appended to the URL. This denotes where the user came from. For more details on the possible values for the variable, click here.

Facebook PHP


Download the latest PHP Facebook SDK

Click here to download the latest version.

Setting Up

To setup Upsight Analytics, you simply need to include the Facebook and Upsight Analytics SDK’s and instantiate the KontagentFacebook object. This is a wrapper around the Facebook class; it will provide the same functionality, such as automatically firing off tracking messages to Upsight Analytics).

require_once './facebook.php';
require_once './kontagent_facebook.php';

$KontagentFacebook = new KontagentFacebook(
    array(
        'appId' => '<FACEBOOK_APP_ID>',
        'secret' => '<FACEBOOK_APP_SECRET>'
    ),
    array(
        'apiKey' => '<KT_API_KEY>',
        'useTestServer' => false
    )
);

Note that the KontagentFacebook constructor takes in an additional argument containing Upsight Analytics configuration info.

You will want to instantiate this class at the top of every page in your application that you want to track because it automatically fires off tracking messages when the user lands.

Tracking

Tracking Page Views

Page views are automatically tracked behind the scenes.

Tracking Installs and User Information

To prompt the user for authorization, use the code below:

$KontagentFacebook->getLoginUrl();

Once the user accepts the dialog, the install and user information will be automatically tracked.

Tracking Invites and Responses

To track invites, use the standard Facebook Requests Dialog to prompt the user to invite their friends:

$KontagentFacebook->getRequestsDialogUrl(array(
    'message' => 'do it!', 
    'subtype1' => 'st1',
    'subtype2' => 'st2',
    'subtype3' => 'st3'
));

After the user confirms and sends the invite, it will be automatically tracked by Upsight Analytics.

Likewise, when the recipient responds and accepts the invite, the Invite Response and Install will be tracked upon landing in your app.

Tracking Stream Posts and Responses

To track stream posts, you need to use our helper function to prompt the user to post to their stream:

$KontagentFacebook->getFeedDialogUrl(array(
    'link' => 'http://yourapp.facebook.com', 
    'subtype1' => 'st1', 
    'subtype2' => 'st2',
    'subtype3' => 'st3'
));

The above function will display the standard Facebook Feed Dialog. After the user confirms and posts, it will automatically be tracked by Upsight Analytics.

Likewise, when the users click-through the post, the Stream Post Response and Install will be automatically tracked upon landing in your app.

Tracking Ad and Partner Clicks

To setup your landing page and ad/partner URLs, please refer to this page.

Sample Code

We have provided a sample demonstration for how to instrument this PHP SDK.

Facebook JavaScript


Download the latest JS Facebook SDK

Click here to download the latest version.

Setting Up

To setup Upsight Analytics, you simply need to include the Facebook and Upsight Analytics SDK’s and instantiate the KontagentFacebook object. This is a wrapper around the Facebook class; it will provide the same functionality, such as automatically firing off tracking messages to Upsight.

Note that the KontagentFacebook constructor takes in an additional argument containing Upsight Analytics configuration info.

You will want to instantiate this class at the top of every page in your application that you want to track because it automatically fires off tracking messages when the user lands.

Synchronous Loading

<div id="fb-root"></div>

<script src="http://connect.facebook.net/en_US/all.js"></script>

<script src="./kontagent_facebook.js"></script>

<script>
    FB.init(
    {
        appId   : '<FACEBOOK_APP_ID>',
        channelUrl: ‘<FACEBOOK_CHANNEl_FILE>’,
        status : true,
        cookie : true,
        xfbml   : true
    },
    {
        apiKey: '<KT_API_KEY>',
        useTestServer: false
    }
    );
</script>

Asynchronous Loading

<div id="fb-root"></div>

<script>
    window.fbAsyncInit = function() {
        FB.init(
        {
            appId:'<FACEBOOK_APP_ID>',
            channelUrl: ‘<FACEBOOK_CHANNEl_FILE>’,
            status : true, 
            cookie : true, 
            xfbml   : true 
        }, 
        {
            apiKey: '', 
            useTestServer: false 
        }
        ); 
}
</script>

<script src="./kontagent_facebook.js"></script> 

<script>
        // Load the SDK Asynchronously
        (function(d) {
            var js, id = 'facebook-jssdk', ref = d.getElementsByTagName('script')[0];
            if (d.getElementById(id)) {return;}
            js = d.createElement('script'); js.id = id; js.async = true;
            js.src = "//connect.facebook.net/en_US/all.js";
            ref.parentNode.insertBefore(js, ref);
        }(document));
</script>

Tracking

Tracking Page Views

Page views are automatically tracked behind the scenes.

Tracking Installs and User Information

To prompt the user for authorization, use the code below:

FB.login(
    function(response) { 
        console.log(response); 
    },
    {
        scope: 'email, user_birthday'
    }
);

Once the user accepts the dialog, the install and user information will automatically be tracked.

Tracking Invites and Responses

To track invites, you need to use the standard Facebook Requests Dialog to prompt the user to invite their friends:

FB.ui(
        {
            method: "apprequests",  
            message: "You should learn more about this game.", 
            data: "tracking information for the user",
            subtype1: "st1", 
            subtype2: "st2" 
            subtype3: "st3" 
        }, 
        function(response) { 
            console.log(response); 
        }
);

After the user confirms and sends the invite, it will automatically be tracked by Upsight Analytics.

Likewise, when the recipient responds and accepts the invite, the Invite Response and Install will be automatically tracked upon landing in your app.

Tracking Stream Posts and Responses

To track stream posts, you need to use our helper function to prompt the user to post to their stream:

FB.ui(
    {
        method: "feed",
        link: "http://yourapp.facebook.com",
        subtype1: "st1",
        subtype2: "st2",
        subtype3: "st3"
    }, 
    function(response) {
        console.log(response); 
    }
);

The above function will display the standard Facebook Feed Dialog. After the user confirms and posts, it will be automatically tracked by Upsight Analytics.

Likewise, when the users click-through the post, the Stream Post Response and Install will be automatically tracked upon landing in your app.

Tracking Ad and Partner Clicks

To setup your landing page and ad/partner URLs, please refer to this page.

Tracking Custom Events, Goal Counts, and Other Messages

To send other tracking methods to Upsight Analytics (such as custom events, goal counts, etc.) you can retrieve the KontagentApi object. This object provides a method to fire off all the message types supported by Upsight. The Kontagent FB object provides a getter for accessing this:

FB.getKontagentApi(); 

Sample Code

We have provided a sample demonstration for how to instrument this JS SDK.

Click Tracking


1. Downloads

Based on the Upsight Analytics Facebook SDK you are using, download one of the landing zip archives below.

2. Setting Up Landing Page

To track ad/partner clicks, you will first need to download and setup a landing page. The landing page is where you want to point your ad/partner links to the landing page will then perform the tracking and redirect the user to your application.

Download one of the libraries above (either JS or PHP), and edit the file. You will need to fill in the following configuration variables at the top of the file:

KT_API_KEY = ''
KT_USE_TEST_SERVER = false;
FB_CANVAS_PAGE_URL = 'http://apps.facebook.com/__/';
KT_BASE_API_URL = 'http://api.geo.kontagent.net/api/v1/';
KT_BASE_TEST_SERVER_URL = 'http://test-server.kontagent.com/api/v1/';

Finally, upload the file to your web server.

3. Pointing your Ads/Partner to Landing Page

Once the landing page is set up and uploaded, point your ads to the landing page.

http://www.yourserver.com/landing.html?kt_type=value
http://www.yourserver.com/landing.php?kt_type=value

When a user hits this page, the landing page will automatically fire off a Undirected Communication Click (ucc) message to Upsight Analytics (parsing and appending the kt_type, kt_st1, kt_st2, and kt_st3).

The user is then redirected to kt_redir_url along with the consumed short unique tracking tag (appended as URL parameter kt_su). If the user proceeds to install, this short tracking tag should be included in the apa message to associate the install back to the click (see next section for details on handling installs).

Required Parameters

Parameter Type Description
kt_redir_urlString Redirect URL. The actual landing page URL you want the user to be redirected to.
kt_typeString Type. The undirected communication type, either an advertisement or partner link. Valid values are ad and partner.

Optional Parameters

Parameter Type Description
kt_st1String An 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.
kt_st2String An 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.
kt_st3String An alpha-numeric label, up to 31 characters long, to categorize the event. Valid characters are a-z, A-Z, 0-9, -, and _.

4. Handling Installs

When the user lands on your application page after being redirected from the landing page, you will notice that there is a kt_su parameter in the URL. This is the short unique tracking tag associated with the ad click and is used to associate installs back to a particular click.

After the user lands on your page, you will probably want to prompt them to install. When the user completes the installation, you will want to send Upsight Analytics an Application Added (apa) message. Make sure to include the short unique tracking tag.

Note that if you are using our Facebook SDK, you simply need to follow the instructions for “Tracking Installs” and the install will automatically be attributed to the ad/partner click