App Events for Games on Facebook

App events allow you to 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 pre-defined 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.

You can view your logged events using the Facebook Events Manager.

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 Canceled: A person canceled their payment (includes both manually canceled payments and when the payment method failed).

Note: A Purchase Canceled event may not be logged if the person closes their browser window mid-purchase. This is why Purchase Canceled events may not equal the difference between Initiated Checkout events and Purchases events.

You can view your logged events using the Facebook Events Manager.

Log Events with Parameters

You can decide to log information 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 pre-defined events. 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.

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

To use the predefined parameters, create the params object 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 by specifying their name as a string:

FB.AppEvents.logEvent('battledAnOrc');

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

Catch Exceptions

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.

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 = "https://connect.facebook.net/en_US/sdk/debug.js";

Reference

• Javascript SDK
• AppEvents.LogEvents Reference