# Analytics Swift Braze Plugin

[Braze](https://www.braze.com/), formerly Appboy, is an engagement platform that empowers growth by helping marketing teams to build customer loyalty through mobile, omni-channel customer experiences.

Braze's destination plugin code is open source and available on GitHub. You can view it on GitHub in the [@braze-inc/analytics-swift-braze](https://github.com/braze-inc/analytics-swift-braze) repo. This destination plugin is maintained by Braze. For any issues with the destination plugin code, please reach out to Braze's support.

## Getting started

1. From the Segment web app, click **Catalog**.
2. Search for "Braze" in the Catalog, select it, and choose which of your sources to connect to the destination.
3. In the Destination Settings, add the **API Key**, found in the Braze Dashboard in *App Settings > Manage App Group*.
4. Set up a new App Group REST API Key in the Braze Dashboard in *App Settings > Developer Console > API Settings*. For more information, see [Creating and Managing REST API Keys](https://www.braze.com/docs/api/basics/#creating-and-managing-rest-api-keys) in the Braze documentation.
   Select the `users.track` endpoint in the **User Data** section.

## Adding the dependency

### Xcode

In the Xcode `File` menu, click **Add Packages**. You'll see a dialog where you can search for Swift packages. In the search field, enter the URL to this repository.

```text
https://github.com/segment-integrations/analytics-swift-braze
```

You'll then have the option to pin to a version, or specific branch, as well as which project in your workspace to add it to. Once you've made your selections, click the **Add Package** button.

### Package.swift

Open your Package.swift file and add the following to the `dependencies` section:

```swift
.package(
            name: "Segment",
            url: "https://github.com/segment-integrations/analytics-swift-braze.git",
            from: "1.0.0"
        ),
```

## Using the plugin in your app

Open the file where you setup and configure the Analytics-Swift library. Add this plugin to the list of imports.

```swift
import Segment
import SegmentBraze // <-- Add this line
```

Just under your Analytics-Swift library setup, call `analytics.add(plugin: ...)` to add an instance of the plugin to the Analytics timeline.

```swift
let analytics = Analytics(configuration: Configuration(writeKey: "<YOUR WRITE KEY>")
                    .flushAt(3)
                    .trackApplicationLifecycleEvents(true))
analytics.add(plugin: BrazeDestination())
```

## Identify

> \[!NOTE]
>
> Add Segment's open-source [Middleware](https://github.com/segmentio/segment-braze-mobile-middleware) tool to optimize your integration. This tool limits [Data Point](https://www.braze.com/docs/user_guide/data_and_analytics/data_points/) use by debouncing duplicate Identify calls from Segment. For more information, see the project's [README](https://github.com/segmentio/segment-braze-mobile-middleware/blob/master/README.md#how-does-this-work).

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

```swift
struct MyTraits: Codable {
        let favoriteColor: String
}

analytics.identify(userId: "a user's id", MyTraits(favoriteColor: "fuscia"))
```

When you Identify a user, Segment passes that user's information to Braze and sets the `userId` as Braze's External User ID.

If you're using a device-mode connection, Braze's SDK assigns a `device_id` and a backend identifier, `braze_id`, to every user. This allows Braze to capture anonymous activity from the device by matching on those identifiers instead of `userId`.

### Capture the `braze_id` of anonymous users

Pass one of the many identifiers that may exist on an anonymous user profile to the [Braze's User by Identifier REST endpoint](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/) to capture and export the `braze_id`. These identifiers include:

* email address
* phone number
* device\_id

Choose an identifier that is available on the user profile at that point in the user lifecycle.

For example, if you pass device\_id to the User by Identifier endpoint:

```js
{
  "device_id": "{{device_id}}",
  "fields_to_export": ["braze_id"]
}
```

The endpoint returns:

```js
{
  "users": [
    {
        "braze_id": "{{braze_id}}"
    }
  ],
  "message": "success"
} 
```

> \[!NOTE]
>
> If you decide to use the `braze_id`, consider [contacting Segment Success Engineering](https://segment.com/help/contact/) or a Solutions Architect to verify your Braze implementation.

Segment's special traits recognized as Braze's standard user profile fields (in parentheses) are:

| Segment Event     | Braze Event  |
| ----------------- | ------------ |
| `firstName`       | `first_name` |
| `lastName`        | `last_name`  |
| `birthday`        | `dob`        |
| `avatar`          | `image_url`  |
| `address.city`    | `home_city`  |
| `address.country` | `country`    |
| `gender`          | `gender`     |

Segment sends all other traits (except Braze's [reserved user profile fields](https://www.braze.com/docs/api/objects_filters/user_attributes_object/#braze-user-profile-fields)) to Braze as custom attributes. You can send an array of strings as trait values but not nested objects.

## Track

> \[!NOTE]
>
> To lower [Data Point](https://www.braze.com/docs/user_guide/data_and_analytics/data_points/) use, limit the events you send to Braze to those that are relevant for campaigns and segmentation to the Braze destination. For more information, see [Schema Controls](/docs/segment/connections/sources/schema).

The Braze Swift destination plugin currently only supports sending `logPurchase` events, and custom events are not supported in device mode. Please review the [plugin code](https://github.com/braze-inc/analytics-swift-braze/blob/main/Sources/SegmentBraze/BrazeDestination.swift) for more information.

Braze supports currency codes as specified in [their Purchase Object Specification](https://www.braze.com/docs/api/objects_filters/purchase_object/). Be aware that any currency reported other than USD displays in [the Braze UI in USD based on the exchange rate on the date it was reported](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/analytics/logging_purchases/#logging-purchases).