This Pixel Reference provides complete information and definitions of the parameters for the Bloomreach pix.gif pixel tracking API. It is agnostic to the tracking library that you use – likely to be the JS tracker (BrTrk), Android, or iOS SDK, or calling the pixel API directly.

acct_id

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description: The Bloomreach-provided Account identifier, that is generally a four digit number.
Example: “1234”
Allowed values: The value must be a non-empty string that is a valid Bloomreach Discovery Account identifier.
Issues and impact: Events without acct_id are ignored and discarded. Bloomreach cannot use these events for reporting and learning. This issue degrades reporting accuracy, attribution, and search performance.

aq

Applicable to: Suggest Event
Value type: String
Required: Required for Suggest Event
Description: “aq” is short for “Actual Query”. This is the final query that the user had actually typed right before clicking on an autosuggestion. This helps in identifying the exact search term that produced the chosen autosuggestion. It should NOT be confused with the suggested word or phrase.
Example: If a user types “tabl” in the search bar and clicks on the autosuggestion “table”, the actual query will be “tabl”. They could have also clicked on a different auto-suggested value like “tabla”, both of which were derived from the same actual query (“tabl”).
Allowed values: All the values are allowed, as users can search for anything. The value can be an empty string as well.
Issues and impact: The aq field must be present. Suggest Events without an actual query will not have context for the autosuggestion and cannot be used for search learning. This degrades search performance and reporting.
Related Troubleshooting article:

• Missing “aq” in Suggest

basket

Applicable to: Conversion Page View
Value type: Object containing an array of product objects like {prod_id, sku, name, quantity, price}
Required: Required for Conversion Page View
Description: This object contains a property called items which is an array of the product objects purchased. Required field when is_conversion = “1”.
Example:

{
  "items": [
    {
      "prod_id": "pid1111",
      "sku": "sku1234",
      "name": "Linen Pillow",
      "quantity": "1",
      "price": "35.95"
    },
    {
      "prod_id": "pid1111",
      "sku": "sku1234",
      "name": "Linen Pillow",
      "quantity": "1",
      "price": "35.95"
    },
    {
      "prod_id": "pid1111",
      "sku": "sku1234",
      "name": "Linen Pillow",
      "quantity": "1",
      "price": "35.95"
    }
  ]
}

Allowed values: Each basket object contains an items array, which contains product objects with the following properties -

Basket Product ID and SKU ID Scenarios

You have to enter certain values for the prod_id and sku, depending on what products are in the basket. Create a product object for each product ID (and SKU, if your site has SKUs) in the basket.

{
  "items": [
    {
      "prod_id": "pid123456",
      "sku": "sku789",
      "name": "Cashmere Sweater",
      "quantity": "1",
      "price": "65.95"
    },
    {
      "prod_id": "pid56789",
      "sku": "",
      "name": "Blue Skinny Jeans",
      "quantity": "2",
      "price": "79.99"
    }
  ]
}

{
  "items": [
    {
      "prod_id": "pid123456",
      "sku": "sku789",
      "name": "Cashmere Sweater White",
      "quantity": "2",
      "price": "120.00"
    },
    {
      "prod_id": "pid123456",
      "sku": "sku790",
      "name": "Cashmere Sweater Blue",
      "quantity": "1",
      "price": "60.00"
    },
    {
      "prod_id": "pid56789",
      "sku": "",
      "name": "Blue Skinny Jeans",
      "quantity": "2",
      "price": "79.99"
    }
  ]
}   
      

