Activity object

Understand the activity object structure for event tracking: action, target, user, source ID, and metadata. Includes built-in actions and metadata recommendations for XO and FHR.

The activity object contains essential data for event tracking, comprising five unique properties, as shown below:

{
    "action": "action",
    "target": {},
    "user": {},
    "sourceId": "source-id",
    "metadata": {}
}

Action

The action property is a string describing the action performed by the user (i.e. the event the user has triggered).

Our system supports five built-in actions:

• View

• Click

• Add-to-cart

• Remove-from-cart

• Purchase

If you would like to track additional actions, you can do so using custom actions.

Target

The target property is an object detailing the target the action was performed on (i.e. the subject of the event).

Targets are action specific (e.g. product id, path to page etc.).

User

The user property is an object detailing the user characteristics you are tracking.

You can find more information on the user object in the Identities section.

Source ID

The source ID links an activity to a specific context or origin. When a user takes an action, the source ID helps trace it back to a particular touchpoint, such as a page, a search term, or a specific marketing campaign.

The source ID property is a string describing the ID that associates the FHR or XO response with the event.

For activities linked to a FHR or XO context the source ID must correspond to the response ID.

For example: If a user clicks on a product recommendation, the source ID might link that action to the specific recommendation engine or search query that suggested the product.

Response object example: XO

Below you can find an example of an XO response object. The response ID, that you should use as source ID for tracking, corresponds to the id in the response object.

{
  "id": "",
  "recommendations": [
    {
      "id": "goomazon-oklexa",
      "strategy": "local-mostPopular",
      "score": 1,
      "distribution": 0,
      "product": {
        "_id": {
          "original_id": "goomazon-oklexa",
          "tenant": "615b225f20b888ce230ce617",
          "kind": "product"
        },
        "type": "product",
        "context": "default",
        "version": 0,
        "title": "Goomazon Oklexa SP93",
        "recommended": true,
        "scores": {
          "BestMatch": 1,
          "BestSeller": 0,
          "price_ascending": 0,
          "price_descending": 0
        },
        "metadata": {
          "updated": "1701820981438"
        },
        "photo": "https://zzfz-003.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-electronics-m-catalog/default/dw6891a144/images/large/SmartLiving/test_speaker_2.jpeg",
        "categories": [
          "SmartLiving"
        ],
        "brand": "SmartLiving",
        "classification-category": "tools",
        "short_description": "The Oklexa SP93 takes the concept of smart speakers to a whole new level! It will do exactly what you expect to do within its configured parameters. By analyzing the volume and pitch of your voice, Oklexa also takes into account visual data, (it's connected to all the cameras in your house), and can literally read your mind! Science!"
      }
    },
    {
      "id": "detector-brn5",
      "strategy": "local-mostPopular",
      "score": 1,
      "distribution": 0,
      "product": {
        "_id": {
          "original_id": "detector-brn5",
          "tenant": "615b225f20b888ce230ce617",
          "kind": "product"
        },
        "type": "product",
        "context": "default",
        "version": 0,
        "title": "Smoke detector BRN5",
        "recommended": true,
        "scores": {
          "BestMatch": 1,
          "BestSeller": 0,
          "price_ascending": 0,
          "price_descending": 0
        },
        "metadata": {
          "updated": "1701820981436"
        },
        "photo": "https://zzfz-003.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-electronics-m-catalog/default/dw6891a144/images/large/SmartLiving/BRN5.jpg",
        "categories": [
          "SmartLiving"
        ],
        "brand": "SmartLiving",
        "classification-category": "tools",
        "short_description": "The BRN5 is an intelligent smoke detector. The main purpose is of course to inform you via mobile devices when smoke production is detected. Built-in Alexa support also allows you to control other aspects of your smart home."
      }
    },
    {
      "id": "d1r7-tr4p",
      "strategy": "local-mostPopular",
      "score": 1,
      "distribution": 0,
      "product": {
        "_id": {
          "original_id": "d1r7-tr4p",
          "tenant": "615b225f20b888ce230ce617",
          "kind": "product"
        },
        "type": "product",
        "context": "default",
        "version": 0,
        "title": "Cleaning Robot D1R7-TR4P",
        "recommended": true,
        "scores": {
          "BestMatch": 1,
          "BestSeller": 0,
          "price_ascending": 0,
          "price_descending": 0
        },
        "metadata": {
          "updated": "1701820981472"
        },
        "photo": "https://zzfz-003.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-electronics-m-catalog/default/dw6891a144/images/large/SmartLiving/staubsauger-schwarz.jpg",
        "categories": [
          "SmartLiving"
        ],
        "brand": "SmartLiving",
        "classification-category": "tools",
        "short_description": "The D1R7-TR4P cleaning robot helps you keep your house clean. Due to its low overall height and flexible design, no place is neglected."
      }
    }
  ],
  "pagination": {
    "total": 3
  },
  "widget": {
    "title": "",
    "attributes": {

    },
    "minResults": -1,
    "distributions": [
      {
        "attributes": {

        }
      }
    ]
  }
}

Response object example: FHR

You can find various examples for the FHR response object here. The response ID, that you should use as source ID for tracking, corresponds to the rid in the FHR response object.

To ensure accurate reporting, use the FHR or XO response ID exclusively for actions related to the features provided by that specific response.

Avoid including a source ID that is unrelated to the action.

Handling infinite scroll

• First response: The initial set of results corresponds to the first response. Activities performed on these products should use the source ID from this response.

• Subsequent responses: When a user scrolls and additional content is loaded (e.g., a second page of results), the new products should reference the source ID from the corresponding response.

Pagination events are not tracked. If you would like to track pagination events, request a custom action.

Metadata

The metadata property is an object detailing additional data related to the action that you are tracking, for example:

• Locale (language and region)

• Device type (mobile, desktop)

• Quantity

• Price

When using XO, we recommend you include the metadata.context field. This is a string field describing the context that the event took place in. Values for this field are user defined and can take any format (e.g. "sale", "french", "1").

When using FHR, we recommend you include the metadata.locale field. This is a string field describing the locale that the event took place in. Values for this field must adhere to the following format: xx_YY (e.g. "en_GB", "en_US", "fr_FR").

Additional fields in the metadata object are action specific and may be required.