Implement Facebook Analytics

Finally got round to going through the Facebook F8 conference videos and noticed a couple of great videos on Facebook Analytics.

F8 Video List Implementing and Understanding Facebook Analytics for Apps Build Better Experiences with Facebook Analytics for Apps

I've not as far as writing a hello-world application, nor checking the capabilities of the devkit addon (I'm in the middle of the second video), so I'll try to keep this "issue" active - it might be that you simply close it down as redundant!

My Observations

The current (native) devkit FB SDK is fine - App Events are available since 3.X
On Android, you need to "activate" and "deactivate" FB App Events on resume and pause (for session tracking)
On iOS, the app needs to "activate" FB App Events at startup
- I'm not sure why they don't "deactivate", my guess is that they handle that internally or that the feature may get added at a later date.
Once activated, iOS and Android only exposes 2 methods: logPurchase and logEvent
logEvent has a number of preset event names (you can also use a custom string)
- The preset names differ in reference, but am assuming they have the same string value, ie:
- JS: FB.AppEvents.EventNames.ACHIEVED_LEVEL
- iOS: FBSDKAppEventNameAchievedLevel
- Android: EVENT_NAME_ACHIEVED_LEVEL
- Further to this, each preset event has a number of preset parameters, (again you can also use custom values here), AND an optional "value to sum"
- Each platform has a different number of presets events, not sure why.
- JS: 12, iOS: 14, Android: 14.
- I'll diff them soon to see what this relates to.
- EDIT: On this video @ 25min it states 14 events...
- There are preset parameters too. JS, iOS and Android all have 11.
I can imagine a "GOTCHA" use-case, on the facebook platform there is an option to automatically capture purchase events (you just toggle the switch on the facebook app settings), if a devkit developer does this and ALSO manually tracks purchases in-app they will get double-reporting for iOS. Probably just worth noting in the documentation.

So I've combed through the differences between the 3 platforms and compiled them into the tables below.

I've focussed on the fact that Javascript has 12 events while iOS/Android has 14, the events that are missing from Javascript are ACTIVATED_APP and PURCHASED. At first this appears debilitating, however I think that it might be a legacy thing with iOS/Android. All three expose methods for:

activateApp
logEvent
logPurchase

With this in mind, the missing "events" (ACTIVATED_APP and PURCHASED) appear to be bundled up into the methods activateApp and logPurchase. I guess there might be use-cases where a developer might want to manually call these via logEvent but it's not documented and I can't think of any.

Events

Javascript                | iOS                                     | Android                            | valueToSum                            | Parameters
FB.AppEvents.EventNames.  |                                         | AppEventsConstants.                |                                       |
--------------------------|-----------------------------------------|------------------------------------|---------------------------------------|-----------------------------------------------------------------
ACHIEVED_LEVEL            | FBSDKAppEventNameAchievedLevel          | EVENT_NAME_ACHIEVED_LEVEL          |                                       | Level
                          | FBSDKAppEventNameActivatedApp           | EVENT_NAME_ACTIVATED_APP           |                                       |
ADDED_PAYMENT_INFO        | FBSDKAppEventNameAddedPaymentInfo       | EVENT_NAME_ADDED_PAYMENT_INFO      |                                       | Success
ADDED_TO_CART             | FBSDKAppEventNameAddedToCart            | EVENT_NAME_ADDED_TO_CART           | Price of item added                   | ContentType, ContentID, Currency
ADDED_TO_WISHLIST         | FBSDKAppEventNameAddedToWishlist        | EVENT_NAME_ADDED_TO_WISHLIST       | Price of item added                   | ContentType, ContentID, Currency
COMPLETED_REGISTRATION    | FBSDKAppEventNameCompletedRegistration  | EVENT_NAME_COMPLETED_REGISTRATION  |                                       | RegistrationMethod
COMPLETED_TUTORIAL        | FBSDKAppEventNameCompletedTutorial      | EVENT_NAME_COMPLETED_TUTORIAL      |                                       | Success, ContentID
INITIATED_CHECKOUT        | FBSDKAppEventNameInitiatedCheckout      | EVENT_NAME_INITIATED_CHECKOUT      | Total price of items in cart          | ContentType, ContentID, NumItems, PaymentInfoAvailable, Currency
                          | FBSDKAppEventNamePurchased              | EVENT_NAME_PURCHASED               | purchase price                        | NumItems, ContentType, ContentID, Currency
RATED                     | FBSDKAppEventNameRated                  | EVENT_NAME_RATED                   | Rating given                          | ContentType, ContentID, MaxRatingValue
SEARCHED                  | FBSDKAppEventNameSearched               | EVENT_NAME_SEARCHED                |                                       | ContentType, SearchString, Success
SPENT_CREDITS             | FBSDKAppEventNameSpentCredits           | EVENT_NAME_SPENT_CREDITS           | Total value of credits spent          | ContentType, ContentID
UNLOCKED_ACHIEVEMENT      | FBSDKAppEventNameUnlockedAchievement    | EVENT_NAME_UNLOCKED_ACHIEVEMENT    |                                       | Description
VIEWED_CONTENT            | FBSDKAppEventNameViewedContent          | EVENT_NAME_VIEWED_CONTENT          | Price of item viewed (if applicable)  | ContentType, ContentID, Currency

Parameters

Javascript                    | iOS                                             | Android                             | Possible Values  | Description
FB.AppEvents.ParameterNames.  |                                                 | AppEventsConstants.                 |                  |
------------------------------|-------------------------------------------------|-------------------------------------|------------------|-------------------------------------------------------------------------------------------
CONTENT_ID                    | FBSDKAppEventParameterNameContentID             | EVENT_PARAM_CONTENT_ID              | string           | International Article Number (EAN) when applicable, or other product or content identifier
CONTENT_TYPE                  | FBSDKAppEventParameterNameContentType           | EVENT_PARAM_CONTENT_TYPE            | string           | For example music, video, or product description
CURRENCY                      | FBSDKAppEventParameterNameCurrency              | EVENT_PARAM_CURRENCY                | string           | ISO 4217 code, e.g., "EUR", "USD", "JPY"
DESCRIPTION                   | FBSDKAppEventParameterNameDescription           | EVENT_PARAM_DESCRIPTION             | string           | A string description
LEVEL                         | FBSDKAppEventParameterNameLevel                 | EVENT_PARAM_LEVEL                   | string           | Player's Level (also described as "Level of a game", slightly confusing)
MAX_RATING_VALUE              | FBSDKAppEventParameterNameMaxRatingValue        | EVENT_PARAM_MAX_RATING_VALUE        | int              | Upper bounds of a rating scale, for example 5 on a 5 star scale
NUM_ITEMS                     | FBSDKAppEventParameterNameNumItems              | EVENT_PARAM_NUM_ITEMS               | int              | Number of items
PAYMENT_INFO_AVAILABLE        | FBSDKAppEventParameterNamePaymentInfoAvailable  | EVENT_PARAM_PAYMENT_INFO_AVAILABLE  | '1' or '0'       | 1 for yes, 0 for no
REGISTRATION_METHOD           | FBSDKAppEventParameterNameRegistrationMethod    | EVENT_PARAM_REGISTRATION_METHOD     | string           | Facebook, Email, Twitter, etc.
SEARCH_STRING                 | FBSDKAppEventParameterNameSearchString          | EVENT_PARAM_SEARCH_STRING           | string           | The text string that was searched for
SUCCESS                       | FBSDKAppEventParameterNameSuccess               | EVENT_PARAM_SUCCESS                 | '1' or '0'       | 1 for yes, 0 for no

Implementation Thoughts

I've realised that since games may be deployed to iOS, Android, web or Facebook canvas that there are two choices in how to "activateApp" (and "deactivateApp" in the case of Android):

1 - Assume all games using the plugin should have AppEvents active by default, therefore handle activateApp and deactivateApp within the native implementations. This would be my preferred approach.

2 - Assume the developer wants to manually implement AppEvents, thus activateApp and deactivateApp should originate from the game source code, like so:

if(FB.AppEvents){
    GC.app.engine.on('resume', function(){ FB.AppEvents.activateApp();   });
    GC.app.engine.on('pause', function(){  FB.AppEvents.deactivateApp(); });
    FB.AppEvents.activateApp();
}

Having had a bit of a look around, I favour #1, just turn it on for everyone, there's very little downside that I can see to having this active by default.

I've had no luck in accessing FB.AppEvents in the simulator, I'm unsure why, however it might be that it is only exposed to games that exist on Facebook Canvas.

play-co / devkit