# Analytics Kotlin Facebook App Events Plugin

## Getting started

1. From the Segment web app, click **Catalog**.
2. Search for *Facebook App Events* in the **Catalog**, select it, and choose which of your sources to connect the destination to.
3. In the destination settings, enter your Facebook App ID, which can be retrieved from your [Facebook Apps dashboard](https://developers.facebook.com/apps/).
4. Add the plugin to your project.

## Adding the dependency

> \[!WARNING]
>
> The Facebook App Events library will be installed as an additional dependency.

To install the Segment-Facebook App Events integration, add the following line to your gradle file:

```text
implementation 'com.segment.analytics.kotlin.destinations:facebookappevents:<latest_version>'
```

Or the following for Kotlin DSL:

```text
implementation('com.segment.analytics.kotlin.destinations:facebookappevents:<latest_version>')
```

## Using the plugin in your app

Open the file where you set up and configure the Analytics-Kotlin library. Add this plugin to the list of imports.

```text
import com.segment.analytics.kotlin.destinations.facebookappevents
```

In your Analytics-Kotlin library setup, call `analytics.add(plugin = ...)` to add an instance of the plugin to the Analytics timeline.

```text
    analytics = Analytics("<YOUR WRITE KEY>", applicationContext) {
        this.flushAt = 3
        this.trackApplicationLifecycleEvents = true
    }
    analytics.add(plugin = FacebookAppEvents()
```

Your events will now begin to flow to Facebook in device-mode.

## Screen

If you're not familiar with the Segment Specs, take a look to understand what the [Screen method](/docs/segment/connections/spec/screen/) does. An example call would look like:

```java
analytics.screen("ScreenName", buildJsonObject {
    put("productSlug", "example-product-123")
});
```

This integration also supports using Segment Screen events as Track events. For example, if you had a Screen event named `Confirmation` you could map the invocation of this to a Facebook app event as you would with Segment Track events.

To use this functionality you must opt into it using the integration setting named **Use Screen Events as Track Events**. Once enabled, you should start seeing Screen events populate in Facebook App Events. The screen name you provide will be wrapped with the words **Viewed** and **Screen**. So, if you have a Screen event with the name property set to `Welcome`, it will show up in Facebook as an event called **Viewed Welcome Screen**.

## Track

If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/segment/connections/spec/track/) does. An example call would look like:

```java
analytics.track("View Product", buildJsonObject {
    put("productId", 123)
    put("productName" "Striped trousers")
});
```

When you call Track Segment sends that event and it's properties to Facebook. In the Facebook analytics interface, you'll be able to use the event properties to segment your data.

Segment truncates events that are longer than 40 characters long due to Facebook's API constraints.

### Facebook parameters

Segment translates the [spec-matching properties](/docs/segment/connections/spec/track/#properties) `revenue` and `currency` to the appropriate Facebook parameters (`valueToSum` and `FBSDKAppEventParameterNameCurrency`), and also send events with revenue to Facebook's purchase logging method (`logPurchase`).

If you don't provide a `currency` explicitly, Segment sends `USD`. If any properties don't match the below, Segment passes them as they were sent.

| **Revenue**  | \_valueToSum  |
| ------------ | ------------- |
| **Currency** | `fb_currency` |

## Limited data use

In July 2020, Facebook released [Limited Data Use feature](https://developers.facebook.com/docs/marketing-apis/data-processing-options) to help businesses comply with the California Consumer Privacy Act (CCPA). This feature limits the way user data is stored and processed for all California residents who opt out of the sale of their data. You can send Limited Data Use data processing parameters to Facebook on each event so that Facebook can appropriately apply the user's data choice. Segment recommends that you first familiarize yourself on this feature and the [Data Processing Options Facebook accepts](https://developers.facebook.com/docs/marketing-apis/data-processing-options).

This destination supports the following parameters:

* **Data Processing Options**
* **Data Processing Options Country**
* **Data Processing Options State**

You can enable the feature using the **Use Limited Data Use** destination setting and control it using Data Processing Initialization Parameters.

> \[!NOTE]
>
> The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations.

### Data Processing Destination Setting

You can change the **Use Limited Data Use** destination setting to enable or disable Limited Data Use. This must be enabled (set to "on") if you want to send data processing parameters as part of the the Limited Data Use feature.

### Data Processing Initialization Parameters

The Data Processing parameters you set are the Data Processing Options Segment uses when sending data to Facebook. By default, Segment uses the following Data Processing Parameters:

| **Data Processing Parameter**       | **Default Value** | **What it means**                               |
| ----------------------------------- | ----------------- | ----------------------------------------------- |
| **Data Processing Options**         | `["LDU"]`         | Use Facebook's Limited Data Use processing      |
| **Data Processing Options Country** | `0`               | Use Facebook's geolocation to determine country |
| **Data Processing Options State**   | `0`               | Use Facebook's geolocation to determine state   |

Facebook uses the `context.ip` to determine the geolocation of the event.

You can manually change the Data Processing parameters by adding settings to the `integrations` object.

## Troubleshooting

### Not seeing events?

Facebook requires that payloads include the following:

* `context.device.id`
* `context.device.type`
* `context.os.version`

> \[!NOTE]
>
> The value of `context.device.type` must be either `ios` or `android`.

For example:

```json
{
  "anonymousId": "507f191e810c19729de860ea",
  "event": "Event Name",
​  "context": {
    "device": {
      "id": "B5372DB0-C21E-11E4-8DFC-AA07A5B093DB",
      "type": "ios"
    },
    "os": {
      "version": "8.1.3"
    }
  },​
  "messageId": "bbac-11e4-8dfc-aa07a53436b09b45567i8245237824",
  "type": "track",
  "userId": "97980cfea0067"
}
```

### Missing custom events

Facebook will only accept custom events with alphanumeric names (you can include spaces, "-" and "\_") that are between 2 and 40 characters in length. Otherwise, Facebook will reject the event payload with a 400 status.