Getting Started with App Events for Web

App Events is a feature of the Facebook SDK for Android that allows you to target, measure, and optimize the delivery of your ads to people most likely to take action. This guide shows you how to add app events from your new or existing app by integrating the Facebook SDK and then adding events to your app.

Requirements

You'll need the following before you can add app events to your app:

1. Select an App or Create a New App for Your Website

Please select an app or create a new one.

Set Your App Advertising Details

After you create an app, go to your App Dashboard. Select the app you wish to view. In the left side navigation panel of the App Dashboard, click Settings > Basic to view the App Details Panel with your App ID, your App Secret, and other details about your app. To set up your app for advertising set the following details:

  • Platform - Scroll to the bottom of the Settings page to add the Website Platform.
  • Privacy Policy URL - You must provide a Privacy Policy URL. Must be provided to take your app public.
  • Terms of Service URL - You must provide a Terms of Service URL.
See the App Development docs to add more details to your app.

To run ads and measure installs in the Ads Manager, you need to associate at least one Ad Account with your App.

  1. In the App Dashboard click Settings > Advanced.
  2. In Authorized Add Account IDs, add your Ad Account IDs. You can get your ad account IDs from your Ads Manager.

3. Integrate the Facebook SDK in Your Website

Add the SDK by Using the Quickstart

By using the Quickstart Guide from your App Dashboard to add the Facebook SDK to your Website, the code provided will already include your App ID.

Add the SDK Manually

To add the SDK manually copy and paste the following code but be sure to replace 'your-app-id' with your App ID.

<script>
  window.fbAsyncInit = function() {
    FB.init({
      appId      : 'your-app-id',
      xfbml      : true,
      version    : 'v2.8'
    });
    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 = "https://connect.facebook.net/en_US/sdk.js";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'facebook-jssdk'));
</script>

4. Add App Events

There are three types of App Events: Automatically Logged Events, Pre-defined Events, popular events that Facebook has created for you, and Custom Events, events you create that are specific to your app. For websites, we recommend triggering the page view event on all pages to ensure accurate user accounts and session durations.

Automatically Logged Events

After you integrate the Facebook SDK into your app, these events are automatically logged.

EventDetails

App Install

The first time a new user activates an app or the first time an app starts on a particular device.

App Launch

When the Facebook SDK is initialized in your app for each session.

In-App Purchase

When a purchase processed by the Apple App Store or Google Play has been completed. If you use other payments platforms, you will need to add purchase event code manually.

Because these events are already in the Facebook SDK there is no need to add these events to your code.

Pre-defined Events

You can add pre-defined events, see the Event Names and Event Parameters below, to your app. Use the Code Generator to get the code for these events.

To Generate Code for a Pre-defined Event

  1. Choose the Pre-Defined Event tab.
  2. In Event Name, choose a pre-defined event.
  3. Choose Get Code.
  4. In the window, select a language to see the code to copy and paste into your app.

Event Names

AppEventsConstants Value valueToSum Parameters

Achieved Level:

EVENT_NAME_ACHIEVED_LEVEL

LEVEL

App Launched:

EVENT_NAME_ACTIVATED_APP

Added Payment Info:

EVENT_NAME_ADDED_PAYMENT_INFO

SUCCESS

Added to Cart:

EVENT_NAME_ADDED_TO_CART

Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Added to Wishlist:

EVENT_NAME_ADDED_TO_WISHLIST

Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Completed Registration:

EVENT_NAME_COMPLETED_REGISTRATION

REGISTRATION_METHOD

Completed Tutorial:

EVENT_NAME_COMPLETED_TUTORIAL

SUCCESS, and CONTENT_ID or CONTENT

Initiated Checkout:

EVENT_NAME_INITIATED_CHECKOUT

Total price of items in cart

CONTENT_TYPE, CONTENT_ID or CONTENT,NUM_ITEMS, PAYMENT_INFO_AVAILABLE, and CURRENCY

Purchased:

EVENT_NAME_PURCHASED

purchase price

NUM_ITEMS, CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Rated:

EVENT_NAME_RATED

Rating given

CONTENT_TYPE , CONTENT_ID or CONTENT, and MAX_RATING_VALUE