{
  "items": [
    {
      "prod_id": "collection223344",
      "sku": "",
      "name": "Linen Bed Sheet Set",
      "quantity": "1",
      "price": "265.95"
    },
    {
      "prod_id": "pid56789",
      "sku": "",
      "name": "Blue Skinny Jeans",
      "quantity": "2",
      "price": "79.99"
    }
  ]   
  

{
  "items": [
    {
      "prod_id": "pid1111",
      "sku": "",
      "name": "Linen Pillow",
      "quantity": "1",
      "price": "35.95"
    },
    {
      "prod_id": "pid2222",
      "sku": "",
      "name": "Linen Comforter",
      "quantity": "1",
      "price": "230.00"
    },
    {
      "prod_id": "pid56789",
      "sku": "",
      "name": "Blue Skinny Jeans",
      "quantity": "2",
      "price": "79.99"
    }
  ]
}
    

Additional Basket Information for native app implementation

The key-value data you send us in the basket will be transformed into the format below in the executed pixel (pix.gif) file:

E.g. !ipid123456'ssku789'nCashmere Sweater'q1.0'p69.95!ipid56789'nBlue Skinny Jeans'q1.0'p79.99

Each product in the cart will be separated by a !. Each product's details will be separated by '.

1. i - This is the product id and not another id such as sku id or collection id. This should match the unique product id sent in the feed.

2. s - Sku id, only applies if you have skus.

3. n - product_name.

4. q - quantity of the product in the basket.

5. p - This should be the unit price per product and not the total price. If the item is on sale, this is the unit sale price.

Issues and impact:

• Events with a missing or invalid basket parameter will degrade reporting accuracy, attribution, and search performance.
• Events with an invalid or missing basket item name degrade reporting accuracy, attribution, and search performance.
• Events with an invalid basket item prod_id degrade reporting accuracy, attribution, and search performance.
• Events with a missing or invalid basket item sku degrade reporting accuracy, attribution, and search performance.
• Events with a missing or invalid basket item quantity degrade reporting accuracy, attribution, and search performance.
• Events with a missing or invalid basket item price degrade reporting accuracy, attribution, and search performance.

Related Troubleshooting articles:

• Missing or Empty Conversion Basket
• Non-unit pricing for basket item price parameters
• Missing or Invalid Quantity
• Missing or Invalid Price
• Missing or Empty Product ID Field
• Missing or Empty SKU Field

basket_value

Applicable to: Conversion Page View
Value type: String
Required: Required for Conversion Page View
Description: The total price of the checkout basket, which may include tax, discounts, and shipping (depending on how you wish to report revenue, ideally matching other BI reports). The total value (including taxes, discounts, etc.) must be within ± 10% of the sum of the individual line items in the basket parameter.

If the checkout basket was $100 with $5 tax and $10 shipping, then br_data.basket_value="115.00"

If the checkout basket was $100 with $0 tax, $10 discount, and $10 shipping, then br_data.basket_value="100.00"

The total price is taken either in
a) the account currency or
b) the currency specified by the currency parameter

For example:
If the account currency is USD and the incoming event has basket_value=”100” and an undefined or empty currency parameter, the value will be stored in USD.
If currency=”EUR” is also passed with basket_value=95, it is converted (based on exchange rate) to the account currency and stored as 100 USD.
Read more on multi-currency.

This basket value must match the basket value used in your analytics systems.

Example: "100.00"
Allowed values: This should be a number and cannot be undefined, NaN or null, etc. This is a required field when is_conversion = “1".
Issues and impact: Events with an invalid or missing basket_value degrade reporting accuracy, attribution, and search performance.
Related Troubleshooting articles:

• Total basket price inconsistent with basket_value parameters
• Missing or Invalid Revenue Value

cat

Applicable to: Category Page View
Value type: String
Required: Required only for Category Page View
Description: The breadcrumb of the page. Crumbs need to be delimited by pipe ( | character). Refer to the Bread Crumb Scenarios to determine what value to use for your bread crumb.
Example: "Home|Clothing|Outerwear"
Allowed values: String of pipe-separated values.

Bread Crumb Scenarios

Issues and impact: Events with an invalid or missing cat degrade reporting and category attribution.

cat_id

Applicable to: Category Page View
Value type: String (case sensitive)
Required: Required only for Category Page View
Description: Unique category ID as referred to in the database/catalog. Bloomreach requires the cat_id field to be unique across your site. For Search implementations, the same cat_id value needs to be passed in the API call. Refer to the Category ID Scenarios to determine what value to use for your category ID.
Example: "catid123"
Allowed values: The cat_id value must match the crumb_id value in your feed.

Category ID Scenarios

Issues and impact: Events with an invalid or missing cat_id degrade reporting and category attribution.

catalogs

Applicable to: Content Page View, Search Result Page View, Search Event, Suggest Event
Value type: Array of Catalog objects
Required: Conditional (depends on type and your implementation)
Description: List of catalogs that are shown on the page. In case the page has multiple tabs, only the catalogs of the selected (and visualized) tabs should be included. If multiple catalogs are shown on the active page (or tab), all of them should be included. Required for Content page. If your account has a content catalog then it's required for Search result pageview, Search event and Suggest event.
Example:

For JS implementation (simple, without views)

[
  { name : "products_en" }
]

For native app implementation (simple, without views)

cat0=products_en

For JS implementation (with views)

[
  { name : "content_en", "view_ids": ["store123", "store456"] },
  { name : "product", "view_ids": ["store123", "store456"] }
]

For native app implementation (with views)

cat0=content_en:v0=store123.v1=store456!cat1=product:v0=store123.v1=store456

Allowed values: The values (and optionally views) must match values in catalog feed.

catalogs format
You must manually format the catalogs parameter for native app implementation.
Example catalogs parameter: &catalogs=cat0%3Dcontent_en%3Av0%3Dstore123.v1%3Dstore456%21cat1%3Dproduct%3Av0%3Dstore123.v1%3Dstore456

• The catalog name is encoded by prefixing "cat" + "the index of the catalog starting from 0" + "=" + "the catalog name"
• Each catalog in catalogs is separated by an "!"

If your implementation has views, the view_id value must also be passed correctly.

• The view_id is encoded by prefixing "v" + "the index of the view_id starting from 0" + "=" + "the view_id"
• Catalog name and view_id are separated by a ":"
• Multiple view_ids are separated by a "."

Implementation scenarios for catalogs

Note that the examples here are not percent-encoded. Remember to percent encode your parameters for native app implementation.

Issues and impact: Events with invalid catalogs degrade reporting accuracy and search performance.

cookie2

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description: Anonymous identifier for a particular browser or device instance using a randomly generated unique user ID. Value is usually stored as a browser cookie. Format is:

uid={{cookie_uid}}:v={{tracker_version}}:ts={{unix_timestamp}}:hc={{hitcount}}

cookie_uid - random 10-13 digit number generated on first visit in the browser or device and stored as a cookie or in local storage on the device, must respect customer privacy choices, example JS: Math.round(Math.random() * 10E12);

tracker_version - version of used tracker (from SDK); for direct API calls use “app”

ts - unix epoch timestamp in seconds when cookie_uid was generated

hitcount - value should be 1 for a new visitor, and incrementing with every subsequent pixel fired.

Example:

• uid=3510849277068:v=11.8:ts=1636626614546:hc=1
• URL Encoded
  cookie2=uid%3D3510849277068%3Av%3D11.8%3Ats%3D1636626614546%3Ahc%3D1

Allowed values: As specified in the description above.
Issues and impact: Events without cookie2 are given a random ID. This issue of customer identification degrades reporting accuracy, attribution, and search performance.

Validate implementation: Test Scenarios - User Cookies
Related Troubleshooting article: Unrecognized Format of Cookie2 Value

Sensitivity: Pixel data collected

cookie2 with cdp_segments

For the Real-Time Segments (RTS) feature pixel, the cdp_segments property value is encoded and appended to the event's cookie2 value. This value is a string representing the combination of one or more segmentation_id and segment_id key-value pairs. It specifies the segmentation_id and segment_id to personalize the ranking.

Example:

• uid=3510849277068:v=16.0:ts=1718920236482:hc=8:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==
• URL Encoded

cookie2=uid%3D3510849277068%3Av%3D16.0%3Ats%3D1718920236482%3Ahc%3D8%3Acdp_segments%3DNjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==

Allowed values for cdp_segments: Must be base64 encoded key-value pair of segmentation_id and segment_id. Values must be known to the Bloomreach Engagement and Discovery integration.

Issues and impact: Events with invalid cdp_segments cannot be used for Real-time Customer Segment machine learning.

currency

Applicable to:Conversion Page View
Value type: String
Required: Required for Conversion Page View
Description: Designates the currency code for the transaction. We configure the currency value according to your needs.

You can choose from EUR, GBP, USD, or any other supported currency mentioned below.
Example: "GBP"
Allowed values: Please ensure that the value is one of the options listed below:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMW, ZWL
Issues and impact: Events with invalid currency cannot be used for revenue calculation. This issue degrades reporting accuracy, attribution, and search performance.

customer_country

Applicable to: Relevance by Segment feature pixel
Value type: String containing the segment value
Required: Required for Relevance by Segment feature
Description: Country that the user belongs to.
Example: “france”, “US”
Allowed values: The value string may only contain alphanumeric characters (a-z, A-Z, 0-9), hyphens (“-”), or underscores (“_”). It is case insensitive.

This can have up to 5000 unique values, though we don’t recommend using a segment with so many values since it can thin out the data used for ranking. If you do have a use case for using more than 5000 unique value, please consult a member of the Bloomreach team.
Issues and impact: This parameter impacts the search results ranking based on segment data.

customer_geo

Applicable to: Relevance by Segment feature pixel
Value type: String containing the segment value
Required: Required for Relevance by Segment feature
Description: Geography/region that the customer belongs to.
Example: "europe”, “asia”
Allowed values: The value string may only contain alphanumeric characters (a-z, A-Z, 0-9), hyphens (“-”), or underscores (“_”). It is case insensitive.

This can have up to 5000 unique values, though we don’t recommend using a segment with so many values since it can thin out the data used for ranking. If you do have a use case for using more than 5000 unique value, please consult a member of the Bloomreach team.
Issues and impact: This parameter impacts the search results ranking based on segment data.

customer_profile

Applicable to: Relevance by Segment feature pixel
Value type: String containing the segment value
Required: Required for Relevance by Segment feature
Description: Profile that the user belongs to.
Example: “healthcare”, “industrial”
Allowed values: The value string may only contain alphanumeric characters (a-z, A-Z, 0-9), hyphens (“-”), or underscores (“_”). It is case insensitive.

This can have up to 5000 unique values, though we don’t recommend using a segment with so many values since it can thin out the data used for ranking. If you do have a use case for using more than 5000 unique value, please consult a member of the Bloomreach team.
Issues and impact: This parameter impacts the search results ranking based on segment data.

customer_tier

Applicable to: Relevance by Segment feature pixel
Value type: String containing the segment value
Required: Required for Relevance by Segment feature
Description: Tier that the user belongs to.
Example: “premium”, “gold”, “base”
Allowed values: The value string may only contain alphanumeric characters (a-z, A-Z, 0-9), hyphens (“-”), or underscores (“_”). It is case insensitive.

This can have up to 5000 unique values, though we don’t recommend using a segment with so many values since it can thin out the data used for ranking. If you do have a use case for using more than 5000 unique value, please consult a member of the Bloomreach team.
Issues and impact: This parameter impacts the search results ranking based on segment data.

domain_key

Applicable to: Valid for all pixel requests
Value type: String (case sensitive)
Required: Conditional; depends on your implementation
Description:

Set Domain Key to the name of the product Catalog that would be searched against on the page where the event occurred. It corresponds to the Search API's domain_key parameter and should match. If you do not query the Search API with a domain_key parameter, the value’s default is the name of the Account's primary Catalog.

The Bloomreach-provided ID of the domain receiving the request. This parameter identifies the specific site language version when one account ID hosts multiple site versions with different languages. Bloomreach uses this value to ensure that only query and analytics data that pertain to that language are used for respective features.

This parameter is only required if your Account has more than one product Catalog. Otherwise, domain_key should not be declared in the pixel, as this will cause issues with analytics.

During the technical kickoff call, the Bloomreach integrations team will inform you whether domain_key will be required for your pixel integration.

Example: "bloomreach_fr"
Allowed values: When choosing a domain_key, it is crucial to adhere to the following rules to ensure compatibility and consistency:

1. Start with a Lowercase letter: The domain_key must initiate with a lowercase letter (a-z).
2. Valid End Characters: It should end with either a lowercase letter (a-z) or a digit (0-9).
3. Character Restrictions for Body:
   • The core segment can contain up to 46 characters comprised of lowercase letters, digits, or underscores.
   • Only underscores may be used as special characters within this range.
4. Length Constraint: The total length of the domain_key must not surpass 48 characters, with the above structure in mind.
5. Consistency Check: Ensure the domain_key corresponds exactly with the values passed in product feeds for flawless integration.
6. Case Sensitivity: The domain_key is sensitive to case; therefore, proper use of lowercase is crucial.

The regex rule for domain_key is \^[a-z]{1}\[a-z0-9\\_]{0,46}[a-z0-9]{1}$\
Issues and impact: Events with invalid domain_key degrade reporting accuracy and search performance.

etype

Applicable to: Tracking variable for Add-to-cart (ATC), Search, Suggest, and Quick View Events.
Value type: String
Required: Required for the abovementioned Events.
Description: Specifies the event's action type.
Example: "click"
Allowed values: This must match the appropriate event pixel type.

Issues and impact: Events with invalid etype or missing etype cannot be classified properly. This issue degrades reporting accuracy, attribution, and search performance.
Related Troubleshooting article:

• Add to Cart event: Incorrect “etype”, Expecting Click-add
• Quickview event: Incorrect “etype”, Expecting Quickview
• Search/Suggest pixel: Incorrect “etype”, Expecting Click or Submit

group

Applicable to: Tracking variable for Add-to-cart (ATC), Search, Suggest, and Quick View Events.
Value type: String
Required: Required for the abovementioned Events.
Description: This specifies the event grouping.
Example: “cart”
Allowed values: This must match the appropriate event pixel type. It must not be empty.

Issues and impact: Events with an invalid group or without group cannot be classified properly. This issue degrades reporting accuracy, attribution, and search performance.

is_conversion

Applicable to: Conversion Page View, deprecated for All Other Page View
Value type: Integer
Required: Required for Conversion page view
Description: This parameter is set to 1 to indicate this is a Conversion or Thank you page (page after the customer completes the purchase).

If you are using JS tracker BrTrk, then value 1 also means that BrTrk will encode basket JSON into basket encoded string for the API.

🚧

Deprecated

If you send ptype = “other” on a Conversion page, is_conversion must be set to 1.

Example: "1"
Allowed values: It is set to 1 or not set.
Issues and impact: Events with invalid is_conversion cannot be classified properly as conversion events. This issue degrades reporting accuracy, attribution, and search performance.

item_id

Applicable to: Content Page View, Widget Click Event, Widget Add Event
Value type: String
Required: Required for the abovementioned Events
Description: Unique ID of the item being shown on the page.
Example: "recipe115718079035"
Allowed values: This identifier should match the item_id as specified in the feed.
Issues and impact: Events without item_id degrade search performance.

item_name

Applicable to: Content Page View
Value type: String
Required: Required for Content Page View
Description: Name or the title of the Content page.
Example: "California Avocado Omelette Recipe"
Allowed values: Must be a non-empty string.
Issues and impact: Events with invalid or missing item_name values degrade reporting clarity and readability.

order_id

Applicable to: Conversion Page View
Value type: String
Required: Required for Conversion Page View
Description: The order ID associated with the order placed. This ID should match the orderID used in your analytics systems. This is used to reconcile Bloomreach's analytics data with your analytics systems.
Example: "12123455"
Allowed values: Order ID must be a unique string identifier for the order. This is a required field when is_conversion = “1".
Issues and impact: Events with invalid order_id or no order_id cannot be matched with external data during data reconciliation between systems.
Sensitivity: Pixel data collected

orig_ref_url

Applicable to: Virtual page view tracking
Value type: String
Required: Required only for Virtual Page View tracking.
Description: The URL from which it is originally referred. Only to be used in Virtual Page Views for the Ajax request.
Example: "https://pacifichomeshop.com"
Allowed values: Must be a valid URL.
Issues and impact: If orig_ref_url is invalid, it leads to improper tracking of page referrer on Single Page Applications. This degrades reporting accuracy, attribution, and search performance.
Related Troubleshooting article: Ajax is Setting the Original Reference URL Incorrectly
Sensitivity: Pixel data collected

prod_collection_id

Applicable to: ATC Event, Quick View Event
Value type: String
Required: Optional for ATC Event and Quick View Event
Description: The unique ID of a Product Collection. This needs to be passed when the relevant Event occurs from a Product Collection page.
Example: "collection5678"

prod_id

Applicable to: Product Page View, Conversion Page View (in the basket), ATC Event, Quick View Event
Value type: String (case sensitive)
Required: Required
Description: The unique product ID, which describes a product, product bundle, product collection or SKU set. If a product is available in multiple SKUs (e.g., color/size combinations), this field refers to the ID shared by all the SKUs for a product.

Product ID Scenarios

