Getting Started with App Events for Web

App Events is a feature of the Facebook SDK for Web 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

Get your Facebook App ID 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();
  };
</script>

<script async defer 
  src="https://connect.facebook.net/en_US/sdk.js"></script>
</script>

4. Add App Events

There are three types of App Events: Automatically Logged Events, Standard 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.

Standard Events

You can add standard 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 Standard Event

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

Standard Event Names

Event Name: AppEventsConstants Value Parameters Description

Achieve Level: EVENT_NAME_ACHIEVED_LEVEL

LEVEL

The achievement of specific levels you define within your application, business or organization.

Activate App: EVENT_NAME_ACTIVATED_APP

The launch of your app.

In-App Ad Click: EVENT_NAME_AD_CLICK

AD_TYPE

An ad from a third-party platform is clicked within your app.

In-App Ad Impression: EVENT_NAME_AD_IMPRESSION

AD_TYPE

An ad from a third-party platform appears on-screen within your app.

Add Payment Info: EVENT_NAME_ADDED_PAYMENT_INFO

SUCCESS

The addition of customer payment information during a checkout process.

Add to Cart: EVENT_NAME_ADDED_TO_CART

valueToSum: Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

The addition of an item to a shopping cart or basket. For example, clicking an Add to Cart button on a website.

Add to Wishlist: EVENT_NAME_ADDED_TO_WISHLIST

valueToSum: Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

The addition of items to a wishlist. For example, clicking an Add to Wishlist button on a website.

Complete Registration: EVENT_NAME_COMPLETED_REGISTRATION

REGISTRATION_METHOD

A submission of information by a customer in exchange for a service provided by your business. For example, sign up for an email subscription.

Complete Tutorial: EVENT_NAME_COMPLETED_TUTORIAL

SUCCESS, and CONTENT_ID or CONTENT

A completion of a tutorial on your app.

Contact: EVENT_NAME_CONTACT

A telephone or SMS, email, chat or other type of contact between a customer and your business.

Customize Product: EVENT_NAME_CUSTOMIZE_PRODUCT

The customization of products through a configuration tool or other application your business owns.

Donate: EVENT_NAME_DONATE

The donation of funds to your organization or cause.

Find Location: EVENT_NAME_FIND_LOCATION

When a person finds one of your locations via web or app, with an intention to visit. For example, searching for a product and finding it at one of your local stores.

Initiate Checkout: EVENT_NAME_INITIATED_CHECKOUT

valueToSum: Total price of items in cart

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

The start of a checkout process.

Purchase: EVENT_NAME_PURCHASED

valueToSum: Price of Purchase

NUM_ITEMS, CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

The completion of a purchase, usually signified by receiving order or purchase confirmation or a transaction receipt.

Rate: EVENT_NAME_RATED

valueToSum: Rating given

CONTENT_TYPE , CONTENT_ID or CONTENT, and MAX_RATING_VALUE

A rating of something within your app, business or organization. For example, rates a restaurant within a restaurant review app.

Schedule: EVENT_NAME_SCHEDULE

The booking of an appointment to visit one of your locations.

Search: EVENT_NAME_SEARCHED

CONTENT_TYPE, SEARCH_STRING and SUCCESS

A search performed on your website, app or other property, such as product searches, travel searches, etc.

Spent Credits: EVENT_NAME_SPENT_CREDITS

valueToSum: Total value of credits spent

CONTENT_TYPE, and CONTENT_ID or CONTENT

The completion of a transaction where people spend credits specific to your business or application, such as in-app currency.

Start Trial: EVENT_NAME_START_TRIAL

valueToSum: Price of Subscription

ORDER_ID and CURRENCY

The start of a free trial of a product or service you offer, such as a trial subscription.

Submit Application: EVENT_NAME_SUBMIT_APPLICATION

The submission of an application for a product, service or program you offer, such as a credit card, educational program or job.

Subscribe: EVENT_NAME_SUBSCRIBE

valueToSum: Price of Subscription

ORDER_ID and CURRENCY

The start of a paid subscription for a product or service you offer.

Unlock Achievement: EVENT_NAME_UNLOCKED_ACHIEVEMENT

DESCRIPTION

The completion of specific activities or actions you want to reward within your application, business or organization. For example, refer a friend, complete your profile, etc.

View Content: EVENT_NAME_VIEWED_CONTENT

Price of item viewed (if applicable)

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

A visit to a content page you care about, such as a product page, landing page or article. Information about the page viewed can be passed to Facebook for use in dynamic ads.

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

Ad Type:

EVENT_PARAM_AD_TYPE

string

Type of ad: banner, interstitial, rewarded_video, native

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 ID:

EVENT_PARAM_CONTENT_ID

string

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

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

Order ID:

EVENT_PARAM_ORDER_ID

string

The unique ID for all events within a subscription

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 Standard Event

  1. Choose the Custom Event tab.
  2. In Event Name, choose a standard 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 > Events Manager.

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: