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.

File import: Use JSON examples below
Real-time API import: Use signalContent in GraphQL examples below

Signal types and subscription availability

All subscriptions (Pro, Premium, Ultimate)

Add-to-cart signal
Identification signal
Order signal

Premium and Ultimate only

Error signal
On-site search signal
Page view signal
Product configuration signal
Product view signal
Rich media interaction signal

Add-to-cart signal

Triggered when a visitor adds products to their cart.

Availability: All Connect subscriptions (Pro, Premium, 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

category: String - Signal category (valid values: Behavior)
currency: String - Price currency (valid values: ISO 4217 currency codes)
effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all add-to-cart signals
itemQuantity: Number (integer) - Quantity of product added to cart
name: String (up to 256 characters) - Signal name to differentiate from other signals
productId: String - Product identifier (may coincide with SKU)
productName: String - Product name
signalType: String - Signal type (valid values: addToCart)
unitPrice: Number - Unit price of the product

Optional fields

discount: Number - Discount from original price (calculate difference between original and current price if exact amount unavailable)
imageUrls: Array of strings - Product image URLs
productCategory: String - Product category based on catalog
productDescription: String - Product description
productUrls: Array of strings - Product page URLs
promotionId: String - Promotion ID for on-site marketing that "sticks" to behaviors
shoppingCartUrl: String - Shopping cart URL
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received) - Example: 2025-08-31T08:29:30.001Z
virtualCategory: String - Category based on how visitor reached page (e.g., "New arrivals", "Sale")

Error signal

Sent when a user encounters an error on your site. Focus on payment, promo code, and account registration errors that lead users away from the happy path.

Availability: Premium and Ultimate subscriptions

🚧
Important
This signal doesn't replace error monitoring solutions. Its purpose is to let marketers segment users who encountered issues during order process and set up personalized messages triggered by the signal.