The product ID value depends on whether it refers to a single product or to a product collection. The table below outlines multiple scenarios and the corresponding product ID value.

Example: “prod1234”
Allowed values: This can be any product ID value. It should be unique.
Issues and impact: Events with invalid prod_id, missing prod_id, or prod_id values that do not match with the product feed degrade reporting, attribution, and search performance.
Related Troubleshooting articles:

• Product page view pixel: Page View pixel with empty prod_id field
• Add to cart event: Percent of Add to Cart prod_id is not Visible in the Product View Page, Missing Product ID in the Add to Cart Event
• Quick view event: Missing Product ID in the Quickview Event
• Conversion pixel: Missing or Empty Product ID Field

prod_name

Applicable to: Product Page View, ATC Event (native app only), Quick View Event
Value type: String
Required: Required for Product Page View and Quick View Events. Optional for ATC Event.
Description: The name of the product being viewed or added to the cart.
Example: “Blue Lace Dress”
Allowed values: Must be a non-empty string.
Issues and impact: Events with an empty or missing prod_name degrade reporting clarity and readability.

ptype

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description: Maps your site's page type classifications to the values Bloomreach expects for page type classifications. It is required on all page views, including desktop, mobile, and tablet versions. Bloomreach has 7 page types: homepage, product, category, search, content, thematic, and other.

Example: "homepage"

Allowed values:

Issues and impact: Events with a missing or invalid ptype are ignored and will be discarded. Bloomreach cannot use these events for reporting and learning. This issue degrades reporting accuracy, attribution, and search performance.

q

Applicable to: Search Event, Suggest Event
Value type: String
Required: Required for both Search and Suggest Event
Description: The search query typed (and submitted) by the user in the search box.
Example: “blue dress”
Allowed values: All the values are allowed as users can search for anything. The value must be a non-empty string.
Issues and impact: The query field must be present. Events without a query cannot be used for search learning and degrade search performance and reporting. Such requests will return an Error code 400.
Related Troubleshooting article:

• Missing “q” in Search/Suggest
• Sending special characters in "q" parameter

rand

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description: A random number that acts as a cache buster to make sure browsers and proxies don't cache requests.
Example: 0.4566879906
Allowed values: Should be a non-empty value, as random as possible (float or integer)
Issues and impact:

1. Missing rand value - Tracking events without rand can cause data loss. Events without rand can be cached and not received by Bloomreach. This issue may degrade reporting and search performance.
2. Invalid rand - Events with an invalid rand can point at the wrong rand implementation. Events without rand can be cached and not received by Bloomreach. This issue may degrade reporting and search performance.

ref

Applicable to: Valid for all pixel requests
Value type: String
Required: Conditional; can be empty only on landing page from a direct channel (e.g. bookmark or typing in the URL), otherwise must have value of the previous page URL
Description:

For JS implementation

This is the URL from the referrer screen.

This parameter should match the format of the "url" parameter, which provides the full URL of the page being viewed without any query string parameters or anchors.

For Native app implementation

For a mobile native app, both "ref" and "url" parameters follow a similar synthetic structure that is used for identifying the content within the app rather than actual navigable URLs.
Example:
For JS implementation:

www.homeoasis.com/category/mens-clothes

For Native app implementation:

http://v11.0-android.app.homeoasis.com/category/mens-clothes

Allowed values: Any url that is the reference of the current url.

Issues and impact: Events with an invalid or missing ref degrade reporting accuracy, attribution, and search performance.

Sensitivity: Pixel data collected

search_term

Applicable to: Search Result Page View
Value type: String
Required: Required for Search Result Page View
Description: The value of the search query describing the page.
Example: “blue dress”
Allowed values: All the values are allowed, as users can search for anything. The value can be an empty string as well - the search_term can be empty when the user doesn't type anything and presses enter (submits an empty query).
Issues and impact: The search_term field must be present. Events without search_term cannot be used for search learning and degrade search performance and reporting.
Related Troubleshooting article:

• Search Result Page View pixel: Empty search_term Field in Search Page View Pixel

sku