Searched:

EVENT_NAME_SEARCHED

CONTENT_TYPE, SEARCH_STRING and SUCCESS

Spent Credits:

EVENT_NAME_SPENT_CREDITS

Total value of credits spent

CONTENT_TYPE, and CONTENT_ID or CONTENT

Unlocked Achievement:

EVENT_NAME_UNLOCKED_ACHIEVEMENT

DESCRIPTION

Viewed Content:

EVENT_NAME_VIEWED_CONTENT

Price of item viewed (if applicable)

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Event Parameters

The table below are typically useful parameters for inclusion with the events shown above or with your own custom events. Future enhancements to our insights product will use the recommended parameters, but note that you can provide your own parameters as well.

These pre-defined parameters are intended to provide guidance on typically useful logging patterns, and may have a more readable form in reporting and other UI. Your app should log the set of parameters that it's interested in seeing breakdowns on in insights. The recommended description for these are guidance only - you can use these parameters for whatever makes sense for your app.

If you need to remove obsolete parameters - you can deactivate parameters by following the instructions in our help center.

The parameters are passed via a Bundle where the key holds the parameter name and the value either a String or an int, as shown below. If you provide another type of value that is not compliant such as a boolean, the SDK logs a warning to LogginBehavior.APP_EVENT.

AppEventConstants::EVENT_PARAM_* Possible Values Description

Content ID:

EVENT_PARAM_CONTENT_ID

string

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

Content:

EVENT_PARAM_CONTENT

string

A list of JSON object that contains the International Article Number (EAN) when applicable, or other product or content identifier(s) as well as additional information about the products. id, quantity, and item_price are the available fields. e.g. "[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]"

Content Type:

EVENT_PARAM_CONTENT_TYPE

string

'product' or 'product_group'

Currency:

EVENT_PARAM_CURRENCY

string

ISO 4217 code, e.g., "EUR", "USD", "JPY"

Description:

EVENT_PARAM_DESCRIPTION

string

A string description

Level:

EVENT_PARAM_LEVEL

string

Level of a game

Max. Rating Value:

EVENT_PARAM_MAX_RATING_VALUE

int

Upper bounds of a rating scale, for example 5 on a 5 star scale

Number of Items:

EVENT_PARAM_NUM_ITEMS

int

Number of items

Payment Info Available:

EVENT_PARAM_PAYMENT_INFO_AVAILABLE

1 or 0

1 for yes, 0 for no

Registration Method:

EVENT_PARAM_REGISTRATION_METHOD

string

Facebook, Email, Twitter, etc.

Search String:

EVENT_PARAM_SEARCH_STRING

string

The text string that was searched for

Success:

EVENT_PARAM_SUCCESS

1 or 0

1 for yes, 0 for no

Custom App Events

Facebook Analytics supports up to 1,000 unique events for your app or website, so you can also create your own custom events. Use the Code Generator to generate code for these 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.

To Generate Code for a Pre-defined Event

  1. Choose the Custom Event tab.
  2. In Event Name, choose a pre-defined event.
  3. Choose Get Code.
  4. In the window, select a language to see the code to copy and paste into your app.

To log a custom event, just pass the name of the event as a string:

function onButtonClick() {
  // Add this to a button's onclick handler
  FB.AppEvents.logEvent("my_app_event");
}

5. Test Your Events

In Facebook Analytics Dashboard

You can review the most recent events logged by your app or website. To verify these events, visit Facebook Analytics. Then choose your app and go to Activity > Event Debugging.

You should see your app launch (if you're setting up an app) or the page view event (if you're setting up a website) as well as the custom event for the button click. If not, click the refresh button to load the latest events.

Once you've verified that your events are being logged correctly, then you can create your first funnel to help you measure conversion for any sequence of events you choose.

In the App Ads Helper Tool

The App Ads Helper allows you to test the app events in your app to ensure that your app is sending events to Facebook.

a. Open the App Ads Helper.

b. In Select an App, choose your app and choose Submit.

c. Go to the bottom and choose Test App Events.

d. Start your app and send an event. The event appears on the web page.

More Resources

For more information and helpful hints on App Events check out: