# Segment

Aggregations.io enables you to monitor and utilize your Segment data in real time. When combined with the Grafana plugin, you can visualize and alert on your Segment analytics events with ease.

---

## Prerequisites 

To set up this integration you'll need to first:

1) [Set up an ingest](/ingest/create-ingest) using the `Array of JSON Objects` schema.
2) [Create an API Key](/api-keys/#create) with `Write` permissions to use with this integration. We'd recommend creating a dedicated `Org-Wide` API Key.
3) A segment account with incoming data sources.

---

## Setting up the destination

#### 1 - Add a new Aggregations.io (Actions) destination

Navigate to your organization's `Destinations` page on Segment and choose `Add Destination`

Search for `Aggregations.io` and select it.

!!!info
If you can't find it in the search results, you need to navigate directly to the destination page by replacing your `{WORKSPACE}` in the url below:
`https://app.segment.com/{WORKSPACE}/destinations/catalog/actions-aggregations-io`
!!!

Click the `Add Destination` button

:::spacer-1
:::

#### 2 - Select data source

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-2.png">
<img src="/docs/assets/images/segment/step-2.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next
Choose the relevant data source whose events you want to utilize in Aggregations.io.
:::

:::clear-both
:::
:::spacer-1
:::

!!! info
If you have multiple sources, you'll need to follow this guide for each. You can opt to utilize the same ingestion & API keys across multiple Segment sources, or create separate ones for isolation. In most cases, reuse makes sense for consistency and simplicity.
!!!

#### 3 - Name your Destination

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment-webhook/step-3.png">
<img src="/docs/assets/images/segment-webhook/step-3.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next
Give your destination a useful name like `Aggregations.io`

If you are creating multiple destinations for different sources but want to utilize the same settings, you can choose to copy them at this step.
:::
:::clear-both
:::

#### 4 - Destination Settings

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-4.png">
<img src="/docs/assets/images/segment/step-4.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next
Enter your **API Key** and **Ingest Id**. 

- Your API Key requires `Write` permissions. 
  - Learn more about creating a new API Key [here.](/api-keys) 
- Your ingest needs to be set up as `Array of JSON Objects`.  
  - You can find your Ingest Id on your [Organization Page](https://app.aggregations.io/organization){target="_blank"}
  - Learn more about ingest setup [here.](/ingest/create-ingest)

While setting up and testing your destination, you should leave the destination disabled.

:::
:::clear-both
:::

#### 5 - Mappings 

||| Add A mapping
Click on the `Mappings` tab and choose `+ New Mapping`

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-5_1.png">
<img src="/docs/assets/images/segment/step-5_1.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

||| Select Action
Choose `Send Events` from the Actions list

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-5_2.png">
<img src="/docs/assets/images/segment/step-5_2.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>
|||
 
#### 6 - Mappings, Selecting events

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-5_3.png">
<img src="/docs/assets/images/segment/step-5_3.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next

Select your filter settings, if you want to restrict the data flowing into Aggregations.io. Segment has made this functionality very powerful, see their guide [here](https://segment.com/docs/connections/destinations/actions/#customize-mappings){target="_blank"} to understand the full capability.

For our example, we know we want to count just `Track`, `Page` and `Screen` events, so that's what we select.

:::
:::clear-both
:::

#### 7 - Mappings, Test event

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper     float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment-webhook/step-6.png">
<img src="/docs/assets/images/segment-webhook/step-6.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next 

Scroll to section (2) and either load a test event from your Segment setup or just load a sample event. 
:::
:::clear-both
:::
#### 8 - Mappings, Selecting mappings

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper blocked  w-100    ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-8.png">
<img src="/docs/assets/images/segment/step-8.png" alt=""   />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::spacer-1
:::

Scroll to section (3) and adjust any necessary settings. 

By default, batching is enabled and the entire event payload is sent. You can use these settings to customize the payload or disable batching (not recommended).

#### 9 - Mapping, Test Mapping

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper blocked    float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment/step-9.png">
<img src="/docs/assets/images/segment/step-9.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next 

Assuming the above steps are filled in, your `Test Mapping` button should be enabled. Click it! 

If not, review the steps above to ensure you have mapped all the fields and you have a test event set up.

If your test succeeds, you should get back an empty payload. 

If there is an error, see below.
:::
:::clear-both
:::

---

## Enabling the destination

It is important to ensure both the **destination** and **mapping** are **enabled** within Segment. 

- Enable the Destination on the `Settings` tab
- Enable the Mapping on the `Mappings` tab

---

## Timestamps

When setting up an ingestion to use with Segment, you may want to rely on one of Segment's timestamps instead of the `Use Ingest Timestamp` option. 

You'll want to be careful to choose on of Segment's non-client-authoratitive timestamps like `receivedAt` in order to ensure it's a correct format. See Segment's docs on timestamps [here.](https://segment.com/docs/connections/spec/common/#timestamps){target="_blank"}

<div style="--cols:1;" class="border-lightgrey integration-img-wrapper blocked    float-right ">

<div>
<a class="img-lb" data-fslightbox="guideimg" href="/docs/assets/images/segment-webhook/timestamps.png">
<img src="/docs/assets/images/segment-webhook/timestamps.png" alt=""   width="400"  />
<div class="zoom-icon">

:icon-search:

</div>
</a>
</div>

</div>

:::mw-floated-next 

To utilize `receivedAt` when setting up your ingest:

- Choose `Use Custom Timestamp Property`
- Set `Timestamp Format` to `ISO 8601 String`
- Set `Timestamp Path` to `@.receivedAt`

:::
:::clear-both
:::

---

## Troubleshooting

#### Error Codes

See the [Ingest Docs](/ingest/posting-events#troubleshooting) for common errors ingesting events. 

#### Reversed headers

If you receive an error indicating `No Authorization Header` it may indicate you've reversed the API Key value and header name

#### Extra headers

If you accidentally add an extra blank header in the mapping you may receive an error ` is not a legal HTTP header name`, simply delete the extraneous header.