App Events for Websites

You can use app events on your website to better understand the actions people take and to see powerful, aggregated demographics in Facebook Analytics.

You can log events from your website using the Facebook SDK for JavaScript. You can log any of the predefined events we provide, such as purchase, add to cart, etc. You can also define new custom events that represent meaningful actions your customers take.

If you already have the Facebook Pixel installed in your website you can go right to the dashboard and access analytics for your Pixel. See Using Pixels and Event Source Groups for more information.

Implementing App Events on Your Website

Integrate the Facebook SDK for JavaScript with your website by following the Facebook SDK for JavaScript Quickstart Guide:

Facebook SDK for JavaScript Quickstart Guide

After you've integrated the SDK, log the PageView event on every page of your website to ensure you see accurate user counts and session time metrics in Facebook Analytics.

<script>
  window.fbAsyncInit = function() {
    FB.init({
      appId      : 'your-app-id',
      xfbml      : true,
      version    : 'v2.8' // or earlier version
    });
    FB.AppEvents.logPageView();
  };

  (function(d, s, id){
     var js, fjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement(s); js.id = id;
     js.src = "//connect.facebook.net/en_US/sdk.js";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'facebook-jssdk'));
</script>
);

Event Logging Methods

App events are logged with the logEvent and logPurchase methods.

Calling an SDK method with incorrect parameters will throw an exception. Make sure your code catches these exceptions.

logEvent Method

The logEvent method is used to log general events, the details of which are provided as parameters to the method.

logEvent: function(
  eventName, /* string, required */
  valueToSum, /* float, optional */
  parameters, /* object, optional */
)

The list of events and related parameters is described in the Events section later in this topic.

The following example demonstrates how to log a predefined 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
);

In addition to the predefined events, you can also create custom events by specifying their name as a string.

FB.AppEvents.logEvent('battledAnOrc');

The maximum length for a custom event name is 40 characters and it can only use characters that are letters, numbers, underscores, or dashes.

You can have a maximum of 1,000 different event names. Note: No new event types will be logged if you reach this maximum level. If you exceed this limit, you'll see an 100 Invalid parameter error when trying to log new event types. However, you can deactivate any existing events that you may not be using. Learn more about event limits.

logPurchase Method

The logPurchase method is a dedicated method used for logging purchases.

logPurchase: function(
  purchaseAmount, /* float */
  currency, /* string, http://en.wikipedia.org/wiki/ISO_4217 */
  parameters, /* object, optional */
)

This method requires that you specify a currency code defined by the ISO 4217 specification.

logPurchase Example

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

Events

Each of the predefined events can be logged with a valueToSum value and a list of as many as 25 parameters. Include the events that make sense based on the user actions in your app.

You can use the following app event builder to create code for both custom events and predefined events.

Do not use event as the name of a parameter. Custom parameters with the name event will not be logged. Use another name or add a prefix or suffix to the name, such as my_custom_event.

Event Names

The predefined event names are members of the FB.AppEvents.EventNames class.

Event NameTypical valueToSum ValueTypical parameters Value(s)

ACHIEVED_LEVEL

(none)

LEVEL

ADDED_PAYMENT_INFO

(none)

SUCCESS

ADDED_TO_CART

Price of item added

CONTENT_TYPE, CONTENT_ID, and CURRENCY

ADDED_TO_WISHLIST

Price of item added

CONTENT_TYPE, CONTENT_ID, and CURRENCY

COMPLETED_REGISTRATION

(none)

REGISTRATION_METHOD

COMPLETED_TUTORIAL

(none)

SUCCESS and CONTENT_ID

INITIATED_CHECKOUT

Total price of items in cart

CONTENT_TYPE, CONTENT_ID, NUM_ITEMS, PAYMENT_INFO_AVAILABLE, and CURRENCY

RATED

Rating given

CONTENT_TYPE, CONTENT_ID, and MAX_RATING_VALUE

SEARCHED

(none)

CONTENT_ID, SEARCH_STRING, and SUCCESS

SPENT_CREDITS

Total value of credits spent

CONTENT_TYPE, and CONTENT_ID

UNLOCKED_ACHIEVEMENT

(none)

DESCRIPTION

VIEWED_CONTENT

Price of item viewed, if applicable

CONTENT_TYPE, CONTENT_ID, and CURRENCY

Event Parameters

To get the most out of Facebook Analytics, we recommend logging more events and adding parameters to them. Standard parameters are described in the table below, but you're free to create your own parameter types.

The predefined parameter name constants described below are members of the FB.AppEvents.ParameterNames class.

Constant NameDatatype or ValueDescription

CONTENT_ID

string

International Article Number (EAN) when applicable, or other product or content identifier

CONTENT_TYPE

string

Description of the content type, such as a "music," "video," or a product description

CURRENCY

string

The currency code as defined by the ISO 4217 specification

DESCRIPTION

string

A string description

LEVEL

string

The player's level

MAX_RATING_VALUE

int

The upper bounds of a rating scale

NUM_ITEMS

int

The number of items

PAYMENT_INTO_AVAILABLE

1 or 0

1 for yes, or 0 for no

REGISTRATION_METHOD

string

The method used for registration, such as "Facebook," "Email," or "Twitter"

SEARCH_STRING

string

The user-specified search string

SUCCESS

1 or 0

1 for yes, or 0 for no

Access your App Events Report

To access your app event report:

  1. Go to Facebook Analytics: https://www.facebook.com/analytics.
  2. Select your website.
  3. Go to the Events Debugging section.

Debugging

To improve performance, the JavaScript SDK is minified when it's loaded. You can also load a debug version of the JavaScript SDK that's not minified and that includes more logging and stricter argument checking. To do this, change the js.src value in your loading code to match this:

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