HomeData hubOther resources
Guides

SDK integration for new Engagement and Discovery setups

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 both Engagement and Discovery

  1. Prerequisite (provisioning and granting access)
    • Data hub and workspace
    • Engagement project
    • Discovery account project
  2. Add DNS records for Custom tracking domain
  3. Add the tracking snippet to your website
    1. The snippet builder can be used in the app to customize for your individual business needs
    2. The default tracking snippet is also provided below, however you will find increased functionality from customizing it
  4. Add tracking events according to the tracking specifications here: SDK tracking required events details
    1. For any questions about which tracking events are relevant to your business objectives, refer to the Tracking document and data requirements tailored for you by Bloomreach or your implementation partner

Tracking snippet

This is your basic tracking snippet for all pages.

  • Pages with confidential information (such as payment gateways) are proposed to be excluded. It's not advised to initialize tracking scripts on payment gateways since this can be abused to gain access to users' credit card numbers and other sensitive information.
  • Place it 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>

Snippet highlights:

  • default_properties
    • You will include any additional custom event properties that you want to pass to all events automatically
    • Examples:
      • customer_tier- Discovery "relevance by segment" search personalization
  • metadata
    • You will include optional metadata properties that control specific functionality
    • Discovery features options:
      • domain_key - string, specific catalog site key provided by Discovery
      • view_id - string, specific view site key provided by Discovery
      • test_data - boolean, if true the system ignores the data from production
      • debug - boolean, if true the system enables real-time troubleshooting of tracking in Event diagnostics Integration mode

Metadata update

In some special cases, you may need to update metadata after start(). In that case, use a metadata() method:

brweb.metadata({
    domain_key: "Pacific",
    view_id: "es_MX",
    test_data: true,
    debug: true
});

When only view_id is to be changed:

brweb.metadata({
    view_id: "es_MX"
});

Migrating from Engagement tracking to Data hub tracking

If you are migrating from an existing Engagement project, and your existing tracking is already using exponea, you should create an exponea alias for the new brweb snippet.

Normally, weblayers in migrating projects are also configured to use exponea, and you can allow the old code to function by using a backwards-compatible alias.

For backwards compatibility, create an alias for brweb early in your JavaScript, insert it right after your snippet, before calling the start() method on all pages:

...
}); // new snippet ends here
window.exponea = brweb; // create alias for backwards compatibility
exponea.start();

Customer identification

  • Identify your visitors once they sign in.
  • Use identity field configured in your Engagement project (Customer Hard ID)
brweb.identify({ email_id: "[email protected]" });
  • If visitor privacy is a concern, 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();

Discovery personalization with user_id

  • Optionally set user_id for Discovery personalization. This is a specific Discovery use case and is optional. Consult this before implementing.
  • Do not set it to a clear text personal information, use an obfuscated value. This value will be sent to Discovery.
  • This can be customer (B2C) or business ID (B2B).

Recommended modify the tracking snippet to include the user_id in by default:

    track: {
        metadata: {
            user_id: "be3e149d34ed43d4128252f2"
        }
    }

Alternatively you can update the user_id anytime after the snippet is initialized with:

brweb.metadata({
    user_id: "be3e149d34ed43d4128252f2"
});

Cookie expiration controls

We give you full control over the expiration date of cookies. Just note that you are setting maximum cookie retention, but the actual visitor's browser cookie policy can cause the cookie to expire much sooner, depending on the cookie type (domain, JavaScript set vs server set, etc).

brweb.start({
  cookies: {
    expires: 182 * 24 * 3600 // = 182 days
  }
});

Real-time customer segments feature

If you use real-time customer segments, integration is easier because you don’t need to add two trackers.

The rest of the flow is the same:

  • Connect your Engagement project to your Discovery account
  • Expose the Engagement segments and expect a training period for the Discovery learning process

Read more here:

Real Time Segmentation Technical Setup overview

Here are the necessary procedures and components required to implement real-time segmentation effectively. The critical aspects include:

Prerequisites

  • Compatible Environment: Ensure a Discovery Pixel tracker and a Merchant account are set up
  • Dashboard Configuration: Set up dashboards for Discovery and Engagement with specific linking functionalities

Essential Setup Steps

  • Tracker Integration: Follow procedures to setup Unified tracking and connect your Event collection to your destinations.
  • API Group Creation: In the Engagement project, generate a new API group, set permissions, and securely store the generated credentials necessary for integration
  • Module Activation: Engage the appropriate modules in the Engagement Dashboard. Modules like brx_Discovery, brx_merchandising, and brx_Content must be activated for segmented functionalities
  • Engagement to Discovery Linking: Synchronize Engagement project settings with Discovery CMS following specific guidelines to avoid configuration errors

Validation and Quality Assurance

  • Post-Setup Validation: After exposing segments, immediately verify their availability in the Discovery tool. Utilize the API for confirming segment data and check conditions ensuring user cookies align with segment criteria.
  • Segment Learning Verification: Use several methods to check if segment learning is ongoing, including querying specific folders and observing interaction metrics

Debugging and Testing

  • JavaScript Tools: Implement specific JavaScript snippets to debug cookie behaviors and analyze segment allocations interactively

Additional Notes

  • Adjust the learning period for pixels based on client needs, ensuring that the training data is gathered suitably. A training period of 30 days is standard, but this may be reduced under certain conditions.
  • Careful attention is needed in changing settings across environments to ensure no mix-ups occur, especially concerning related API credentials.

Chrome extension

Previously the Exponea Console provided this functionality as a browser extension. Now, it will be available in a Web Store link.

Read more here: Exponea Console

📘

Note

This extension won’t have the validation capabilities that are now present in the Discovery Pixel Validator Chrome extension.

Updated 5 months ago