# Universal Collect

Universal Collect is compatible with both Decision API implementations (for both server-side and client-side applications) and Flagship SDKs.

{% hint style="warning" %}
In order to see your events in the ABTasty reporting interface, the visitor first needs to be [assigned to a use case](https://docs.abtasty.com/server-side/decision-api).
{% endhint %}

**Common arguments**

There are certain arguments that are **required** for every hit type. You should get to know them before reading into hit-specific arguments.

* Common Arguments list

**Hits**

Learn more about the specific arguments and rules associated with each hit type by clicking on the hit names below.

**Hits that are automatically sent by the JS tag (or sent by you in case of POST):**

* Screenview

**Hits that should be implemented by you:**

* Pageview
* Screenview
* Event
* Transaction
* Item

#### Common Arguments list

These arguments can be sent with any type of hit. Including more data with your hit will yield more actionable reports so you can more clearly identify what works, what doesn't work, and where you can drill down further.

**Summary**

* **Required** for all hit types:
  * Type
  * Environment ID
  * Visitor ID
  * Data Source
* **Required** for Screenview & Pageview hits only:
  * Document Location URL
  * Optional for all hit types
  * Protocol Version (optional)
  * User IP (optional)
  * Document Referrer (optional)
  * Viewport Size (optional)
  * Screen Resolution (optional)
  * Document Encoding (optional)
  * Screen Color Depth (optional)
  * User Language (optional)
  * Java Enabled (optional)
  * Flash Version (optional)
  * Current Session Timestamp (optional)
  * Session Number (optional)

**Type**

**Required** for all hit types

This argument refers to the type of hit.

* `CAMPAIGN`
* `PAGEVIEW` (hit documentation)
* `SCREENVIEW` (hit documentation)
* `EVENT` (hit documentation)
* `ITEM` (hit documentation)
* `TRANSACTION` (hit documentation)

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **t**     | string     | *None*        | *None*     | all                 |

* Example value: `SCREENVIEW`
* Example usage: `t=SCREENVIEW`

> 📘 CAMPAIGN hit
>
> You might see some `CAMPAIGN` hits when browsing your network. They are automatically sent when:
>
> * You call the `/campaign` Decision API endpoint with the `trigger_hit` parameter not set to `false`
> * You call the `/activate` Decision API endpoint
> * You use one of the activate method available in SDKs (with API or Bucketing mode)

**Environment ID**

**Required** for all hit types

This argument refers to the unique ID of the environment in FE\&R (prod or preprod).

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **cid**   | string     | None          | 32 Bytes   | all                 |

* Example value: `bmg9e8r7serg0gvp30s0`
* Example usage: `cid=bmg9e8r7serg0gvp30s0`

**Visitor ID**

**Required** for all hit types

This argument refers to the unique ID associated with the application user or website visitor.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **vid**   | string     | *None*        | 50 Bytes   | all                 |

* Example value: `user1234354`
* Example usage: `vid=user1234354`

**Data Source**

**Required** for all hit types

This argument refers to the data source type. The value should be set to `APP`.

| Parameter | Value Type | Default Value | Max Length |
| --------- | ---------- | ------------- | ---------- |
| **ds**    | string     | APP           | 10 Bytes   |

* **Required** value: `APP`
* **Required** usage: `ds=APP`

**Protocol Version**

Optional for all hit types

This argument refers to the Universal Collect protocol version. The value will only change when there are changes that are not backwards compatible.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **v**     | integer    | 1             | *None*     | all                 |

* Example value: `1`
* Example usage: `v=1`

**User IP**

Optional for all hit types

This argument refers to the IP address of the user. This should be a valid IP address in IPv4 or IPv6 format. It will always be anonymized.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **uip**   | string     | *None*        | 45 Bytes   | all                 |

* Example value: `52.311.94.68`
* Example usage: `uip=52.211.94.68`

**Document Referrer**

Optional for all hit types

This argument identifies the referral source of traffic to an application or website. This value is also used to compute the traffic source. The format of this value is a URL.

CLARIFY: how is the traffic source computed?

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **dr**    | string     | *None*        | 2048 Bytes | all                 |

* Example value: `http://example.com`
* Example usage: `dr=http%3A%2F%2Fexample.com`

**Viewport Size**

Optional for all hit types

This argument refers to the viewable area of the browser or device in pixels.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **vp**    | string     | *None*        | 20 Bytes   | all                 |

* Example value: `123x456`
* Example usage: `vp=123x456`

**Screen Resolution**

Optional for all hit types

This argument refers to the the screen resolution in pixels.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **sr**    | string     | *None*        | 20 Bytes   | all                 |

* Example value: `800x600`
* Example usage: `sr=800x600`

**Page Title**

This argument refers to the title of the page or document.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **pt**    | string     | *None*        | 1500 Bytes | all                 |

— Example value: `Settings` — Example usage: `pt=Settings`

**Document Encoding**

Web: Optional for all hit types

:::caution App: This info is not available for app :::

This argument refers to the character encoding used by the page or document.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **de**    | string     | UTF-8         | 20 Bytes   | all                 |

* Example value: `UTF-8`
* Example usage: `de=UTF-8`

**Screen Color Depth**

Optional for all hit types

This argument refers to the screen color depth.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **sd**    | string     | *None*        | 20 Bytes   | all                 |

* Example value: `24-bits`
* Example usage: `sd=24-bits`

**User Language**

Optional for all hit types

This argument refers to the user's language.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ul**    | string     | *None*        | 20 Bytes   | all                 |

* Example value: `en-us`
* Example usage: `ul=en-us`

**Java Enabled**

Optional for all hit types

This argument specifies whether or not Java is enabled by a client.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **je**    | boolean    | *None*        | *None*     | all                 |

* Example value: `1`
* Example usage: `je=1`

**Flash Version**

Optional for all hit types

This argument refers to the version of Flash used by a client.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| *fl*\*    | string     | *None*        | 20 Bytes   | all                 |

* Example value: `10 1 r103`
* Example usage: fl=10%201%20r103\`

**Queue Time**

Optional for all hit types

This argument is used to collect offline or latent hits. The value represents the time delta (in milliseconds) between the times when a hit is reported and when it is sent. The value must be greater than or equal to 0. Hits with a Queue Time value greater than four hours (14400000ms) will not be processed.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **qt**    | integer    | *None*        | *None*     | all                 |

* Example value: `560`
* Example usage: `qt=560`

**Document Location URL**

**Required** for Screenview & Pageview hit types.

This argument refers to the URL of the page, or the Screen Name of the app, at the moment the hit is sent.

> 📘 SCREENVIEW hit specificity
>
> For `SCREENVIEW`, the `dl` can be equal to any string value.

> 📘 PAGEVIEW hit specificity
>
> For `PAGEVIEW`, the value must be a valid URL. Otherwise the hit will be rejected. Also, our server will compute more information from this URL, such as domain name, path, parameters, etc.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **dl**    | string     | *None*        | 2048 Bytes | all                 |

* Example value: `https://abtastylab.com/b0711162425441fb679dc41b98f052ab/`
* Example usage: `dl=https%3A%2F%2Fabtastylab.com%2Fb0711162425441fb679dc41b98f052ab%2F`

**Current Session Timestamp**

Optional for all hit types

This argument indicates when the current session was started in Unix Epoch time.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **cst**   | Integer    | *None*        | *None*     | all                 |

* Example value: `1522053173006`
* Example usage: `cst=1522053173006`

**Session Number**

Optional for all hit types

This argument indicates the number of sessions the current visitor has logged, including the current session.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **sn**    | Integer    | *None*        | *None*     | all                 |

* Example value: `6`
* Example usage: `sn=6`

#### Hits

**Screenview**

This hit should be sent every time the visitor lands on a new screen on your application.

**Arguments**

* `SCREENVIEW` hits must implement the **Document Location URL** in addition to the **required common arguments**
* Common argument **Type** (`t`) must be set to `SCREENVIEW`

That's it! There are no other hit-specific arguements for this hit type.

**Implementation example**

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "HomeScreen",
  "t": "SCREENVIEW",
  "vid": "{{visitorId}}",
  "ds":"APP"
}'
```

**Pageview**

This hit should be sent every time the visitor lands on a new page on your website.

**Arguments**

* `PAGEVIEW` hits must implement the **Document Location URL** in addition to the **required common arguments**
* Common argument **Type** (`t`) must be set to `PAGEVIEW`

That's it! There are no other hit-specific arguements for this hit type.

**Implementation example**

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "https://www.abtasty.com",
  "t": "PAGEVIEW",
  "vid": "{{visitorId}}",
  "ds":"APP"
}'
```

