Salesforce Docs Portal

Einstein Recommendation Collect Tracking API

Overview

You can implement Einstein Recommendation Collect Tracking calls by making a POST request to the appropriate URL.

When you issue your first request to the Collect API, the JSON response includes user_id and session_id values. You can use these values in subsequent calls. Include these parameters at the same level as the payload, as shown in this basic example.

https://MID.collect.igodigital.com/c2/MID/track_page_view.json
{
    "payload": {
        "title": "INSERT_PAGE_TITLE",
        "url": "INSERT_PAGE_URL",
        "referrer": "INSERT_REFERRER_URL",
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Keep these considerations in mind when you use the Collect API.

  • The Collect API only accepts requests that use the Content-Type: application/json header.
  • You can issue requests to HTTP or HTTPS endpoints.
  • An API key is only required when you issue a request that creates or updates product or catalog data via Streaming Updates.

Parameter Definitions

MID

A unique client identifier. This value is typically the MID associated with the Business Unit.

title

The title of the page that the user is viewing.

url

The URL or path to the application page.

referrer

The previous page or referring URL for the application.

email

Include this value if the site is tracking the user’s email address or other identifier. For example, on pages such as newsletter signup pages or order confirmation pages, you typically have the user’s email address. The Collect API uses email addresses to merge duplicate values.

user_id

The user_id value returned from the first Collect API call for an individual user. Use this value for all future API calls for that individual.

note: When you start a new session, a new profile is created. At the end of the session, if there are multiple records that share a common email address, those records are merged.

session_id

The session_id value returned from the first Collect API call for the user’s current session. Use this value for all API calls in an individual’s session.

Item Detail View Collect Example

This example shows how to implement an observation script that tracks views for a specific item detail page.

https://MID.collect.igodigital.com/c2/MID/track_page_view.json
{
    "payload": {
        "item": "INSERT_ITEM",
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        },
    "user_id": "",
    "session_id": ""
    }
}

Additional Parameter Definitions

item

Represents the item that’s being displayed to the customer, such as on an item detail page.

Real-Time Rating Collect Example

This example implements an observation script that tracks when a user submits a rating for an item.

https://MID.collect.igodigital.com/c2/MID/track_rating.json?
{
    "payload": {
        "item": "INSERT_ITEM",
        "rating": "INSERT_ITEM_RATING",
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

rating

Populate this parameter with a numerical representation of the rating that the user submitted. You must pass this value in the same call for the rating to be properly recorded.

Cart Collect Example

This example implements an observation script that tracks a snapshot of the items in the user’s cart.

https://MID.collect.igodigital.com/c2/MID/track_cart.json?
{
    "payload": {
        "cart": [
            {
                "item": "INSERT_ITEM",
                "quantity": "INSERT_QUANTITY",
                "price": "INSERT_ITEM_PRICE",
                "unique_id": "INSERT_UNIQUE_ID"
            },
            {
                "item": "INSERT_ITEM",
                "quantity": "INSERT_QUANTITY",
                "price": "INSERT_ITEM_PRICE",
                "unique_id": "INSERT_UNIQUE_ID"
            }
        ],
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

item

Set this parameter to a unique identifier for the item in the user’s cart.

quantity

Set this parameter to the quantity of the item in the user’s cart.

price

Set this parameter to the per-unit price of the item in the user’s cart.

Clear Cart Collect Example

This example implements an observation script that indicates when the user has emptied their shopping cart.

https://MID.collect.igodigital.com/c2/MID/track_cart.json?
{
    "payload": {
        "cart": {
            "clear_cart": true
        },
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

clear_cart

When true, indicates that the user has removed all items from their shopping cart.

Conversion Collect Example

This example implements an observation script that tracks a conversion event.

https://MID.collect.igodigital.com/c2/MID/track_conversion.json?
{
    "payload": {
        "cart": [
            {
                "item": "INSERT_ITEM",
                "quantity": "INSERT_QUANTITY",
                "price": "INSERT_ITEM_PRICE"
            },
            {
                "item": "INSERT_ITEM",
                "quantity": "INSERT_QUANTITY",
                "price": "INSERT_ITEM_PRICE"
            }
        ],
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        },
        "order_number": "INSERT_ORDER_NUMBER",
        "shipping": "INSERT_SHIPPING_CHARGE",
        "discount": "INSERT_DISCOUNT_AMOUNT"
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

order_number

Set this parameter to the order number after a conversion event occurs.

shipping

This optional parameter specifies the shipping charge associated with the user’s order.

discount

This optional parameter specifies the discount amount that was applied to the user’s order.

Search Collect Example

This example implements an observation script that tracks page views for a specific item detail page.

https://MID.collect.igodigital.com/c2/MID/track_page_view.json?
{
    "payload": {
        "search": "INSERT_SEARCH_TERM",
        "title": "INSERT_PAGE_TITLE",
        "url": "INSERT_PAGE_URL",
        "referrer": "INSERT_REFERRER_URL",
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

search

Set this parameter to include the internal or external search keywords that led to the page view event.

Category Page Collect Example

This example implements an observation script that tracks page views for a specific item detail page.

https://MID.collect.igodigital.com/c2/MID/track_page_view.json?
{
    "payload": {
        "category": "INSERT_CATEGORY_NAME",
        "title": "INSERT_PAGE_TITLE",
        "url": "INSERT_PAGE_URL",
        "referrer": "INSERT_REFERRER_URL",
        "user_info": {
            "email": "INSERT_EMAIL_OR_SUBSCRIBER_ID"
        }
    },
    "user_id": "",
    "session_id": ""
}

Additional Parameter Definitions

category

Set this parameter for each category and subcategory page.

Example Response

{
user_id: "5fb6fd46-7fd6-11e4-93db-123139337486"
session_id: "5fb70c14-7fd6-11e4-93db-123139337486"
}

Create or Update a Single Item Example

This code sample implements streaming updates to a single item in your catalog.

Replace the placeholder values with dynamic code to get the appropriate value for the item. Acceptable values for item_type are content, product, or banner. If your request doesn’t specify a value for item_type, or it provides a value that the API doesn’t recognize, the API uses a default value of content.

https://MID.collect.igodigital.com/c2/MID/update_item_secure.json?api_key=<api_key>
{"payload":
	{
		"item": "INSERT_ITEM",
		"unique_id": "INSERT_UNIQUE_ITEM_ID",
		"item_type": "INSERT_ITEM_TYPE",
		"name": "INSERT_ITEM_NAME_OR_TITLE",
		"INSERT_ATTRIBUTE_NAME": "INSERT_ATTRIBUTE_VALUE"
	}
}

Create or Update Multiple Items Example

This code sample updates multiple items in your catalog.

Replace the placeholder values with dynamic code to get the appropriate value for the item. Acceptable values for item_type are content, product, or banner. If your request doesn’t specify a value for item_type, or it provides a value that the API doesn’t recognize, the API uses a default value of content.

https://MID.collect.igodigital.com/c2/MID/update_item_secure.json?api_key=<api_key>
{"payload":
   [
      {
	   "item": "INSERT_ITEM",
	   "item_type": "INSERT_ITEM_TYPE",
	   "name": "INSERT_ITEM_NAME_OR_TITLE",
	   "INSERT_ATTRIBUTE_NAME": "INSERT_ATTRIBUTE_VALUE"
      },
      {
	   "item": "INSERT_ITEM",
	   "item_type": "INSERT_ITEM_TYPE",
	   "name": "INSERT_ITEM_NAME_OR_TITLE",
	   "INSERT_ATTRIBUTE_NAME": "INSERT_ATTRIBUTE_VALUE"
      }
   ]
}

Attributes can include multiple values. To specify an attribute that has multiple values, place the values in a string array, as shown in this code sample.

{
    "payload": {
        "item": "INSERT_ITEM",
        "item_type": "INSERT_ITEM_TYPE",
        "name": "INSERT_ITEM_NAME_OR_TITLE",
        "INSERT_ATTRIBUTE_NAME": [
            "INSERT_ATTRIBUTE_VALUE1",
            "INSERT_ATTRIBUTE_VALUE2",
            "INSERT_ATTRIBUTE_VALUE3"
        ]
    }
}

Update Item Availability Example

You can use the API to update the availability of an item in your catalog. Set the value of sku to a unique ID for the item that you’re modifying. The availability parameter indicates whether the product is available. Acceptable values for availability are Y or N.

https://MID.collect.igodigital.com/api/update_product?key=<API_KEY>&sku=INSERT_UNIQUE_ITEM_ID&availability=N