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.

Games on Facebook now automatically log the following events: App Install, App Launched, Initiated Checkout, Purchased, and Purchase Cancelled. It is not necessary to manually log these 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 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 automatically logged events within Facebook Analytics

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 12 pre-defined events. However, we also support logging custom events.

The maximum number of different event names is 1,000. Note: No new event types will be logged once this cap is hit and if you exceed this limit you may see an 100 Invalid parameter error when logging. However, it is possible to deactivate obsolete events. Read more about event limits in the FAQ.

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.

Access your App Events Report

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

Or use the URL www.facebook.com/analytics/{app_id}?section=AppEvents and replace {app_id} 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