App Events Best Practices for E-Commerce/Retail App

This guide is intended to be used as a starting point for your app and should be customized for your app's needs. The example app provides a screen by screen breakdown of the different events and parameters that can be collected. At the end of it, there is a table that lists the recommended events and parameters for your app.

E-Commerce/Retail App Objectives

  • Understand conversion flow through app
  • Retarget users that have abandoned their cart
  • Find new users through lookalikes of high value users

ActivatedApp Event

ActivatedApp Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
- (void)applicationDidBecomeActive:(UIApplication *)application {    
    [FBSDKAppEvents activateApp];    
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
@Override
public void onCreate() {
    super.onCreate();
    FacebookSdk.sdkInitialize(getApplicationContext());
    AppEventsLogger.activateApp(this);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
void Awake ()
{
	if (FB.IsInitialized) {
		FB.ActivateApp();
	} else {
		//Handle FB.Init
		FB.Init( () => {
			FB.ActivateApp();
		});
	}
}

Searched Event

Searched Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logSearchedEvent :(NSString*)contentType
    searchString :(NSString*)searchString
    success :(BOOL)success {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            contentType, FBSDKAppEventParameterNameContentType,
            searchString, FBSDKAppEventParameterNameSearchString,
            [NSNumber numberWithInt:success ? 1 : 0], FBSDKAppEventParameterNameSuccess,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameSearched
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logSearchedEvent (String contentType, String searchString, boolean success) {
    Bundle params = new Bundle();
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putString(AppEventsConstants.EVENT_PARAM_SEARCH_STRING, searchString);
    params.putInt(AppEventsConstants.EVENT_PARAM_SUCCESS, success ? 1 : 0);
    logger.logEvent(AppEventsConstants.EVENT_NAME_SEARCHED, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogSearchedEvent (string contentType, string searchString, bool success) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.SearchString] = searchString;
    parameters[AppEventParameterName.Success] = success ? 1 : 0;
    FB.LogAppEvent(
        AppEventName.Searched,
        parameters
    );
}

ViewedContent Event

ViewedContent Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logViewedContentEvent :(NSString*)contentType
    contentId :(NSString*)contentId
    currency :(NSString*)currency
    valToSum :(double)price {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            contentType, FBSDKAppEventParameterNameContentType,
            contentId, FBSDKAppEventParameterNameContentID,
            currency, FBSDKAppEventParameterNameCurrency,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameViewedContent
        valueToSum: price
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logViewedContentEvent (String contentType, String contentId, String currency, double price) {
    Bundle params = new Bundle();
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, contentId);
    params.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, currency);
    logger.logEvent(AppEventsConstants.EVENT_NAME_VIEWED_CONTENT, price, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogViewedContentEvent (string contentType, string contentId, string currency, double price) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.ContentID] = contentId;
    parameters[AppEventParameterName.Currency] = currency;
    FB.LogAppEvent(
        AppEventName.ViewedContent,
        (float)price,
        parameters
    );
}

AddedToWishList Event

AddedToWishList Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logAddedToWishlistEvent :(NSString*)contentId
    contentType :(NSString*)contentType
    currency :(NSString*)currency
    valToSum :(double)price {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            contentId, FBSDKAppEventParameterNameContentID,
            contentType, FBSDKAppEventParameterNameContentType,
            currency, FBSDKAppEventParameterNameCurrency,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameAddedToWishlist
        valueToSum: price
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logAddedToWishlistEvent (String contentId, String contentType, String currency, double price) {
    Bundle params = new Bundle();
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, contentId);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, currency);
    logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_TO_WISHLIST, price, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogAddedToWishlistEvent (string contentId, string contentType, string currency, double price) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.ContentID] = contentId;
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.Currency] = currency;
    FB.LogAppEvent(
        AppEventName.AddedToWishlist,
        (float)price,
        parameters
    );
}

AddedToCart Event

AddedToCart Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logAddedToCartEvent :(NSString*)contentId
    contentType :(NSString*)contentType
    currency :(NSString*)currency
    valToSum :(double)price {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            contentId, FBSDKAppEventParameterNameContentID,
            contentType, FBSDKAppEventParameterNameContentType,
            currency, FBSDKAppEventParameterNameCurrency,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameAddedToCart
        valueToSum: price
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logAddedToCartEvent (String contentId, String contentType, String currency, double price) {
    Bundle params = new Bundle();
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, contentId);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, currency);
    logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_TO_CART, price, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogAddedToCartEvent (string contentId, string contentType, string currency, double price) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.ContentID] = contentId;
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.Currency] = currency;
    FB.LogAppEvent(
        AppEventName.AddedToCart,
        (float)price,
        parameters
    );
}

AddedPaymentInfo Event

AddedPaymentInfo Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logAddedPaymentInfoEvent :(BOOL)success {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            [NSNumber numberWithInt:success ? 1 : 0], FBSDKAppEventParameterNameSuccess,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameAddedPaymentInfo
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logAddedPaymentInfoEvent (boolean success) {
    Bundle params = new Bundle();
    params.putInt(AppEventsConstants.EVENT_PARAM_SUCCESS, success ? 1 : 0);
    logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_PAYMENT_INFO, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogAddedPaymentInfoEvent (bool success) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.Success] = success ? 1 : 0;
    FB.LogAppEvent(
        AppEventName.AddedPaymentInfo,
        parameters
    );
}