Applicable to: Product Page View, Conversion Page View (in the basket), ATC Event, Quick View Event
Value type: String
Required: Conditional; depends on your implementation
Description: Unique sku ID representing the selected variant of this product (e.g., size M, color blue of a t-shirt). This must match the SKU ID field in the feed. If your site does not have SKUs, leave this blank.
Example: “sku7778”
Allowed values: The values should be consistent with what you send in the feed. This must be a string or comma-separated list.
Issues and impact: Events with invalid sku, missing sku, or sku values that do not match with the product feed degrade reporting, attribution, and search performance.
Related Troubleshooting articles:

• Conversion pixel basket field: Missing or Empty SKU Field
• Add to Cart pixel: Missing SKU ID in the Add to Cart Event

test_data

Applicable to: Valid for all pixel requests
Value type: Boolean
Required: Conditional; depends on your implementation
Description: When set to true, this flags pixel data to be ignored during analytics processing. This ensures that you can fire the pixel in a test environment, allowing you to perform pixel validation without affecting your analytics data. We recommend not declaring test_data=true in the pixel for your live site. While it is possible to send test_data=false on the live site, it is not an ideal implementation.
Example: true
Allowed values: true/false. For test data, the value must be lowercase "true" or not set. When any other value (say “false”) is received, Bloomreach processes the data as production data.
Issues and impact: Events with invalid test_data value are considered to be production data. If you meant to send test data, this issue can degrade your production data quality, reporting, and learning.

title

Applicable to: Valid for all pixel requests
Value type: String
Required: Required

Description:

For JS implementation

This is the title of the current page. Bloomreach uses titles when listing pages in analytics reports for Insights.

If you have <title> tags set in your HTML, you must add this variable to your Pixel. Every page on your site should have a different title.

For Native app implementation

This is the screen name of the app view.

Example: JS Implementation - "Best Sellers"
Native app - "Best%20Sellers"

Allowed values: Any string

Issues and impact: Events with an invalid or missing title degrade reporting clarity and readability.

tms

Applicable to: Valid for all pixel requests
Value type: String
Required: Conditional; depends on your implementation
Description: The name of the Tag Management system that should be filtered out. In case of migration from one tag management system to another, there may be a transition time frame when the pixel is fired by two systems simultaneously. Setting the tms parameter will allow the Bloomreach analytics system to filter out duplicate pixels. Use tms="tlm" for Tealium. This parameter is optional and only required during the transition time from one tag management system to another. Leave this field empty if this scenario does not apply.

Example: "tlm"
Allowed values: The allowed values for tms are “gtm” (for Google Tag Manager) or “tlm'” (for Tealium).

Issues and impact: If the tms variable is incorrect or invalid, it could lead to duplicate pixels, which can impact the analytics data.

type

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description: The type of tracking fire. For page view pixels, type=pageview.
Example: "pageview"
Allowed values:

Issues and impact: Events without or invalid type cannot be classified properly. This issue degrades reporting accuracy, attribution, and search performance.

url

Applicable to: Valid for all pixel requests
Value type: String
Required: Required
Description:

For JS implementation

This should include the full URL of the page the user is viewing without any URL parameters. This URL is used to identify the page for analytics and personalization purposes. If the page URL includes query parameters or anchors, these should be removed before setting the "url" parameter in the pixel. Only the base URL of the page is required. The URL is encoded to ensure it can be properly handled and parsed by the Bloomreach pixel tracking library.

For Native app implementation

In the context of native (mobile) apps, the "url" parameter should be a synthetic unique URL composed of a static base URL and the screen app screen name. To maintain uniqueness, the base URL should be prefixed with OS and application version, should be prefixed with the page type classification, and then followed by the title. For example, synthetic URL: http://{releaseversion}-{operatingSystem}.app.merchantname.com/category/mens-clothes.The URL could be structured with the ptype and title matching the values of their respective variables in the pixel. This URL is used to uniquely identify the page/content being viewed for tracking purposes.

Release version and operating system are proven to be useful for troubleshooting the release that caused it.

Example:

For JS implementation:

www.homeoasis.com/category/mens-clothes

For Native app implementation:

http://v11.0-android.app.homeoasis.com/category/mens-clothes

Allowed values: Must be a valid URL, and must be one of your whitelisted domains (configured by Bloomreach).

Issues and impact: Events with a missing or invalid url degrade reporting accuracy, attribution, and search performance.
Related Troubleshooting article: Urls from Homepage Missing in Pixel Logs

Sensitivity: Pixel data collected

