# Activities analytics

Data coming into your datamart is stored in a multi-model database, optimizing it for different usages. **To display performance analytics for elements like session duration, conversions,** and **funnel, the platform duplicates some** [**user activities**](https://developer.mediarithmics.io/user-points/user-activities) **and information and optimizes them.**

{% hint style="success" %}
For that purpose, it is important that you use [predefined event names and properties](https://developer.mediarithmics.io/user-points/user-activities#predefined-event-names) when possible. Custom events won't be taken into account when calculating metrics. For example, don't create `order` events when tracking an e-commerce site, but the [predefined](https://developer.mediarithmics.io/data-streams/real-time-user-tracking/web-events#transaction-confirmation-page) `$transaction_confirmed` [event](https://developer.mediarithmics.io/data-streams/real-time-user-tracking/web-events#transaction-confirmation-page). `$transaction_confirmed` events are used when calculating conversions and amounts but not `order` events.
{% endhint %}

Here is a sample event that can be used in analytics:

```javascript
{
    "$ts": 3489009384393,
    "$event_name": "$transaction_confirmed", // Conversion detected
    "$properties": {
        "$items": [
            {
                 "$id": "product_ID", // Used to filter in funnel analytics
                 "$qty": 20, // Used for conversion amounts
                 "$price": 102.8, // Used or conversion amounts
                 "$brand": "Apple" // Used to filter in funnel analytics
                 "$category1": "Category 1", // Used to filter in funnel analytics
                 "$category2": "Category 2", // Used to filter in funnel analytics
                 "$category3": "Category 3", // Used to filter in funnel analytics
                 "$category4": "Category 4" // Used to filter in funnel analytics
             },
             {
                 "$id": "product_ID2",
                 "$qty": 12,
                 "$price": 3.4,
                 "$brand": "Microsoft"
             }
        ],
        "$currency": "EUR"
    }
}
```

The list of predefined events that are used in analytics are as follows.

| Event name              | Usage                                                                                                                                            | Important properties                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| $transaction\_confirmed | <p>Home dashboards (<em>E-Commerce Engagement</em>)<br></p><p>Segment dashboards (<em>E-Commerce Engagement</em>)<br></p><p>Funnel Analytics</p> | <p><code>$items</code> : list of products in the transaction<br></p><p><code>$items.$qty</code> : for the conversion amounts<br></p><p><code>$items.$price</code>: for the conversion amounts<br></p><p><code>$items.$id</code> : for the product IDs in funnel analytics<br></p><p><code>$items.$brand</code>: for the brand filter in funnel analytics<br></p><p><code>$items.$category1</code>, <code>$items.$category2</code>, <code>$items.$category3</code> and <code>$items.$category4</code> : for the categorization in funnel analytics</p> |
| $item\_view             | Funnel Analytics                                                                                                                                 | <p><code>$items</code> : contains only one product<br></p><p><code>$items.$price</code>: for the conversion amounts<br></p><p><code>$items.$id</code> : for the product IDs in funnel analytics<br></p><p><code>$items.$brand</code>: for the brand filter in funnel analytics<br></p><p><code>$items.$category1</code>, <code>$items.$category2</code>, <code>$items.$category3</code> and <code>$items.$category4</code> : for the categorization in funnel analytics</p>                                                                           |
| $basket\_view           | Funnel Analytics                                                                                                                                 | <p><code>$items</code> : list of products in the basket<br></p><p><code>$items.$qty</code> : for the conversion amounts<br></p><p><code>$items.$price</code>: for the conversion amounts<br></p><p><code>$items.$id</code> : for the product IDs in funnel analytics<br></p><p><code>$items.$brand</code>: for the brand filter in funnel analytics<br></p><p><code>$items.$category1</code>, <code>$items.$category2</code>, <code>$items.$category3</code> and <code>$items.$category4</code> : for the categorization in funnel analytics</p>      |

## Activities analytics data retention

Activities analytics data is kept **4 month** in order to optimize performances.

## Transforming important events into your custom events

While it is better to use predefined events when possible, it isn't always the best solution for you. To keep having analytics correctly stored, you can transform your custom events to predefined ones.

{% hint style="info" %}
Only events coming into the datamart after an event transformation has been defined will be transformed.

Those transformations don't transform user activities and events anywhere else. You should use [activity analyzers](https://developer.mediarithmics.io/data-streams/data-ingestion/real-time-user-tracking/activity-analyzers) to transform them everywhere.
{% endhint %}

### Event transformations

An event transformation is linked to a datamart. Here is a sample transformation:

```javascript
{
    "id": 15, // Read only
    "datamart_id": "3333", // Read only
    "created_ts": <>, // Read only
    "created_by": <>, // Read only
    "last_modified_by": <>, // Read only
    "last_modified_ts": <>, // Read only

    "channel_id": "8888",
    "source_event_name": "order",
    "target_event_name": "$transaction_confirmed",
    "mapping_id": 15
}
```

| Property            | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| datamart\_id        | Integer | The ID of the datamart where the transformation is applied                                                                                                                                                                                                                                                                                                                                         |
| channel\_id         | Integer | The ID of the channel where the transformation is applied                                                                                                                                                                                                                                                                                                                                          |
| source\_event\_name | String  | The name of your custom event you wish to transform into a predefined event                                                                                                                                                                                                                                                                                                                        |
| target\_event\_name | String  | <p>The name of the predefined event it is transformed into. Allowed values are :</p><ul><li><code>$transaction\_confirmed</code></li><li><code>$item\_view</code></li><li><code>$basket\_view</code></li><li><code>$list\_item\_view</code></li></ul><p>To learn about predefined events, see <a href="../../../user-points/user-activities#predefined-event-names">Predefined event names</a></p> |
| mapping\_id         | Integer | The ID of the [Property mapping](#property-mapping) to apply when transforming the event                                                                                                                                                                                                                                                                                                           |

### Property mappings

Event transformations use property mappings to choose which property in your custom event becomes which property in the predefined event.

Here is a sample property mapping to start with for `$transaction_confirmed` events.

```javascript
// Comments are here to help you understand, 
// remove them before uploading mappings as they are not accepted in JSON
{
  "id": 17, // Read only
  "created_by": <>, // Read only
  "created_ts": <>, // Read only
  "mapping": {
    "values": [
      {
          // Maps $properties.order.order_products[] to $items[]
           "target_attribute_name": "$items",
           "source_attribute_path": {
               "attribute_name": "$properties",
               "sub_path": {
                   "attribute_name": "order",
                   "sub_path": {
                        "attribute_name": "order_products"
                   }
               }
           },
           // Alternative : mapping directly $properties if there are no multiple
           // elements in the event. It will be treated as an array of only one item
           "target_attribute_name": "$items",
           "source_attribute_path": {
                "attribute_name": "$properties"
           },
           
           // Maps $properties.order.order_products.xxx to $items.xxx
           // You can't use other target attributes than the ones 
           // in this example.
           // But they are not all mandatory : a non used target 
           // attribute will use the default value
           "children": [
               // $properties.order.order_products.product.id
               // becomes $items.$id
               // to be used by analytics database
               {
                   "target_attribute_name": "$id",
                   "source_attribute_path": {
                     "attribute_name": "product",
                     "sub_path": {
                        "attribute_name": "id"
                     }
                   }
               },
               // $properties.order.order_products.qty
               // becomes $items.$qty
               // to be used by analytics database
               {
                   "target_attribute_name": "$qty",
                   "source_attribute_path": {
                     "attribute_name": "qty"
                   }
               },
               {
                   "target_attribute_name": "$price",
                   "source_attribute_path": {
                     "attribute_name": "price"
                   }
               },
               {
                   "target_attribute_name": "$ean",
                   "source_attribute_path": {
                     "attribute_name": "ean",
                   }
               },
               {
                   "target_attribute_name": "$brand",
                   "source_attribute_path": {
                     "attribute_name": "brand",
                   }
               },
               {
                   "target_attribute_name": "$category1",
                   "source_attribute_path": {
                     "attribute_name": "cat1"
                   }
               },
               {
                   // In this example $category2 will be 
                   // event.$event_name instead of 
                   // $properties.order.order_products[].$event_name
                   // thanks to absolute_path
                   "target_attribute_name": "$category2",
                   "source_attribute_path": {
                     "absolute_path": true,
                     "attribute_name": "$event_name",
                   }
               },
               {
                   "target_attribute_name": "$category3",
                   "source_attribute_path": {
                     "attribute_name": "cat3"
                   }
               },
                {
                   "target_attribute_name": "$category4",
                   "source_attribute_path": {
                     "attribute_name": "cat4"
                   }
               }
           ]
       }
    ]
  }
}
```

{% hint style="warning" %}
Map events JSON as it is stored in the database and visible in user's timelines (post [activity analyzers](https://developer.mediarithmics.io/data-streams/data-ingestion/real-time-user-tracking/activity-analyzers)).
{% endhint %}

## Get existing transformations

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation`

#### Path Parameters

| Name       | Type    | Description     |
| ---------- | ------- | --------------- |
| datamartId | integer | The datamart ID |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": [
        {
          "datamart_id": ":datamartId",
          "channel_id": "8888",
          "source_event_name": "order",
          "target_event_name": "$transaction_confirmed",
          "mapping_id": xxx
        },
        {
            ...
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Create an event transformation

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation`

#### Path Parameters

| Name       | Type    | Description     |
| ---------- | ------- | --------------- |
| datamartId | integer | The datamart ID |

#### Request Body

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| Body | string | The event transformation object |

{% tabs %}
{% tab title="200 " %}

```javascript
```

{% endtab %}
{% endtabs %}

## Update an event transformation

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation/:transformationId`

#### Path Parameters

| Name             | Type    | Description           |
| ---------------- | ------- | --------------------- |
| transformationId | integer | The transformation ID |
| datamartId       | integer | The datamart ID       |

#### Request Body

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| Body | string | The event transformation object |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Remove an event transformation

<mark style="color:red;">`DELETE`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation/:transformationId`

#### Path Parameters

| Name             | Type    | Description           |
| ---------------- | ------- | --------------------- |
| transformationId | integer | The transformation ID |
| datamartId       | integer | The datamart ID       |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get property mappings

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping`

#### Path Parameters

| Name       | Type    | Description     |
| ---------- | ------- | --------------- |
| datamartId | integer | The datamart ID |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Create property mappings

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping`

#### Path Parameters

| Name       | Type    | Description     |
| ---------- | ------- | --------------- |
| datamartId | integer | The datamart ID |

#### Request Body

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| Body | object | The property mapping object |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "ok",
  "data": {
      id: 17,
      created_by: <>
      ...
  }
}
```

{% endtab %}
{% endtabs %}

## Delete property mappings

<mark style="color:red;">`DELETE`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping/:mappingId`

#### Path Parameters

| Name       | Type    | Description     |
| ---------- | ------- | --------------- |
| mappingId  | integer | The mapping ID  |
| datamartId | integer | The datamart ID |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok"
}
```

{% endtab %}

{% tab title="400 " %}

```javascript
{
    "status": "error",
    "error": "Deleting a property mapping used in a transformation is forbidden",
    "error_code": "BAD_REQUEST_DATA",
    "error_id": "9460be23-0f80-4acb-9a33-dd8a1c5d08a9"
}
```

{% endtab %}
{% endtabs %}