HomeData hubOther resources
Guides

SDK integration for a new Engagement setup

Suggest Edits

👍

Welcome note

Data hub is our new upgraded platform, which we rolled out in August 2025. It offers a single unified integration for passing your data through to your Bloomreach products.

You have access to Data hub if you've implemented with Bloomreach after August 2025.

Customers who have implemented before August 2025 should follow the existing documentation for Engagement, Discovery, and Clarity.

Integrating new Engagement

  1. Prerequisite (provisioning and grant access)
    • Data hub and workspace
    • Engagement project
  2. Add DNS records for Custom tracking domain
  3. Add snippet on the website
  4. Add tracking following the tracking specs

Tracking snippet

Your basic tracking snippet for all pages that you place in HTML before </HEAD> (required for non-flickering experiments), optionally you can add it to your Google Tag Manager.

<style>.xnpe_async_hide{opacity:0 !important}</style>
<script>
  !function(e,t,n,i,o,r){const s=4e3,c="xnpe_async_hide";function a(e){if("number"!=typeof e)return e;const t=new Date;return new Date(t.getTime()+1e3*e)}function p(e){return e.reduce((function(e,t){return e[t]=function(){e._.push([t.toString(),arguments])},e}),{_:[]})}function m(e,t,n){const i=n.createElement(t);i.src=e;const o=n.getElementsByTagName(t)[0];return o.parentNode.insertBefore(i,o),i}function l(e){return"[object Date]"===Object.prototype.toString.call(e)}r.target=r.target||"//api.exponea.com",r.file_path=r.file_path||r.target+"/js/brweb.min.js",o[t]=p(["anonymize","initialize","identify","getSegments","update","track","trackLink","trackEnhancedEcommerce","getHtml","showHtml","showBanner","showWebLayer","ping","getAbTest","loadDependency","getRecommendation","reloadWebLayers","_preInitialize","_initializeConfig","metadata"]),o[t].notifications=p(["isAvailable","isSubscribed","subscribe","unsubscribe"]),o[t].segments=p(["subscribe"]),o[t]["snippetVersion"]="v3.1.1",function(e,t,n,i){e[i]={sdk:e[n],sdkObjectName:n,skipExperiments:!!t.new_experiments,path:t.target,streamId:t.stream_id}}(o,r,t,i),function(e,t,n){m(e.file_path,t,n)}(r,n,e),function(e,t,n,i,o,r,p,u){if(!e.new_experiments)return;!0===e.new_experiments&&(e.new_experiments={});const _=e.new_experiments.hide_class||c,f=e.new_experiments.timeout||s,d=encodeURIComponent(r.location.href);let g;e.cookies&&e.cookies.expires&&("number"==typeof e.cookies.expires||l(e.cookies.expires)?g=a(e.cookies.expires):e.cookies.expires.tracking&&("number"==typeof e.cookies.expires.tracking||l(e.cookies.expires.tracking))&&(g=a(e.cookies.expires.tracking))),g&&g<new Date&&(g=void 0);const b=e.target+"/webxp/streams/"+e.stream_id+"/"+t+"/"+(u.exec(p.cookie)||[0,"new"])[1]+"/modifications.min.js?http-referer="+d+"&timeout="+f+"ms"+(g?"&cookie-expires="+Math.floor(g.getTime()/1e3):"");"sync"===e.new_experiments.mode&&r.localStorage.getItem("__exponea__sync_modifications__")?function(e,t,n,i,o){n[o][t]="<"+t+' src="'+e+'"></'+t+">",i.writeln(n[o][t]),i.writeln("<"+t+">!"+o+".init && document.writeln("+o+"."+t+'.replace("/'+t+'/", "/'+t+'-async/").replace("><", " async><"))</'+t+">")}(b,t,r,p,n):function(e,t,n,i,o,r,s,c){r.documentElement.classList.add(e);const a=m(n,i,r);function p(){o[c].init||m(n.replace("/"+i+"/","/"+i+"-async/"),i,r)}function l(){r.documentElement.classList.remove(e)}a.onload=p,a.onerror=p,o.setTimeout(l,t),o[s]._revealPage=l}(_,f,b,t,r,p,o,n)}(r,n,i,0,t,o,e,RegExp("__exponea_etc__"+"=([\\w-]+)")),function(e,t,n){var i;e[t]._initializeConfig(n),(null===(i=n.experimental)||void 0===i?void 0:i.non_personalized_weblayers)&&e[t]._preInitialize(n),e[t].start=function(i){i&&Object.keys(i).forEach((e=>n[e]=i[e])),e[t].initialize(n)}}(o,t,r)}(document,"brweb","script","webxpClient",window,{
  target: "https://api.XXXXXXX.dev", // your Bloomreach API base endpoint
    stream_id: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", // your Bloomreach Event stream ID
    experimental: {
        non_personalized_weblayers: true
    },
    new_experiments: { mode: "sync" },
    customer: {
        email_id: "[email protected]" // identified visitor identity for Engagement
    },
    track: {
        default_properties: { // custom properties to be added to all events
            customer_tier: "gold-member" // your additional custom segments (primarily for Discovery)
        },
        metadata: { // optional metadata properties which control specific functionality
            domain_key: "Pacific", // Bloomreach provided key for Discovery
            view_id: "en_US", // Bloomreach provided key for Discovery
            test_data: true, // enables Discovery ignore on production
            debug: true // enables Discovery real-time Integration mode and ignore on production
        }
    },
});
brweb.start(); // some regulations may require you to start() only after visitor has granted cookie consent
</script>