InitiatedCheckout Event

InitiatedCheckout Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logInitiatedCheckoutEvent :(NSString*)contentId
    contentType :(NSString*)contentType
    numItems :(int)numItems
    paymentInfoAvailable :(BOOL)paymentInfoAvailable
    currency :(NSString*)currency
    valToSum :(double)totalPrice {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            contentId, FBSDKAppEventParameterNameContentID,
            contentType, FBSDKAppEventParameterNameContentType,
            [NSNumber numberWithInt:numItems], FBSDKAppEventParameterNameNumItems,
            [NSNumber numberWithInt:paymentInfoAvailable ? 1 : 0], FBSDKAppEventParameterNamePaymentInfoAvailable,
            currency, FBSDKAppEventParameterNameCurrency,
            nil];

    [FBSDKAppEvents logEvent: FBSDKAppEventNameInitiatedCheckout
        valueToSum: totalPrice
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logInitiatedCheckoutEvent (String contentId, String contentType, int numItems, boolean paymentInfoAvailable, String currency, double totalPrice) {
    Bundle params = new Bundle();
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, contentId);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putInt(AppEventsConstants.EVENT_PARAM_NUM_ITEMS, numItems);
    params.putInt(AppEventsConstants.EVENT_PARAM_PAYMENT_INFO_AVAILABLE, paymentInfoAvailable ? 1 : 0);
    params.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, currency);
    logger.logEvent(AppEventsConstants.EVENT_NAME_INITIATED_CHECKOUT, totalPrice, params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogInitiatedCheckoutEvent (string contentId, string contentType, int numItems, bool paymentInfoAvailable, string currency, double totalPrice) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.ContentID] = contentId;
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.NumItems] = numItems;
    parameters[AppEventParameterName.PaymentInfoAvailable] = paymentInfoAvailable ? 1 : 0;
    parameters[AppEventParameterName.Currency] = currency;
    FB.LogAppEvent(
        AppEventName.InitiatedCheckout,
        (float)totalPrice,
        parameters
    );
}

Purchased Event

Purchased Event Code Example:

/**
 * For more details, please take a look at:
 * developers.facebook.com/docs/reference/ios/current/class/FBSDKAppEvents
 */
 - (void)logPurchasedEvent :(int)numItems
    contentType :(NSString*)contentType
    contentId :(NSString*)contentId
    currency :(NSString*)currency
    valToSum :(double)price {

    NSDictionary *params = 
        [[NSDictionary alloc] initWithObjectsAndKeys:
            [NSNumber numberWithInt:numItems], FBSDKAppEventParameterNameNumItems,
            contentType, FBSDKAppEventParameterNameContentType,
            contentId, FBSDKAppEventParameterNameContentID,
            currency, FBSDKAppEventParameterNameCurrency,
            nil];

    [FBSDKAppEvents logPurchase:price 
          currency: currency
        parameters: params];
}
/**
 * This function assumes logger is an instance of AppEventsLogger and has been
 * created using AppEventsLogger.newLogger() call.
 */
public void logPurchasedEvent (int numItems, String contentType, String contentId, String currency, double price) {
    Bundle params = new Bundle();
    params.putInt(AppEventsConstants.EVENT_PARAM_NUM_ITEMS, numItems);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, contentType);
    params.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, contentId);
    params.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, currency);
    logger.logPurchase(price, Currency.getInstance(currency),params);
}
/**
 * Include the Facebook namespace via the following code:
 * using Facebook.Unity;
 *
 * For more details, please take a look at:
 * developers.facebook.com/docs/unity/reference/current/FB.LogAppEvent
 */
public void LogPurchasedEvent (int numItems, string contentType, string contentId, string currency, double price) {
    var parameters = new Dictionary<string, object>();
    parameters[AppEventParameterName.NumItems] = numItems;
    parameters[AppEventParameterName.ContentType] = contentType;
    parameters[AppEventParameterName.ContentID] = contentId;
    parameters[AppEventParameterName.Currency] = currency;
    FB.LogPurchase(
	    (float)price,
	    currency,
	    parameters
    );
}

E-Commerce/Retail Recommended Events and Parameters

Event Name Predefined Suggested Parameters

App Install

Yes

Launched App

Yes

Searched

Yes

SearchString

Viewed Content

Yes

ContentID, Content Type, Description, Currency, valueToSum

Added to Wishlist

Yes

ContentID, Content Type, Description, Currency, valueToSum

Added to Cart

Yes

Contents, ContentID, Content Type, Description, Currency, valueToSum

Initiated Checkout

Yes

ContentID, Content Type, Description, Currency, valueToSum

Added Payment Info

Yes

Purchased

Yes

Contents, ContentID, Content Type, Description, Currency, valueToSum, Number of Items