{
  "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

category: String - Signal category (valid values: Behavior)
effect: String - Signal engagement effect (valid values: negative, positive) - We suggest negative for all error signals
errorIdentifier: String - Error identifier (e.g., "promoCode")
errorText: String - Error message content received
errorType: String - Error type (valid values: application, user) - Application errors are server-side/system errors; user errors occur when input doesn't pass validation
name: String (up to 256 characters) - Signal name to differentiate from other signals
signalType: String - Signal type (valid values: error)

Optional fields

signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Identification signal

Captures visitors' emails or client/contact IDs as they browse your website.

Availability: All Connect subscriptions (Pro, Premium, 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

category: String - Signal category (valid values: Behavior)
effect: String - Signal interpretation for engagement index scoring (valid values: negative, positive)
identifierName: String - Identifier type (valid values: email, sms, contactKey)
identifierValue: String - Contact information associated with visitor (type depends on identifierName value)
name: String (up to 256 characters) - Signal name to differentiate from other signals
signalType: String - Signal type (valid values: identification)

Optional fields

identificationFromLogin: Boolean - Set to true if identifierValue derives from user authentication, false if from cookie/query string (separates explicit vs implicit identification)
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

On-site search signal

Records search terms website visitors use and number of results they get.

Availability: 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

category: String - Signal category (valid values: Behavior)
effect: String - Signal engagement effect (valid values: negative, positive) - Send positive if search returns results, negative if no results
name: String (up to 256 characters) - Signal name to differentiate from other signals
numberOfResults: Number (integer) - Number of results matching the search term
searchTerm: String - Word or phrase the visitor searched for
signalType: String - Signal type (valid values: onSiteSearch)

Optional fields

signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Order signal

Comes each time a contact places an order on your website. Includes total amount and detailed breakdown by product.

Availability: All Connect subscriptions (Pro, Premium, 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

category: String - Signal category (valid values: Behavior)
currency: String - Order currency (valid values: ISO 4217 currency codes)
effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all order signals
name: String (up to 256 characters) - Signal name to differentiate from other signals
orderId: String - Order identifier
signalType: String - Signal type (valid values: order)

Optional fields

orderDiscount: Number - Discount from original price
orderedItems: Array of objects - Products in the order (separate object per product, not per instance - three identical items = one object with quantity: 3)
orderShippingHandling: Number - Shipping and handling amount
orderSubtotal: Number - Subtotal amount (net of discount)
orderTax: Number - Tax amount
orderValue: Number - Total order value
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Ordered items fields

currency (optional): String - Product price currency (ISO 4217 codes)
discount (optional): Number - Discount from original price
imageUrls (optional): Array of strings - Product image URLs
productCategory (optional): String - Product category based on catalog
productDescription (optional): String - Product description
productId (required): String - Product identifier (may coincide with SKU)
productName (required): String - Product name
productUrls (optional): Array of strings - Product page URLs
promotionId (optional): String - Promotion ID for on-site marketing that "sticks" to behaviors
quantity (optional): Number (integer) - Product quantity purchased
shoppingCartUrl (optional): String - Shopping cart URL
unitPrice (required): Number - Amount client paid for product
virtualCategory (optional): String - Category based on how visitor reached product page (e.g., "New arrivals", "Sale")

Page view signal

Registers page views as users browse your website.

Availability: 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

category: String - Signal category (valid values: Behavior)
effect: String - Signal interpretation for engagement index scoring (valid values: negative, positive)
name: String (up to 256 characters) - Signal name to differentiate from other signals
signalType: String - Signal type (valid values: pageView)
url: String - URL of page user opened

Optional fields

pageCategory: String - Category the page belongs to
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Product configuration signal

Tracks interactions on product pages (selecting clothing size, checking FAQs/reviews, etc.) that suggest customer engagement.

Availability: 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

category: String - Signal category (valid values: Behavior)
configurationType: String - Interaction label (name product parameter like size/color/quantity or identify UI element like dropdown)
effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all product configuration signals
name: String (up to 256 characters) - Signal name to differentiate from other signals
productId: String - Product identifier (may coincide with SKU)
productName: String - Product name
signalType: String - Signal type (valid values: productConfiguration)

Optional fields

currency: String - Product price currency (valid values: ISO 4217 currency codes)
inventoryQuantity: Number (integer) - Number of units available
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Product view signal

Records user activity on product pages. Provides insights into product and category attention, crucial for segmentation and tying product interest to identified visitors.

Availability: 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",
   "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"
          discount: 0
          productCategory: "Painting & Decorating / Tools"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

category: String - Signal category (valid values: Behavior)
currency: String - Product price currency on website (valid values: ISO 4217 currency codes)
effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all product views
name: String (up to 256 characters) - Signal name to differentiate from other signals
productId: String - Product identifier (may coincide with SKU)
productName: String - Product name
signalType: String - Signal type (valid values: productView)
unitPrice: Number - Unit price of product (use placeholder if product pages don't have prices, as in banking/insurance)

Optional fields

availability: String - Product availability status (e.g., "In Stock", "Out of Stock", "Back Order")
brandDescription: String - Brand description
brandName: String - Product brand name
dateAdded: DateTime string - When product was added to catalog (format: yyyy-MM-dd HH:mm:ss.SSS)
discount: Number - Discount from original price
imageUrls: Array of strings - Product image URLs
inventoryQuantity: Number (integer) - Number of units available
model: String - Model number or description
msrp: Number (decimal/float) - Suggested retail price or original price
productCategory: String - Product category based on catalog
productDescription: String - Product description
productRating: Number - Product rating
productStatus: String - Product lifecycle state (e.g., "Active", "Discontinued", "Upcoming")
productUrls: Array of strings - Product page URLs
promotionId: String - Promotion ID for on-site marketing that "sticks" to behaviors
shoppingCartUrl: String - Shopping cart URL
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)
sku: String - SKU if different from product ID
virtualCategory: String - Category based on how visitor reached page (e.g., "New arrivals", "Sale")

Rich media interaction signal

Records user interactions with video and audio content on your website. Valuable for audience segmentation based on product/category interest.

Availability: 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

category: String - Signal category (valid values: Behavior)
effect: String - Signal engagement effect (valid values: negative, positive) - Usually rich media interactions are positive signals
mediaId: String - Media file URL
name: String (up to 256 characters) - Signal name to differentiate from other signals
signalType: String - Signal type (valid values: richMediaInteraction)

Optional fields

interactionType: String - User interaction type (valid values: load, launch, pause, continue, complete, stop, enlarge)
mediaCategory: String - Media category (e.g., "video")
mediaName: String - Audio or video file title
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)
url: String - URL of page where media file is embedded

Prepare signal content for import

Signal types and subscription availability

All subscriptions (Pro, Premium, Ultimate)

Premium and Ultimate only

Add-to-cart signal

Required fields

Optional fields

Error signal

🚧
Important

Required fields

Optional fields

Identification signal

Required fields

Optional fields

On-site search signal

Required fields

Optional fields

Order signal

Required fields

Optional fields

Ordered items fields

Page view signal

Required fields

Optional fields

Product configuration signal

Required fields

Optional fields

Product view signal

Required fields

Optional fields

Rich media interaction signal

Required fields

Optional fields

Related pages

Signal types and subscription availability

All subscriptions (Pro, Premium, Ultimate)

Premium and Ultimate only

Add-to-cart signal

Required fields

Optional fields

Error signal

🚧Important

Required fields

Optional fields

Identification signal

Required fields

Optional fields

On-site search signal

Required fields

Optional fields

Order signal

Required fields

Optional fields

Ordered items fields

Page view signal

Required fields

Optional fields

Product configuration signal

Required fields

Optional fields

Product view signal

Required fields

Optional fields

Rich media interaction signal

Required fields

Optional fields

Related pages

🚧
Important