# StackAdapt Events and Conversions Destination

Setting up [StackAdapt](https://www.stackadapt.com/) as a Segment destination forwards your Segment events to StackAdapt. This lets you generate retargeting and lookalike audiences, track conversions, and measure return on ad spend using your Segment events - bypassing the need to install the StackAdapt pixel on your website and write code to send events to StackAdapt.

This destination is maintained by StackAdapt. For any issues with the destination, submit a ticket to [StackAdapt's support team](https://support.stackadapt.com/hc/en-us/requests/new?ticket_form_id=360006572593).

## Getting started

### Getting your StackAdapt universal pixel ID

1. Log in to your StackAdapt account and navigate to the Pixels page.
2. Click **Install StackAdapt Pixel**.

   ![Highlighted link to install StackAdapt Pixel in the navigation bar.](https://docs-resources.prod.twilio.com/fb8624a3c84475df6c822918d35225141e80888a67d66c00baf3516a0b7104d8.png)
3. In the instructions that appear, copy the universal pixel ID from the code snippet. For example, the universal pixel ID in this code snippet is `sqQHa3Ob1hFi__2EcYYVZg1`.

![StackAdapt Pixel instructions with code snippet for universal pixel ID.](https://docs-resources.prod.twilio.com/e3d5c7f684051aa7e72b85d968384aa722235f903703ff8fdaff55ac69285b6f.png)

### Setting up the StackAdapt destination

1. From the Segment web app, navigate to **Connections > Catalog > Destinations**.
2. Search for and select the "StackAdapt" destination.
3. Click **Add Destination**.
4. Select an existing source to connect to the StackAdapt destination.
5. Give the destination a name.
6. On the Settings screen, provide your StackAdapt Universal Pixel ID. This can be found on the [Pixels page in StackAdapt](#getting-your-stackadapt-universal-pixel-id).
7. Toggle on the destination using the **Enable Destination** toggle.
8. Click **Save Change**.

### StackAdapt Pixel setup

Segment events that are forwarded to StackAdapt can be used to track ad conversions, and to generate retargeting and lookalike audiences. Review the StackAdapt documentation for the general setup of these if you are not already familiar:

* [Creating Conversion Events](https://support.stackadapt.com/hc/en-us/articles/360005859214-Creating-Conversion-Events)
* [Creating Retargeting Audiences](https://support.stackadapt.com/hc/en-us/articles/360005939153-Creating-Retargeting-Audiences)
* [How to Generate and Target a Lookalike Audience](https://support.stackadapt.com/hc/en-us/articles/360023738733-How-to-Generate-and-Target-a-Lookalike-Audience)

Setup of conversion events, retargeting audiences, and lookalike audiences that fire on Segment events is largely the same as the setup in the StackAdapt documentation, with a few caveats:

1. You **must** select "Universal Pixel" as the pixel type. This is because the StackAdapt destination in Segment uses your Universal Pixel ID to send events to StackAdapt.
2. There is no need to install the StackAdapt pixel on your website as instructed in the "Installation" step. Segment will forward events to StackAdapt that would normally be tracked by the StackAdapt pixel.
3. If you choose to set up event rules, ensure that you use the event keys supported by the StackAdapt destination.

### Event rules

The StackAdapt Segment destination sends an `action` event key which by default is mapped to the Segment event name. Creating rules on this `action` key should be sufficient most simple event rule use cases. For example, if you fire a Segment event when a user fills out a registration form on your website and want to track this as a conversion event in StackAdapt, you can create a rule in StackAdapt that matches the `action` key with the Segment event name.

A Segment event fired with the code `analytics.track("User Registered")` can be tracked as a conversion event with an event rule that matches an `action` of `User Registered` as shown below:

![Event rule in StackAdapt that matches a User Registered event.](https://docs-resources.prod.twilio.com/57b3b376dc1558a4818a061f1797b7b0c41d6f62af23478fd2f02b596646f431.png)

#### Ecommerce events

The StackAdapt destination also supports forwarding ecommerce fields for the purpose of creating event rules that match ecommerce events, with default mappings to properties specified in the [Segment v2 Ecommerce Event Spec](/docs/segment/connections/spec/ecommerce/v2/) as described in the table:

| Segment Ecommerce Event Property | StackAdapt Event Key |
| -------------------------------- | -------------------- |
| `order_id`                       | `order_id`           |
| `revenue`                        | `revenue`            |
| `product_id`                     | `product_id`         |
| `category`                       | `product_category`   |
| `name`                           | `product_name`       |
| `price`                          | `product_price`      |
| `quantity`                       | `product_quantity`   |

For events that can involve multiple products, such as checkout events, StackAdapt forwards a JSON array of product objects with a `products` key and fields that map by default to following Segment product array fields:

| Segment Ecommerce Event Property | StackAdapt Product Object Key |
| -------------------------------- | ----------------------------- |
| `products.$.product_id`          | `product_id`                  |
| `products.$.category`            | `product_category`            |
| `products.$.name`                | `product_name`                |
| `products.$.price`               | `product_price`               |
| `products.$.quantity`            | `product_quantity`            |

For example, to create a conversion event when an order is completed with a revenue value greater than 10, you could set up an event rule matching an `action` value of `Order Completed` and a `revenue` value greater than 10:

![Event rule in StackAdapt that matches an Order Completed event with a revenue greater than 10.](https://docs-resources.prod.twilio.com/d1d7d0fe5fca2bcdc84424b997fa13c6a4f86eece87f62a8408f33ee73bb1c8e.png)

This rule would match a Segment event fired with code such as:

```javascript
analytics.track('Order Completed', {
  order_id: '50314b8e9bcf000000000000',
  revenue: 11.5
  products: [
    {
      product_id: '507f1f77bcf86cd799439011',
      name: 'Monopoly: 3rd Edition',
      price: 11.5,
      quantity: 1,
      category: 'Games'
    }
  ]
});
```

#### Trait fields

Although trait fields are not frequently used in event rules, the StackAdapt destination forwards them and they can be used if desired.

| Segment Trait Property | StackAdapt Event Key |
| ---------------------- | -------------------- |
| `traits.email`         | `email`              |
| `traits.first_name`    | `first_name`         |
| `traits.last_name`     | `last_name`          |
| `traits.phone`         | `phone`              |

For example, to create a conversion event when a user with the domain `example.com` completes an order, you could set up an event rule matching an `action` value of `Order Completed` and an `email` containing `@example.com` as shown below:

![Event rule in StackAdapt that matches an Order Completed event with an email containing @example.com.](https://docs-resources.prod.twilio.com/0a4c6996dcb6beec4fb0baddb45ad5c538260bfdd188e7c2bff37efd7829fa69.png)

This rule would match a Segment event fired with code such as:

```javascript
analytics.track("Order Completed", {
  order_id: "50314b8e9bcf000000000000",
  traits: {
    email: "john.smith@example.com",
    first_name: "John",
    last_name: "Smith",
    phone: "+180055501000"
  }
});
```

### URL rules

If you are using URL rules, these will be matched whenever Segment sends an event to StackAdapt with a `url` matching the URL rule. This should be accomplished by the page event Segment automatically fires when a page is viewed, so setup of URL rules should be identical to setting up URL rules with the StackAdapt pixel.

### Conversion tracking with backend events

When you send events to Segment from your backend, which are forwarded to StackAdapt using Segment's backend SDKs, the user agent and IP address of the user who originated the event must be included in the event context for conversions to be tracked. StackAdapt uses the user agent and IP address to attribute the conversion to the correct event to a user who has interacted with your ads. Examples of how to do this can be found in the documentation for [Segment's SDKs](/docs/segment/connections/sources/catalog/#server). For example, for the [Python SDK](/docs/segment/connections/sources/catalog/libraries/server/python/#override-context-value) this can be done as follows:

```python
analytics.track('user_id', 'Order Completed', context={
  'ip': '203.0.113.1',
  'userAgent': 'Mozilla/5.0 (Linux; U; Android 4.1.1; en-gb; Build/KLP) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30'
})
```

This is necessary when using backend SDKs but not for events sent from the frontend with `analytics.js`, because `analytics.js` automatically includes the user agent and IP address in the event context.

### Conversion tracking with Reverse ETL

When sending past events to StackAdapt using a [Reverse ETL tool](/docs/segment/connections/reverse-etl/reverse-etl-catalog/), the user agent, IP address, event type, and either the page URL (for conversion trackers with URL rules), or the fields the event rules match on, must be included in your mappings. For example, the mapping for a Snowflake source can be used to match a conversion tracker with an event rule that matches an `action` of `User Registered`:

![Snowflake mapping showing IP, User Agent, Segment User ID, track and User Registered to corresponding fields.](https://docs-resources.prod.twilio.com/9d257d0578b5c8506cf5ce80c1eef1c5e869eafbd5b2d4997e34648772d108c0.png)

Rows forwarded to StackAdapt with this mapping will be matched by the `User Registered` event rule shown below:

![Event rule in StackAdapt that matches a User Registered event.](https://docs-resources.prod.twilio.com/57b3b376dc1558a4818a061f1797b7b0c41d6f62af23478fd2f02b596646f431.png)

When forwarding past events using [Reverse ETL](/docs/segment/connections/reverse-etl/), only users who have interacted with an ad from an associated campaign within the conversion tracker's configured view-through expiry window (for impressions) or click-through expiry window (for clicks) will count as conversions. These windows can be set to up to 180 days in the conversion tracker configuration.

## Destination Settings

| Field              | Description                        | Required | Type   |
| ------------------ | ---------------------------------- | -------- | ------ |
| Universal Pixel ID | Your StackAdapt Universal Pixel ID | Yes      | string |

## Available Presets

StackAdapt Events & Conversions  has the following presets

| Preset Name   | Trigger                                                                                      | Default Action |
| ------------- | -------------------------------------------------------------------------------------------- | -------------- |
| Forward Event | Event type = "identify", Event  type = "page", Event  type = "screen", Event  type = "track" | Forward Event  |

## Available Actions

Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following StackAdapt Events & Conversions -supported actions:

> \[!NOTE]
>
> Individual destination instances have support a maximum of 50 mappings.

* [Forward Event](#forward-event)

### Forward Event

Forward Segment events to StackAdapt for conversion tracking

Forward Event is a **Cloud** action. The default Trigger is `type = "identify" or type = "page" or type = "screen" or type = "track"`

| Field           | Description                                                                                                 | Required | Type   |
| --------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------ |
| Segment User ID | The ID of the user in Segment                                                                               | No       | STRING |
| Event Type      | The Segment event type (page, track, etc.)                                                                  | No       | STRING |
| Event Name      | The event name (e.g. Order Completed)                                                                       | No       | STRING |
| IP Address      | IP address of the user                                                                                      | Yes      | STRING |
| Page Title      | The title of the page where the event occurred.                                                             | No       | STRING |
| URL             | The URL of the page where the event occurred.                                                               | No       | STRING |
| Referrer        | The referrer of the page where the event occurred.                                                          | No       | STRING |
| UTM Source      | UTM source parameter associated with event                                                                  | No       | STRING |
| User Agent      | User-Agent of the user                                                                                      | Yes      | STRING |
| Email           | Email address of the individual who triggered the event.                                                    | No       | STRING |
| Phone Number    | Phone number of the individual who triggered the event                                                      | No       | STRING |
| First Name      | First name of the individual who triggered the event.                                                       | No       | STRING |
| Last Name       | Last name of the individual who triggered the event.                                                        | No       | STRING |
| Ecommerce Data  | Additional ecommerce fields that are included in the pixel payload.                                         | No       | OBJECT |
| Products        | The list of products associated with the event (for events with multiple products, such as Order Completed) | No       | OBJECT |

## Data and privacy

Review [StackAdapt's Data Processing Agreement](https://www.stackadapt.com/data-processing-agreement) to learn more about StackAdapt's privacy and data terms.