**Event**

This hit type can be used to measure any events you may be interested in, from element clicks to newsletter subscriptions.

**Arguments**

* `EVENT` hits must implement the **requiredcommon arguments**
* Common argument **Type** (`t`) must be set to `EVENT`

**Event Category**

**Required** for `EVENT` hit type

This argument categorizes the event and helps us understand what you want to retrieve inside the reporting.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ec**    | string     | *None*        | 150 Bytes  | EVENT               |

* Example value: `Action Tracking`
* Example usage: `ec="Action Tracking"`

The \`ec\` must be equal to \*\*Action Tracking\*\* or \*\*User Engagement\*\*

**Event Action**

**Required** for `EVENT` hit type

This argument corresponds to the KPI name you will be able to select inside the FE\&R dashboard reporting.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ea**    | string     | *None*        | 500 Bytes  | EVENT               |

* Example value: `newsletterSubscription`
* Example usage: `ea=newsletterSubscription`

**Event Label**

Optional

This argument is a supplementary description of your event.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **el**    | string     | *None*        | 500 Bytes  | EVENT               |

* Example value: `contains status of user newsletter mode`
* Example usage: `el=contains status of user newsletter mode`

**Event Value**

Optional

The Event Value can be used to evaluate user interactions with individual site objects or content items.

For example, each new registration for a newsletter gets an event value.

The \`ev\` must be non-negative. The \`ev\` must be an integer (It won't work with float)

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ev**    | integer    | *None*        | 500 Bytes  | EVENT               |

* Example value: `1`
* Example usage: `ev=1`

**Implementation example**

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ea": "newsletterSubscription",
  "ec": "Action Tracking",
  "el": "optin",
  "ev": 1,
  "t": "EVENT",
  "vid": "18100217380532936",
  "ds": "APP"
}'
```