Tracking required events

  • Track your basic web user interactions.
  • The full list of events names and properties depend on selected use cases.
  • Refer to the Automatic tracking document and data requirements provided to you by Bloomreach consultant or an integration partner.
  • We include examples of these events, please follow the specs given to you by technical consultant in order to implement all required properties for your selected use cases.

Customer identification

  • Identify your visitors once they sign in.
brweb.identify({ email_id: "[email protected]" });
  • Anonymize the browser on visitor logout.
  • This will clear browser cookies and other identifying information in the browser memory.
  • Subsequent events will be tracked to a new anonymous visitor profile.
brweb.anonymize();

Recommended retail events

  • view_item (PDP)
  • view_category (PLP)
  • cart_update (add and remove from cart)
  • checkout
  • purchase (conversion)

Track view_item

  • Track this when product detail page is loaded.
  • This event is an impression of a product.
brweb.track("view_item", {
    title: "Yellow wide sweater with turtleneck",
    product_id: "119479",
    variant_id: "MJ12199-0400",
    price: 49.99
});

Track view_category

  • Track this event on product listing pages, or category listing pages.
brweb.track("view_category", {
    category_id: "650",
    title: "Turtlenecks",
    category_level_1: "Clothes",
    category_level_2: "Sweaters",
    category_level_3: "Sweaters & Cardigans"
});

Track cart_update

  • Track this event with action=add when user adds an item to the cart.
  • Track this event with action=remove when user removes an item from the cart.
  • This event is user interaction with a shopping cart.
brweb.track("cart_update", {
    action: "add", // add to cart
    title: "Yellow wide sweater with turtleneck",
    product_id: "119479",
    variant_id: "MJ12199-0400",
    product_list: [
        {
            product_id: "119479", quantity: 2
        }
    ],
    total_price: 99.98 // in USD reference currency for Engagement
});

brweb.track("cart_update", {
    action: "remove", // remove from cart
    title: "Yellow wide sweater with turtleneck",
    product_id: "119479",
    variant_id: "MJ12199-0400",
    product_list: [
        {
            product_id: "119479", quantity: 1
        }
    ],
    total_price: 49.98
});

Example: cart_update API request:

{
    "commands": [
        {
            "name": "customers/events",
            "data": {
                "customer_ids": {
                    "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
                },
                "event_type": "cart_update",
                "properties": {
                    "action": "add",
                    "title": "Yellow wide sweater with turtleneck",
                    "product_id": "119479",
                    "variant_id": "MJ12199-0400",
                    "product_list": [
                        {
                            "product_id": "119479",
                            "quantity": 2
                        }
                    ],
                    "total_price": 99.98,
                    "location": "https://www.pacific.com/en/clothing/sweaters-cardigans/turtleneck.html",
                    "referrer": "https://www.pacific.com/",
                    "os": "Windows",
                    "browser": "Chrome",
                    "device": "Other",
                    "page_title": "Pacific | Clothing & accessories",
                    "lang": "en-US",
                },
                "timestamp": 1749545984.2786303
            }
        }
    ]
}

Track checkout

  • Track this event during multi step checkout, track each step separately.
  • This event serves for funnel analysis of your customers.
brweb.track("checkout", {
    step_number: 2,
    step_title: "Shipping"
});

Track purchase (secured server-side)

Track purchase event with full product_list from your server for higher reliability and security of the data. This way you can include sensitive information such as costs/margins. Server-side integration allows you to send when order is cancelled or products are returned.

  • purchase_id
  • purchase_status = created
  • total_price
  • product_list
    • product_id
    • variant_id
    • title
    • quantity
    • price

For server side tracking use and customize following API call:

POST to your API endpoint https://tracking-api.bloomreach.co/track/u/v1/batch?stream_id=STREAM_ID

  • Add stream_id URL param with one from you Event stream credentials page.
  • Add X-Forwarded-For HTTP header with client's IP address for geolocation use cases.
  • Add User-Agent HTTP header with client's user agent for device audience targeting use cases.

Example API payload body:

{
    "commands": [
        {
            "name": "customers/events",
            "data": {
                "customer_ids": {
                    "email_id": "[email protected]",
                },
                "event_type": "purchase",
                "properties": {
                    // custom event properties
                    "purchase_id": "OID123",
                    "purchase_status": "created",
                    "total_price": 99.98,
                    "product_list": [
                        {
                            "title": "Yellow wide sweater with turtleneck",
                            "product_id": "119479",
                            "variant_id": "MJ12199-0400",
                            "price": 49.99,
                            "quantity": 2,
                        }
                    ]
                },
                "timestamp": 1749545984.2786303
            }
        }
    ]
}

Updated 3 months ago