# Segment Integration

ABsmartly has a native integration with [Segment](https://www.segment.com), allowing you to seamlessly send events between the two, now using Segment's Actions API.

## Benefits of ABsmartly (Actions) vs ABsmartly Classic

* **Easier Setup**: Actions-based destinations are easier to configure with clear default settings, letting you quickly get started.
* **Control and Clearer Mapping**: Actions-based destinations enable you to define the mapping between the data Segment receives from your source and the data Segment sends to ABsmartly.

## Getting Started

1. From the Segment web app, click **Catalog**.

2. Search for “ABsmartly” in the Catalog, select **ABsmartly (Actions)**, and choose which of your sources to connect the destination to.

3. Add the following Connection Settings:

   <!-- -->

   * **Collector Endpoint**: Your ABsmartly Collector REST Endpoint. Usually `https://{YOUR-SUBDOMAIN}.absmartly.io/v1`.
   * **API Key**: An existing API Key. Created under `Settings>API Keys` in the ABsmartly Web Console.
   * **Environment**: The environment where the events are originated matching an existing environment in ABsmartly. Created under `Settings>Environments` in the ABsmartly Web Console.

4. Enable the *Track Calls* mapping to send events to ABsmartly.

### Destination Settings

| Setting            | Required | Description                                                                                                                                                           |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key            | ✅       | ABsmartly SDK API Key. Create SDK Api Keys in the `Settings>API Keys` section of the ABsmartly Web Console.                                                           |
| Collector Endpoint | ✅       | ABsmartly Collector endpoint, for example: `https://your-subdomain.absmartly.io/v1`. Contact ABsmartly Support if you don’t know your Collector Endpoint.             |
| Environment        | ✅       | Environment name. Environment name needs to match what’s in the Web Console. Create Environments in the `Settings>Environments` section of the ABsmartly Web Console. |

## Available Presets

ABsmartly (Actions) has the following presets:

| Preset Name          | Trigger                                                   | Default Action |
| -------------------- | --------------------------------------------------------- | -------------- |
| Page Calls           | `Event type = "page"`                                     | Track Goal     |
| Exposures (Verbatim) | `Event type = "track"` and `event = "Experiment Viewed"`  | Track Exposure |
| Screen Calls         | `Event type = "screen"`                                   | Track Goal     |
| Track Calls          | `Event type = "track"` and `event != "Experiment Viewed"` | Track Goal     |

## Available Actions

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

> **Mapping limits per destination**
>
> Individual destination instances have support a maximum of 50 mappings.

* [Track Exposure](https://segment.com/docs/connections/destinations/catalog/actions-absmartly/#track-exposure)
* [Track Goal](https://segment.com/docs/connections/destinations/catalog/actions-absmartly/#track-goal)

### Track Exposure

Send an experiment exposure event to ABsmartly

Track Exposure is a **Cloud** action. The default Trigger is:

```python
type = "track" and event = "Experiment Viewed"
```

| Field                      | Type     | Description                                                                                                                                                             |
| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ABsmartly Exposure Payload | `Object` | The ABsmartly exposure payload.                                                                                                                                         |
| Agent                      | `String` | Optional agent identifier that originated the event. Used to identify which SDK generated the event.                                                                    |
| Application                | `String` | Optional application name that originated this event. Must exist if not empty. Create Applications in the `Settings>Applications` section of the ABsmartly Web Console. |

### Track Goal

Send a goal event to ABsmartly

Track Goal is a **Cloud** action. The default Trigger is:

```python
type = "track" and event != "Experiment Viewed"
```

| Field           | Type     | Description                                                                                                                                                              |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Units           | `Object` | The units of the goal to track. Mapping of unit name to source property in the event payload. Create Units in the `Settings>Units` section of the ABsmartly Web Console. |
| Goal Name       | `String` | The name of the goal to track.                                                                                                                                           |
| Goal Properties | `Object` | Custom properties of the goal.                                                                                                                                           |
| Agent           | `String` | Optional agent identifier that originated the event. Used to identify which SDK generated the event.                                                                     |
| Application     | `String` | Optional application name that originated this event. Must exist if not empty. Create Applications in the `Settings>Applications` section of the ABsmartly Web Console.  |

> **info**
>
> If you need support setting things up, you can contact the ABsmartly support team on Slack or via [email](mailto:support@absmartly.com).

## Sending Exposures to Segment

It can be useful to send experiment exposures to Segment for visibility from other destinations. The Segment Spec includes the [Experiment Viewed](https://segment.com/docs/connections/spec/ab-testing/) semantic event for this purpose.

> **info**
>
> By default, the *Track Calls* mapping will filter and not send any events with the name `Experiment Viewed` to ABsmartly.

You can [install a custom event logger](https://docs.absmartly.com/docs/APIs-and-SDKs/SDK-Documentation/getting-started.md) in ABsmartly and send exposures directly to Segment.

```javascript
analytics.ready(function () {
  // initialize ABSmartly SDK
  const sdk = new absmartly.SDK({
    endpoint: "https://your-absmartly-endpoint.absmartly.io/v1",
    apiKey: "<YOUR-API-KEY>",
    environment: "development",
    application: "YOUR-APP",
    eventLogger: (context, eventName, data) => {
      if (eventName == "exposure") {
        // filter only relevant and interesting exposures
        // if the assigned flag is false, this exposure was a treatment call that did not result in an assignment
        // this can happen if, for example, the experiment is no longer running, but treatment() calls are still in the application code
        if (exposure.assigned) {
          analytics.track("Experiment Viewed", {
            experiment_id: exposure.id,
            experiment_name: exposure.name,
            variation_id: exposure.variant,
            variation_name: "ABCDEFG"[exposure.variant],
          });
        }
      }
    },
  });

  const context = sdk.createContext(request);
  context.attribute("user_agent", navigator.userAgent);

  context
    .ready()
    .then((response) => {
      console.log("ABSmartly Context ready!");
      console.log(context.treatment("test-exp"));
    })
    .catch((error) => {
      console.log(error);
    });
});
```

## Publishing Experiment Exposures Through Segment

To publish experiment exposures through Segment, you must first configure and enable the *Exposures (Verbatim)* mapping in your ABsmartly (Actions) destination.

By enabling the *Exposures (Verbatim)* mapping in Segment, you replace the direct flow of exposure events from the ABsmartly SDK to the ABsmartly collector and instead send them to Segment for processing by the destination function.

This can be achieved by instantiating the ABsmartly SDK with a custom context publisher.

The custom publisher will publish an `Experiment Viewed` Segment event with ABsmartly’s exposure data in the `properties.exposure` field as well as the normal semantic data that Segment recommends for this event.

Here is an example in Javascript:

```javascript
analytics.ready(function () {
  // initialize ABSmartly SDK
  const sdk = new absmartly.SDK({
    endpoint: "https://your-absmartly-endpoint.absmartly.io/v1",
    apiKey: "<YOUR-API-KEY>",
    environment: "development",
    application: "YOUR-APP",
  });

  // ABSmartly publisher implementation that publishes ABSmartly exposures to Segment,
  // instead of directly to the ABSmartly Collector
  // these will then be pushed by the ABSmartly segment integration to the ABSmartly collector
  class SegmentContextPublisher extends absmartly.ContextPublisher {
    constructor(segment) {
      super();

      this._segment = segment;
    }

    publish(request, sdk, context) {
      // NOTE: only exposures are expected to come via this route
      // other types of events should be tracked through the Segment API
      if (request.exposures) {
        for (const exposure of request.exposures) {
          this._segment.track(`Experiment Viewed`, {
            experiment_id: exposure.id,
            experiment_name: exposure.name,
            variation_id: exposure.variant,
            variation_name: "ABCDEFG"[exposure.variant],
            absmartly: Object.assign(
              {},
              {
                exposures: [exposure],
              },
              // add anything else in the ABsmartly payload that are not exposures or goals
              ...Object.entries(request)
                .filter((e) => e[0] !== "exposures" && e[0] !== "goals")
                .map((e) => ({ [e[0]]: e[1] }))
            ),
          });
        }
      }

      return Promise.resolve();
    }
  }

  // set this as the default publisher - all contexts created from now on will use it by default
  sdk.setContextPublisher(new SegmentContextPublisher(analytics));

  const request = {
    units: {
      userId: analytics.user().id(),
      anonymousId: analytics.user().anonymousId(),
    },
  };

  window.context = sdk.createContext(request);
  context.attribute("user_agent", navigator.userAgent);

  context
    .ready()
    .then((response) => {
      console.log("ABSmartly Context ready!");
      console.log(context.treatment("test-exp"));
    })
    .catch((error) => {
      console.log(error);
    });
});
```

## Migration from the ABsmartly Classic Destination

To migrate from the classic ABsmartly destination to ABsmartly (Actions), disconnect the classic ABsmartly destination before enabling the ABsmartly (Actions) destination to avoid duplicate experimentation events.

**Looking for the deprecated ABsmartly Classic Segment integration?**

This is a Lambda function that runs on [Segment](https://www.segment.com) for ABsmartly Integration.

It extracts the relevant data from Segment events and sends it, correctly formatted, to the ABsmartly Collector endpoint.

It can also be added directly as a destination function on a Segment workspace.

## Configuring a Workspace Destination Function

If you are configuring a destination function on your workspace, these are the necessary settings:

### Collector Endpoint

* **Type:** String
* **Required:** \&#9989
* **Javascript:** `settings.collectorEndpoint`

Your dedicated ABsmartly Collector Endpoint. Example: `https://demo.absmartly.io/v1`

### API Key

* **Type:** String
* **Required:** \&#9989
* **Javascript:** `settings.apiKey`

API Key to use when sending events to the ABsmartly Collector. API Keys are created in the ABsmartly Web Console's Settings section.

### Environment

* **Type:** String
* **Required:** \&#9989
* **Javascript:** `settings.environment`

The environment name where the events are originating (case sensitive). Environments are created in the ABsmartly Web Console's Settings section.

### Unit Mapping

* **Type:** Mapping
* **Required:** \&#9989
* **Javascript:** `settings.unitMapping`

Mapping of Segment identity to ABsmartly Unit. Mapping of Segment identity to ABsmartly Unit. Example `anonymousId` -> `anonymous_uuid`, `userId` -> `user_id`. Units are created in the ABsmartly Web Console's Settings section.

> **note**
>
> This mapping is required, even if the names are exactly the same.

### EnableExposureTracking

* **Type:** Boolean
* **Required:** \&#10060
* **Javascript:** `settings.enableExposureTracking`

Enable sending ABsmartly exposures to the ABsmartly Collector.

> **note**
>
> Enable this **only** if you instantiate the ABsmartly SDK with a **custom** publisher and are sending ABsmartly exposures through Segment.

### EnablePageViewTracking

* **Type:** Boolean
* **Required:** \&#10060
* **Javascript:** `settings.enablePageViewTracking`

Enable sending Segment's [Page events](https://segment.com/docs/connections/spec/page/) as goals to the ABsmartly Collector.

> **caution**
>
> These events tend to happen very frequently and may increase storage cost.

> **note**
>
> The goal generated will have the name `Page: <Page Name>` for example `Page: Home` and needs to have been previously created in the ABsmartly Web Console's Settings section.

### EnableAppScreenViewTracking

* **Type:** Boolean
* **Required:** \&#10060
* **Javascript:** `settings.enableAppScreenViewTracking`

Enable sending Segment's [Screen events](https://segment.com/docs/connections/spec/screen/) as goals to the ABsmartly Collector.

> **caution**
>
> These events tend to happen very frequently and may increase storage cost.

> **note**
>
> The goal generated will have the name `Screen: <Screen Name>` for example `Screen: Login` and needs to have been previously created in the ABsmartly Web Console's Settings section.

### Goal Mapping

* **Type:** Mapping
* **Required:** \&#10060
* **Javascript:** `settings.goalMapping`

Mapping of Segment event names to ABsmartly goal names. If a mapping exists, it will be used, otherwise the original event name will be used as the goal name.

## Advanced Usage

### Sending experiment exposures to Segment

It can be useful to send experiment exposures to Segment for visibility from other destinations. The Segment spec includes the [`Experiment Viewed` semantic event](https://segment.com/docs/connections/spec/ab-testing/) for this purpose.

In the ABsmartly context, we can [install a custom event logger](https://docs.absmartly.com/docs/APIs-and-SDKs/SDK-Documentation/getting-started.md) and send exposures directly to Segment.

```javascript
analytics.ready(function () {
  // initialize ABSmartly SDK
  const sdk = new absmartly.SDK({
    endpoint: "https://your-absmartly-endpoint.absmartly.io/v1",
    apiKey: "<YOUR-API-KEY>",
    environment: "development",
    application: "YOUR-APP",
    eventLogger: (context, eventName, data) => {
      if (eventName == "exposure") {
        // filter only relevant and interesting exposures
        // if the assigned flag is false, this exposure was a treatment call that did not result in an assignment
        // this can happen if, for example, the experiment is no longer running, but treatment() calls are still in the application code
        if (exposure.assigned) {
          analytics.track("Experiment Viewed", {
            experiment_id: exposure.id,
            experiment_name: exposure.name,
            variation_id: exposure.variant,
            variation_name: "ABCDEFG"[exposure.variant],
          });
        }
      }
    },
  });

  const context = sdk.createContext(request);
  context.attribute("user_agent", navigator.userAgent);

  context
    .ready()
    .then((response) => {
      console.log("ABSmartly Context ready!");
      console.log(context.treatment("test-exp"));
    })
    .catch((error) => {
      console.log(error);
    });
});
```

### Mapping Segment Identities to ABsmartly Units

For simple mappings, you can map Segment's identities/properties to ABsmartly's units in your ABsmartly integration settings in Segment.

If you want to programmatically make this mapping, you can install a middleware in your Segment SDK that will append the units to the `properties.absmartly.units` field before sending to Segment. The destination function will extract and use that instead. This may be useful if you are running ABsmartly experiment on units that are not the typical Segment `anonymousId` or `userId`.

```javascript
// example absmartly middle to enrich segment track, page and screen events with relevant
analytics.ready(function () {
  // absmartly units - useful if you want to run experiments on units that are not your segment users
  const absmartlyMiddleware = function ({ payload, next, integrations }) {
    const type = payload.obj.type;
    switch (type) {
      case "track":
      case "page":
      case "screen":
        const event = payload.obj;
        const props = event.properties;

        const units = [];

        // always send the current user's units
        const anonymousId =
          "anonymousId" in event
            ? event["anonymousId"]
            : analytics.user().anonymousId();
        units.push({ type: "anonymousId", uid: anonymousId });

        // additionally, if we have any other units, add them
        if (event.userId) {
          units.push({ type: "userId", uid: event.userId });
        }

        // add any additional product units from properties, for example, when running product experiments
        // event will also be assigned to these units in absmartly
        if (props.productId) {
          units.push({ type: "productId", uid: props.productId });
        }

        if (props.products) {
          for (const product of props.products) {
            units.push({ type: "productId", uid: product.productId });
          }
        }

        props["absmartly"] = { units };
        break;
      default:
        break;
    }

    next(payload);
  };

  // add it as middleware
  analytics.addSourceMiddleware(absmartlyMiddleware);
});
```

### Publishing Experiment Exposures Through Segment

To publish experiment exposures, you must turn on `EnableExposureTracking` in your destination settings in Segment.

We want to replace the direct flow of exposure events from the ABsmartly SDK to the ABsmartly collector, by instead sending them to Segment for processing by the destination function.

This can be achieved by instantiating the ABsmartly SDK with a custom context publisher.

The custom publisher will publish an `Experiment Viewed` Segment event with ABsmartly's exposure data in the `properties.absmartly` field as well as the normal semantic data that Segment recommends for this event.

Here is an example in Javascript.

```javascript
analytics.ready(function () {
  // initialize ABSmartly SDK
  const sdk = new absmartly.SDK({
    endpoint: "https://your-absmartly-endpoint.absmartly.io/v1",
    apiKey: "<YOUR-API-KEY>",
    environment: "development",
    application: "YOUR-APP",
  });

  // ABSmartly publisher implementation that publishes ABSmartly exposures to Segment,
  // instead of directly to the ABSmartly Collector
  // these will then be pushed by the ABSmartly segment integration to the ABSmartly collector
  class SegmentContextPublisher extends absmartly.ContextPublisher {
    constructor(segment) {
      super();

      this._segment = segment;
    }

    publish(request, sdk, context) {
      // NOTE: only exposures are expected to come via this route
      // other types of events should be tracked through the Segment API
      if (request.exposures) {
        for (const exposure of request.exposures) {
          this._segment.track(`Experiment Viewed`, {
            experiment_id: exposure.id,
            experiment_name: exposure.name,
            variation_id: exposure.variant,
            variation_name: "ABCDEFG"[exposure.variant],
            absmartly: Object.assign(
              {},
              {
                exposures: [exposure],
              },
              // add anything else in the ABsmartly payload that are not exposures or goals
              ...Object.entries(request)
                .filter((e) => e[0] !== "exposures" && e[0] !== "goals")
                .map((e) => ({ [e[0]]: e[1] }))
            ),
          });
        }
      }

      return Promise.resolve();
    }
  }

  // set this as the default publisher - all contexts created from now on will use it by default
  sdk.setContextPublisher(new SegmentContextPublisher(analytics));

  const request = {
    units: {
      userId: analytics.user().id(),
      anonymousId: analytics.user().anonymousId(),
    },
  };

  window.context = sdk.createContext(request);
  context.attribute("user_agent", navigator.userAgent);

  context
    .ready()
    .then((response) => {
      console.log("ABSmartly Context ready!");
      console.log(context.treatment("test-exp"));
    })
    .catch((error) => {
      console.log(error);
    });
});
```

## Finishing Up

You should now have your ABsmartly Segment integration fully set up!

If you are looking for more information, feel free to ask a question in your organization's dedicated ABsmartly Slack channel.