**Transaction**

A transaction hit should be manually configured to be sent each time a visitor completes a transaction.

Do not send \`TRANSACTION\` and \`EVENT\` hits with the same \`ta\` and \`ea\` parameter values.

A transaction can be linked to other `ITEM` hits to specify the products of the transaction (see item event documentation).

**Arguments**

* `TRANSACTION` hits must implement the **requiredcommon arguments**
* Common argument **Type** (`t`) must be set to `TRANSACTION`

**Transaction ID**

**Required** for `TRANSACTION` hit type and for `ITEM` hit type when triggered on confirmation page.

**Transaction ID`tid` values must be unique for each transaction.**

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tid**   | string     | *None*        | 500 Bytes  | TRANSACTION, ITEM   |

Example value: `OD564` Example usage: `tid=OD564`

**Transaction Affiliation**

**Required**

This argument corresponds to the KPI name you will be able to select inside the FE\&R dashboard reporting.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ta**    | string     | *None*        | 500 Bytes  | TRANSACTION         |

Example value: `Purchase` Example usage: `ta=Purchase`

**Transaction Revenue**

Optional

This argument specifies the total revenue associated with a transaction. This value should include any supplementary costs such as shipping or taxes.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tr**    | float      | 0             | *None*     | TRANSACTION         |

Example value: `15.47` Example usage: `tr=15.47`

**Transaction Shipping**

Optional

This argument specifies the total shipping costs of a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ts**    | float      | 0             | *None*     | TRANSACTION         |

Example value: `3.50` Example usage: `ts=3.50`

**Transaction Tax**

Optional

This argument specifies the total tax collected in a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tt**    | float      | 0             | *None*     | TRANSACTION         |

Example value: `2.60` Example usage: `tt=2.60`

**Transaction Currency**

Optional

When present, this argument indicates the local currency for all the currency values in a transaction. The value should be a valid ISO 4217 currency code.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tc**    | string     | *None*        | 500 Bytes  | TRANSACTION         |

Example value: `EUR` Example usage: `tc=EUR`

**Transaction Coupon Code**

Optional

This argument refers to the coupon or discount code associated with a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tcc**   | string     | *None*        | 10 Bytes   | TRANSACTION         |

Example value: `coupon` Example usage: `tcc=coupon`

**Payment Method**

Optional

This argument indicates the payment method used in a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **pm**    | string     | *None*        | 10 Bytes   | TRANSACTION         |

Example value: `Paypal` Example usage: `pm="Paypal"`

**Shipping Method**

Optional

This argument indicates the shipping method used in a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **sm**    | string     | *None*        | 10 Bytes   | TRANSACTION         |

Example value: `express` Example usage: `sm="express"`

**Item Count Number**

Optional

This argument indicates the number of items included in a transaction.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **icn**   | int        | *None*        | *None*     | TRANSACTION         |

Example value: `12` Example usage: `icn=12`

**Implementation example**

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "icn": 12,
  "pm": "Paypal",
  "sm": "Fedex",
  "t": "TRANSACTION",
  "ta": "Purchase",
  "tc": "EUR",
  "tcc": "Coupon",
  "tid": "OD564",
  "tr": 15.47,
  "ts": 3.5,
  "tt": 2.6,
  "vid": "18100217380532936",
  "ds": "APP"
}'
```

