Getting Started with App Events for Unity

App Events is a feature of the Facebook SDK for Unity that allows you to track actions within your app or website. Tracking these actions, or events, 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 to your new or existing app by integrating the Facebook SDK then logging these events.

There are three types of App Events:

  • Automatically Logged Events - Beginning with the v4.27, the Facebook Unity SDK automatically logs app installs, app sessions, and in-app purchases. To disable automatic logging, see below.

  • Standard Events - Popular events that Facebook has created for you.

  • Custom Events - Events you create that are specific to your app.

Requirements

If you have not already implemented the Facebook Unity SDK please see our Getting Started guide.

Logging app activations

Logging app activations as an App Event enables almost all other functionality and should be the first thing you add to your app. The SDK provides a helper method to log app activation. By logging an activation event, you can observe how frequently users activate your app, how much time they spend using it, and other demographic information through Facebook Analytics.

You should be calling FB.ActivateApp both on launch and each application resume to ensure you are correctly measuring sessions.

The SDK needs to be initalized first with FB.Init before you can call FB.ActivateApp.

Consider utilizing Unity's Awake function from MonoBehavior to cover App Launches.

void Awake ()
{
  if (FB.IsInitialized) {
    FB.ActivateApp();
  } else {
    //Handle FB.Init
    FB.Init( () => {
      FB.ActivateApp();
    });
  }
}

Consider utilizing Unity's OnApplicationPause function from MonoBehavior to cover App Resumes.

// Unity will call OnApplicationPause(false) when an app is resumed
// from the background
void OnApplicationPause (bool pauseStatus)
{
  // Check the pauseStatus to see if we are in the foreground
  // or background
  if (!pauseStatus) {
    //app resume
    if (FB.IsInitialized) {
      FB.ActivateApp();
    } else {
      //Handle FB.Init
      FB.Init( () => {
        FB.ActivateApp();
      });
    }
  }
}

The FB.ActivateApp method is the preferred way to log app activations, even though there's an event that you can send manually via the SDK. The helper method performs a few other tasks that are necessary for proper accounting for Mobile App Install Ads.

Events

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


Example 1: Log that a user has bought something

In this example priceCurrency is a string containing the 3-letter ISO code for the currency that the user spent, and priceAmount is a float containing the quantity spent. packageName is a string containing your SKU code for the thing they bought.

var iapParameters = new Dictionary<string, object>();
iapParameters["mygame_packagename"] = packageName;
FB.LogPurchase(
  priceAmount,
  priceCurrency,
  iapParameters
);

Example 2: Track the amount of credits spent

In the second example we keep track of how many credits a person spent. numGold is the number of in-app currency the user spent in this purchase, storeItem is a string naming the item the user bought.

var softPurchaseParameters = new Dictionary<string, object>();
softPurchaseParameters["mygame_purchased_item"] = storeItem;
FB.LogAppEvent(
  Facebook.Unity.AppEventName.SpentCredits,
  (float)numGold,
  softPurchaseParameters
);

The maximum number of different event names is 1,000. Note: No new event types will be logged once this cap is hit and if you exceed this limit you may see an 100 Invalid parameter error when logging. However it is possible to deactivate obsolete events. Read more about event limits in the FAQ.

Disable Automatically Logged Events

Our Unity SDK enables automatically logged events by default. To disable or enable automatic event logging, go to Facebook -> Edit Settings in the Unity IDE menu bar and select or unselect Auto Logging App Events under the App Events Settings section.

You can programmatically disable automatically logged events by setting the SetAutoLogAppEventsEnabled() method of Fb.Mobile to false.

FB.Mobile.SetAutoLogAppEventsEnabled(false); 

In some cases, you may wish to re-enable auto-logging after an end-user provides consent. You can do this by setting the SetAutoLogAppEventsEnabled() method to true.

FB.Mobile.SetAutoLogAppEventsEnabled(true); 

Disable Collection of Advertiser IDs

Our Unity SDK enables collection of Advertiser IDs by default. To disable or enable Advertiser ID collection, go to Facebook -> Edit Settings in Unity IDE menu bar and select or unselect AdvertiserID Collection under the App Events Settings section.

You can programmatically disable Advertiser ID collection by setting the SetAdvertiserIDCollectionEnabled () method of Fb.Mobile to false.

FB.Mobile.SetAdvertiserIDCollectionEnabled (false);

In some cases, you may wish to re-enable Advertiser ID collection after an end-user provides consent. You can do this by setting the SetAdvertiserIDCollectionEnabled() method to true.

FB.Mobile.SetAdvertiserIDCollectionEnabled (true);