user_id

Applicable to: Valid for all pixel requests

Value type: String

Required: Conditional; depends on your implementation

Description: If you track users via a universal customer ID, populate this parameter with that ID. This should be an anonymized string. It should not contain the user's email or other personally identifiable information. This parameter is only required if you wish to identify your users via a universal customer ID. This will allow Bloomreach to recognize users in a way that is aligned with your system for various personalization features.

Example: "61WwurfPU9f9dB5"

Allowed values: The correct implementation of this parameter can vary for different user scenarios. Common mistake is to set user_id to "null" or "undefined". Learn what parameter value you can set for each scenario in the user_id recommended implementation article.
Issues and impact: If the user_id is incorrect, it can lead to improper analytics reports. Some metrics may behave unusually, leading to inaccurate insights. This can affect the understanding of user behavior and the effectiveness of personalization features.
Related Troubleshooting article: Past Purchase Widget Missing

Sensitivity: Pixel data collected

view_id

Applicable to: Valid for all pixel requests

Value type: String (case-sensitive)

Required: Conditional; depends on your implementation

Description: The name of the product catalog view that would be searched against on the page where the event occurred. It corresponds to the Search APIs view_id parameter and should match. If you do not query the Search API with a view parameter, the value should be left empty.

Identifies the catalog view to show when one Bloomreach account ID hosts multiple site versions with unique product catalog characteristics, such as product price, availability, or title. Bloomreach uses View ID value to display the right product information for a user based on their site view.

This parameter is only required if you integrate on a site with multiple site versions with unique product catalog characteristics. Otherwise, view_id should not be declared in the pixel, as this will cause issues with analytics.

In the early stages of scoping and designing an integration project, Bloomreach will work with your teams to determine whether view_id will be required for your pixel integration.

Value must be consistent with the view_id value passed in the feed and API call.

Example: “10200”
Allowed values:

When choosing a view_id, it is crucial to adhere to the following rules to ensure compatibility and consistency:

1. Starting and Ending Characters: The view_id must begin and end with either a letter (A-Z, a-z) or a digit (0-9).

2. Middle Characters:

• A maximum of 46 characters (letters, digits, or underscores) can reside between the starting and ending characters.

• Only underscores may be used as special characters within this range.

3. Length Constraint: The total length of the view_id must not surpass 48 characters, with the above structure in mind.

4. Consistency Check: The view_id should align exactly with the values passed in product feeds for flawless integration.

5. Case Sensitivity: Remember, the view_id distinguishes between uppercase and lowercase letters.

The regex rule for view_id is ^[a-zA-Z0-9][a-zA-Z0-9\_]{0,46}[a-zA-Z0-9]$

Issues and impact: Events with invalid view_id degrade reporting accuracy and search performance.

wid

Applicable to: Widget View, Widget Click, Widget Add-to-Cart Event
Value type: String
Required: Required for the above Widget Events
Description: The widget ID.
Example: abc123
Allowed values: This is a unique, 6 or 8-character alphanumeric value. This value has to be populated from the API response metadata.widget.id.
Issues and impact: Events with incorrect or missing wid values create discrepancies with Recommendation Analytics.

wq

Applicable to: Widget View, Widget Click, Widget Add-to-Cart Event
Value type: Query String
Required: This is optional for non-query widgets. Required for “search", "category", "past_purchases" widgets.
Description: The query string used by the customer which returns a widget suggestion.Example: black dress
Allowed values: The value can be any string.
Issues and impact: Events with incorrect or missing wq values create discrepancies with Recommendation Analytics.

wrid

Applicable to: Widget View, Widget Click, Widget Add-to-Cart Event
Value type: String
Required: Required for the above Widget Events.
Description: The unique ID of the response.
Example: abcd123
Allowed values: This value has to be populated from the API response metadata.widget.rid.
Issues and impact: Events with incorrect or missing wrid values create discrepancies with Recommendation Analytics.

wty

Applicable to: Widget View, Widget Click, Widget Add-to-Cart Event
Value type: String
Required: Required for the above Widget Events.
Description: The type of recommendation widget.
Example: mlt, jfy
Allowed values: The value returned in the API response shall be passed as a widget type.
Issues and impact: Events with incorrect or missing wty values create discrepancies with Recommendation Analytics.