**Item**

Items usually represent individual products. `ITEM` hits must be associated with a `TRANSACTION`.

Make sure the \`TRANSACTION\` hit that corresponds to the \`tid\` argument is triggered \*\*before\*\* the \`ITEM\` hit, otherwise the hits will not be consolidated.

**Arguments**

* An `ITEM` hit must implement the **requiredCommon Arguments**
* Common argument **Type** (`t`) must be set to `ITEM`.

**Transaction ID**

**Required** for `ITEM` and `TRANSACTION` hit types

This argument allows an item to be linked to a transaction with a matching Transaction ID `tid`.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **tid**   | string     | *None*        | 500 Bytes  | TRANSACTION, ITEM   |

Example value: `OD564` Example usage: `tid=OD564`

**Item Name**

**Required**

This argument specifies the name of an item.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **in**    | string     | *None*        | 500 Bytes  | ITEM                |

Example value: `Shoe` Example usage: `in=Shoe`

**Item Code**

**Required**

This argument specifies an item's SKU or product bar code.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ic**    | string     | *None*        | 500 Bytes  | ITEM                |

Example value: `SKU47` Example usage: `ic=SKU47`

**Item Price**

Optional

This argument specifies the price for a single unit of an item.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **ip**    | float      | 0             | *None*     | ITEM                |

Example value: `3.50` Example usage: `ip=3.50`

**Item Quantity**

Optional

This argument indicates the number of units of an item that are purchased.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **iq**    | integer    | 0             | *None*     | ITEM                |

Example value: `4` Example usage: `iq=4`

**Item Category**

Optional

This argument specifies the product category that an item belongs to.

| Parameter | Value Type | Default Value | Max Length | Supported hit types |
| --------- | ---------- | ------------- | ---------- | ------------------- |
| **iv**    | string     | *None*        | 500 Bytes  | ITEM                |

Example value: `Blue` Example usage: `iv=Blue`

**Implementation example**

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ic": "SKU47",
  "in": "Shoe",
  "ip": 3.5,
  "iq": 4,
  "iv": "Blue",
  "t": "ITEM",
  "tid": "OD564",
  "vid": "18100217380532936",
  "ds": "APP"
}'
```

#### Experience Continuity

In case you're using Experience Continuity with the Decision API only and you're directly doing POST call to the Universal Collect, you have to pass the `cuid` parameter corresponding to the authenticated visitorId.

**Implementation example**

Make sure that the Experience Continuity option is enabled on the FE\&R platform before using those methods.

> 📘 Previous endpoint note
>
> The previous endpoint is still active: <https://ariane.abtasty.com>

```shell
curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "https://www.abtasty.com",
  "t": "PAGEVIEW",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds":"APP"
}'
```

```shell
curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "HomeScreen",
  "t": "SCREENVIEW",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds":"APP"
}'
```

```shell
curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ea": "newsletterSubscription",
  "ec": "Action Tracking",
  "el": "optin",
  "ev": 1,
  "t": "EVENT",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'
```

```shell
curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "icn": 12,
  "pm": "Paypal",
  "sm": "Fedex",
  "t": "TRANSACTION",
  "ta": "Purchase",
  "tc": "EUR",
  "tcc": "Coupon",
  "tid": "OD564",
  "tr": 15.47,
  "ts": 3.5,
  "tt": 2.6,
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'
```

```shell
curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ic": "SKU47",
  "in": "Shoe",
  "ip": 3.5,
  "iq": 4,
  "iv": "Blue",
  "t": "ITEM",
  "tid": "OD564",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'
```

#### Hit validation

You can use this tool to help you validate the hits you send to ABTasty