App Events for Games on Facebook

App events allow you to view analytics, measure ad performance and build audiences for ad targeting for your Game on Facebook.

This is done by sending an event from your app via Facebook SDK for JavaScript. This event can be one of 12 predefined events such as 'added to cart' in a commerce app or 'level achieved' in a game, or other custom events.

Prerequisites

Before including the code to measure events, you will need to register your app with Facebook. If you haven't registered your app with Facebook, you can do so here: Games on Facebook Quickstart .

Implementation

Your Game on Facebook should already be including the Facebook SDK for JavaScript. If not, read our JavaScript quickstart guide.

Automatic Logging of Events

We automatically log the following events for Games on Facebook:

• App Install: The first time a person accepts the terms of service for your app.
• App Launched: Anytime a person opens the webpage containing your app.

If you have enabled payments through Facebook - the following additional events are logged:

• Initiated Checkout: A person starts the payment process to make a purchase.
• Purchased: A person successfully completes a payment in your app.
• Purchase Cancelled: A person cancelled their payment (includes both manually cancelled payments and when the payment method failed).

Note: a purchase cancelled event may not be logged if the person closes their browser window mid-purchase. This is why purchase cancelled events may not equal the difference between initated checkout events and purchases events.

You can view your automatically logged events within Facebook Analytics for Apps

Log Events with Parameters

You can decide to log additional in addition to the automatically logged events to better measure the performance of your app on Facebook.com. For instance, you may want to log an event any time someone completes a level in your game.

Below is an example of how you can log an event along with a parameter that describe your event:

var params = {};
params[FB.AppEvents.ParameterNames.LEVEL] = '12'; //player level
FB.AppEvents.logEvent(
  FB.AppEvents.EventNames.ACHIEVED_LEVEL,
  null,  // numeric value for this event - in this case, none
  params
);

We recommend using one of the 12 pre-defined events which can be found here. However, we also support logging custom events.

Log Purchases

The Facebook SDK includes a dedicated function for logging purchases, which requires the specification of a currency.

Note that payments done via Games on Facebook are automatically logged as purchase events. It is only necessary to use the following code for sales of physical items.

  var params = {};
  params[FB.AppEvents.ParameterNames.CONTENT_ID] = 'QW-12345';
  FB.AppEvents.logPurchase(98.76, 'USD', params);

Note: to use the predefined parameters, you have to create the params object first, then pass it to the function as shown below.

  var params = {};
  params[FB.AppEvents.ParameterNames.CONTENT_ID] = '12345';
  FB.AppEvents.logPurchase(98.76, 'USD', params);

Custom App Events

You can also choose to create your own custom events, which is done simply by specifying their name as a string:

FB.AppEvents.logEvent('battledAnOrc');

Note the maximum length for a customized event name is 40 characters and should consist only of alphanumerics, underscores, or dashes.

Catch Exceptions

Note that if you call the provided SDK JavaScript function with incorrect parameters, the function will throw an exception. Make sure your code passes the correct parameters, and catch any exceptions if they occur.

Access your App Events Report

1. Open the Analytics for Apps Dashboard: https://www.facebook.com/analytics
2. Select your app.
3. Go to the section Events.

Or use the URL www.facebook.com/analytics/{YourAppIdHere}?section=AppEvents and replace {YourAppIdHere} with your app ID.

Debug

To improve performance, the JavaScript SDK is loaded minified. You can also load a debug version of the JavaScript SDK that includes more logging and stricter argument checking as well as being non-minified. To do so, change the js.src value in your loading code to this:

js.src = "//connect.facebook.net/en_US/sdk/debug.js";

Reference

• Javascript SDK
• AppEvents.LogEvents Reference