To import behavioral signals generated by external libraries to Connect, make sure they meet the predefined format. This is the same format that native signals from the Connect library follow.
- If you are importing signals from a file, see the JSON examples.
- For real-time import via the API, see
signalContent
in the GraphQL version.
Add-to-cart signal
This signal is triggered when a visitor adds products to their cart.
The add-to-cart signal is included into all Connect subscriptions (Pro, Premium and Ultimate).
{
"signalType": "addToCart",
"name": "Add product to cart in online store",
"category": "Behavior",
"currency": "USD",
"productId": "AC-PNT-WHT-SM",
"productName": "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz",
"effect": "positive",
"itemQuantity": 2,
"unitPrice": 39.99,
"discount": 7,
"productCategory": "Painting & Decorating / Paint",
"productUrls": ["https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint", "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-interior-satin-paint"]
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "addToCart"
name: "Add product to cart in online store"
category: "Behavior"
currency: "USD"
productId: "AC-PNT-WHT-SM"
productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
effect: "positive"
itemQuantity: 2
unitPrice: 39.99
discount: 7
productCategory: "Painting & Decorating / Paint"
productUrls: [
"https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"
"https://www.example.com/painting-and-decorating/must-haves/awesome-colors-interior-satin-paint"
]
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
currency | String. Valid values - ISO 4217 currency codes. | The currency in which the price of the product is represented |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. We suggest sending positive for all add-to-cart signals. |
itemQuantity | Number | The quantity of the product added to the cart |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
productId | String | The identifier of the product. It may coincide with the SKU. |
productName | String | The name of the product |
signalType | String. Valid value -addToCart . | The type of signal to import |
unitPrice | Number | The unit price of the product |
Optional fields
Field | Values | Definition |
---|---|---|
discount | Number | Discount from the original price. If the exact amount is not provided, you could calculate the difference between the original and the current price. |
imageUrls | Array of strings | The URLs of product images |
productCategory | String | The category that the product falls in based on the product catalog |
productDescription | String | The description of the product |
productUrls | Array of strings | The URLs of product pages |
promotionId | String | For the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it. |
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
shoppingCartUrl | String | The URL of the shopping cart that the add-to-carts are contributing to |
virtualCategory | String | The category is based on how the visitor got to the page, for example from "New arrivals" or "Sale". |
Error signal
This signal is sent when a user encounters an error on your site. We suggest focusing on payment, promo code, and account registration errors - anything that leads users away from the happy path and results in lost sales opportunities.
Important
The error signal doesn't replace an error monitoring solution. Its aim is to let marketers segment out users who have ran into issues during the order process. Also, marketers can set up the delivery of personalized messages triggered by the signal.
The error signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "error",
"name": "Shopping cart error",
"category": "Behavior",
"errorIdentifier": "promoCode",
"errorText": "This promo code is invalid.",
"errorType": "user",
"effect": "negative"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "error"
name: "Shopping cart error"
category: "Behavior"
errorIdentifier: "promoCode"
errorText: "This promo code is invalid."
errorType: "user"
effect: "negative"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. We suggest sending negative for all error signals. |
errorIdentifier | String | An identifier assigned to the error. Example: "promoCode". |
errorText | String | The content of the error message received |
errorType | String. Valid values: - application - user | Application errors are server-side or system errors. User errors occur when user input doesn't pass client- or server-side validation. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
signalType | String. Valid value -error . | The type of signal to import |
Optional fields
Field | Values | Definition |
---|---|---|
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
Identification signal
This signal captures visitors' emails or client/contact IDs as they are browsing your website.
The identification signal is supported by all types of Connect subscriptions (Pro, Premium and Ultimate).
{
"signalType": "identification",
"name": "Identification from login",
"category": "Behavior",
"identifierName": "email",
"identifierValue": "[email protected]",
"identificationFromLogin": true,
"effect": "positive"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "identification"
name: "Identification from login"
category: "Behavior"
identifierName: "email"
identifierValue: "[email protected]"
identificationFromLogin: true
effect: "positive"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal. |
effect | String. Valid values: - negative - positive | Specify how to interpret the signal. The value will be used for engagement index scoring. |
identifierName | String. Valid values: - email - sms - contactKey | The type of the identifier to use for the signal |
identifierValue | String | The contact information associated with a visitor. The type of identifier depends on the identifierName value. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
signalType | String. Valid value -identification . | The type of signal to import |
Optional fields
Field | Values | Definition |
---|---|---|
identificationFromLogin | Boolean | If the identifierValue derives from user authentication, set the value to true . If it is taken from a cookie or a query string, use false .This lets you separate sessions where visitors identified themselves explicitly or implicitly. |
On-site search signal
This signal records the search terms that your website visitors use and the number of results they get.
The on-site search signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "onSiteSearch",
"name": "Product search in online store",
"category": "Behavior",
"numberOfResults": 9,
"searchTerm": "paint with satin finish",
"effect": "positive"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "onSiteSearch"
name: "Product search in online store"
category: "Behavior"
numberOfResults: 9
searchTerm: "paint with satin finish"
effect: "positive"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. If a search term returns results, send positive as the value. If there are no results, send negative . |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
numberOfResults | Number | The number of results that matched the search term |
searchTerm | String | The word or phrase that the visitor searched for |
signalType | String. Valid value -onSiteSearch . | The type of signal to import |
Optional fields
Field | Values | Definition |
---|---|---|
signalCustomAttributes | Array | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
Order signal
This signal comes each time a contact places an order on your website. For each order, there is the total amount and a detailed breakdown by the product.
The order signal is supported by all types of Connect subscriptions (Pro, Premium and Ultimate).
{
"signalType": "order",
"name": "Online store order",
"category": "Behavior",
"currency": "USD",
"effect": "positive",
"orderDiscount": 0,
"orderId": "02937-2025-XIA",
"orderSubtotal": 89.47,
"orderShippingHandling": 15.45,
"orderValue": 98.44,
"orderTax": 4.47,
"orderedItems": [
{
"productId": "AC-PNT-WHT-SM",
"productName": "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz",
"quantity": 2,
"unitPrice": 39.99,
"currency": "USD",
"discount": 7,
"productCategory": "Painting & Decorating / Paint",
"productUrls": ["https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint", "https://www.example.com/painting-and-decorating/bestsellers/awesome-colors-interior-satin-paint"],
"shoppingCartUrl": "https://www.example.com/cart",
"virtualCategory": "Sale"
},
{
"productId": "AC-DBL-BRSH-6",
"productName": "AWESOME COLORS Double Thick Chip Paint Brush",
"quantity": 1,
"unitPrice": 9.49,
"currency": "USD",
"discount": 0,
"productCategory": "Painting & Decorating / Tools",
"productUrls": ["https://www.example.com/painting-and-decorating/tools/awesome-colors-double-brush", "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-double-brush"],
"shoppingCartUrl": "https://www.example.com/cart",
"virtualCategory": ""
}
]
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "order"
name: "Online store order"
category: "Behavior"
currency: "USD"
effect: "positive"
orderDiscount: 0
orderId: "02937-2025-XIA"
orderSubtotal: 89.47
orderShippingHandling: 15.45
orderValue: 98.44
orderTax: 4.47
orderedItems: [
{
productId: "AC-PNT-WHT-SM"
productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
quantity: 2
unitPrice: 39.99
currency: "USD"
discount: 7
productCategory: "Painting & Decorating / Paint"
productUrls: [
"https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"
"https://www.example.com/painting-and-decorating/bestsellers/awesome-colors-interior-satin-paint"
]
shoppingCartUrl: "https://www.example.com/cart"
virtualCategory: "Sale"
}
{
productId: "AC-DBL-BRSH-6"
productName: "AWESOME COLORS Double Thick Chip Paint Brush"
quantity: 1
unitPrice: 9.49
currency: "USD"
discount: 0
productCategory: "Painting & Decorating / Tools"
productUrls: [
"https://www.example.com/painting-and-decorating/tools/awesome-colors-double-brush"
"https://www.example.com/painting-and-decorating/must-haves/awesome-colors-double-brush"
]
shoppingCartUrl: "https://www.example.com/cart"
virtualCategory: ""
}
]
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
currency | String. Valid values - ISO 4217 currency codes. | The currency used for the order |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. We suggest sending positive for all order signals. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
orderId | String | An identifier assigned to the order |
signalType | String. Valid value -order . | The type of signal to import |
Optional fields
Field | Values | Definition |
---|---|---|
orderDiscount | Number | Discount from the original price |
orderedItems | Array of objects | The list of products in the order. You need a separate object for each product, but not each instance of the same product - three identical items would result in one object, with a quantity of 3. |
orderShippingHandling | Number | The shipping and handling amount for the order |
orderSubtotal | Number | The subtotal amount for the order (net of discount) |
orderTax | Number | The tax amount for the order |
orderValue | Number | The total value of the order |
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
Fields supported by objects within the orderedItems
array
Field | Values | Required? | Definition |
---|---|---|---|
currency | String. Valid values - ISO 4217 currency codes. | Optional | The currency in which the price of the product is represented |
discount | Number | Optional | Discount from the original price |
imageUrls | Array of strings | Optional | The URLs of product images |
productCategory | String | Optional | The category that the product falls in based on the product catalog |
productDescription | String | Optional | The description of the product |
productId | String | Required | The identifier of the product. It may coincide with the SKU. |
productName | String | Required | The name of the product |
productUrls | Array of strings | Optional | The URLs of product pages |
promotionId | String | Optional | For the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it. |
quantity | Integer | Optional | The quantity of the product purchased |
shoppingCartUrl | String | Optional | The URL of the shopping cart |
unitPrice | Number | Required | Indicates how much the client paid for the product. |
virtualCategory | String | Optional | The category is based on how the visitor got to the product page, for example from "New arrivals" or "Sale". |
Page view signal
This signal registers page views as users are browsing your website.
The page view signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "pageView",
"name": "Page view from online store",
"category": "Behavior",
"url": "https://www.example.com/painting-and-decorating/tools/",
"pageCategory": "Painting & Decorating",
"effect": "positive"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "pageView"
name: "Page view from online store"
category: "Behavior"
url: "https://www.example.com/painting-and-decorating/tools/"
pageCategory: "Painting & Decorating"
effect: "positive"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
effect | String. Valid values: - negative - positive | Specify how to interpret the signal. The value will be used for engagement index scoring. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
signalType | String. Valid value - pageView . | The type of signal to import |
url | String | The URL of the page a user has opened |
Optional fields
Field | Values | Definition |
---|---|---|
pageCategory | String | The category that the page belongs to |
Product configuration signal
This signal tracks interactions on product pages (for example, selecting clothing size, checking FAQs or reviews, etc) that suggest customer engagement.
The product configuration signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "productConfiguration",
"name": "Product configuration from online store",
"category": "Behavior",
"currency": "USD",
"effect": "positive",
"productId": "AC-DBL-BRSH-6",
"productName": "AWESOME COLORS Double Thick Chip Paint Brush",
"configurationType": "Size selection"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "productConfiguration"
name: "Product configuration from online store"
category: "Behavior"
currency: "USD"
effect: "positive"
productId: "AC-DBL-BRSH-6"
productName: "AWESOME COLORS Double Thick Chip Paint Brush"
configurationType: "Size selection"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
configurationType | String | Assign a label to the interaction that happened. For example, you could name the product parameter (size, color, quantity) or identify the UI element (product option dropdown). |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. We suggest sending positive for all product configuration signals. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
productId | String | The identifier of the product. It may coincide with the SKU. |
productName | String | The name of the product |
signalType | String. Valid value -productConfiguration . | The type of signal you are importing |
Optional fields
Field | Values | Definition |
---|---|---|
currency | String. Valid values - ISO 4217 currency codes. | The currency in which the price of the product is represented |
inventoryQuantity | Integer | The number of units available |
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
Product view signal
This signal records user activity on product pages. It offers insights into how much attention each product and product category is getting. This is crucial for segmentation. Also, it becomes possible to tie product interest to identified visitors.
The product view signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "productView",
"name": "Product view from online store",
"category": "Behavior",
"currency": "USD",
"effect": "positive",
"productId": "AC-DBL-BRSH-6",
"productName": "AWESOME COLORS Double Thick Chip Paint Brush",
"unitPrice": 9.49,
"availability": "In Stock",
"brandName": "Awesome Colors",
"dateAdded": "2025-04-12 08:29:30.001",
"discount": 0,
"productCategory": "Painting & Decorating / Tools"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "productView"
name: "Product view from online store"
category: "Behavior"
currency: "USD"
effect: "positive"
productId: "AC-DBL-BRSH-6"
productName: "AWESOME COLORS Double Thick Chip Paint Brush"
unitPrice: 9.49
availability: "In Stock"
brandName: "Awesome Colors"
dateAdded: "2025-04-12 08:29:30.001"
discount: 0
productCategory: "Painting & Decorating / Tools"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
currency | String. Valid values - ISO 4217 currency codes. | The currency in which the price of the product is represented on the website |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. We suggest sending positive for all product views. |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
productId | String | The identifier of the product. It may coincide with the SKU. |
productName | String | The name of the product |
signalType | String. Valid value -productView . | The type of signal to import |
unitPrice | Number | The unit price of the product. If your product pages don't have prices (as is often the case in banking and insurance), use a placeholder. |
Optional fields
Field | Values | Definition |
---|---|---|
availability | String | Indicates if the product is available for purchase, for example "In Stock", "Out of Stock", "Back Order". |
brandName | String | The brand name of the product |
brandDescription | String | The description of the brand |
dateAdded | Combined date and time representation. Format: yyyy-MM-dd HH:mm:ss.SSS . | The date when the product was added to the product catalog |
discount | Number | Discount from the original price |
imageUrls | Array of strings | The URLs of product images |
inventoryQuantity | Integer | The number of units available |
model | String | The number or description of the model |
msrp | Number. Must be a decimal or float. | Suggested retail price or original price |
productCategory | String | The category that the product falls in based on the product catalog |
productDescription | String | The description of the product |
productRating | Number | The rating of the product |
productStatus | String | The current lifecycle state of the product (for example, "Active", "Discontinued", "Upcoming") |
productUrls | Array of strings | The URLs of product pages |
promotionId | String | For the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it. |
shoppingCartUrl | String | The URL of the shopping cart that the add-to-carts are contributing to |
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
sku | String | If the product ID is different from the SKU, add this field. |
virtualCategory | String | The category is based on how the visitor got to the page, for example from "New arrivals" or "Sale". |
Rich media interaction signal
This signal records user interactions with video and audio content on your website. The findings can be valuable for audience segmentation based on product (or product category) interest.
The rich media interaction signal is supported by Premium and Ultimate subscriptions.
{
"signalType": "richMediaInteraction",
"name": "Video review interaction in online store",
"category": "Behavior",
"mediaId": "jhaf6r76a",
"effect": "positive",
"interactionType": "launch",
"mediaCategory": "video",
"mediaName": "How I used AWESOME COLORS Brush to paint the ceiling",
"url": "https://www.example.com/opinions/painting-and-decorating/"
}
mutation {
createSignals(
signals: [
{
appKey: "00000000000xxx000000000xxxx"
identifiableAttributes: { contactKey: "AAUN-132417508" }
sessionId: "OOII97671461464332a1111"
signalContent: {
signalType: "richMediaInteraction"
name: "Video review interaction in online store"
category: "Behavior"
mediaId: "jhaf6r76a"
effect: "positive"
interactionType: "launch"
mediaCategory: "video"
mediaName: "How I used AWESOME COLORS Brush to paint the ceiling"
url: "https://www.example.com/opinions/painting-and-decorating/"
}
}
]
) {
signalIds
}
}
Required fields
Field | Values | Definition |
---|---|---|
category | String. Valid value - Behavior . | The category of the signal |
effect | String. Valid values: - negative - positive | Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring. Usually rich media interactions are interpreted as positive signals. |
mediaId | String | The URL of the media file |
name | String, up to 256 characters | Assign a name to the signal to differentiate it from other signals. |
signalType | String. Valid value -richMediaInteraction . | The type of signal to import |
Optional fields
Field | Values | Definition |
---|---|---|
interactionType | String. Valid values: - load - launch - pause - continue - complete - stop - enlarge | The type of user interaction with the media |
mediaCategory | String | The category that the media falls into, for example, "video" |
mediaName | String | The title of the audio or video file |
signalCustomAttributes | Array of objects | Allows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value . |
url | String | The URL of the page where the media file is embedded |