This article describes how to access exposed segmentations from Engagement JS SDK. It doesn't cover the exposing feature itself or explain how the exposed segments should be passed to other systems, its primary focus is on the programmable interface of the Engagement JS SDK. The objective is to provide integration engineers with a guide on how to utilize the provided functions and what behavior to expect.

📘

Requirements

This feature is available in:

• js-sdk v3.5.0 or higher
• js-snippet v2.5.0 or higher

Exposing segmentations from Bloomreach Engagement to Bloomreach Content or Bloomreach Discovery (Search and Merchandising features) requires meeting specific requirements. For any queries, please, contact your Bloomreach Account manager.

Engagement JS SDK

getSegments method

This method is an asynchronous getter with a callback mechanism.

window.exponea.getSegments(  
   exposingCategory,  
   successCallback,  
   errorCallback,  
   options  
)

Parameters

• exposingCategory: a string defining the exposing category of your interest: “content”, “discovery”, or “merchandising”.
• successCallback: the function executed when segmentations for a given exposing category were successfully fetched.
  • segmentsDefinition: an array of objects with the definition of all exposed segmentations, segments for a given category, and current end customer

[  
  {  
    id: "id of segments current end customer fits in"  
    segmentation_id: "id of exposed segmentations."  
  }  
]

• errorCallback: the function executed when an error occurs while gathering the exposed segmentations from the backend.
• options: a configuration options object
  • force: a boolean enforcing the fetching from the server even if the exposed segmentations were already fetched previously.

Return Value

This function has no return value.

segments.subscribe method

Designed for situations where you need to take action whenever there is a change in the segments a customer fits into, the method eliminates the need to wait for page refresh or navigation changes to execute the code again.

By calling the subscribe method multiple times with the same successCallback reference, you can create multiple subscribers. Each subscription has its own subscription object that can be canceled individually.

window.exponea.segments.subscribe(  
   exposingCategory,   successCallback,  
   errorCallback  
)

Parameters

• exposingCategory: a string defining the exposing category of your interest: “content”, “discovery”, or “merchandising”.
• successCallback: the function executed when segmentations or segments change, i.e. not each time they're fetched, only when a change in returned values is detected.
  • segmentsDefinition: an array of objects with the definition of all exposed segmentations, segments for a given category, and current end customer

[  
  {  
    id: "id of segments current end customer fits in"  
    segmentation_id: "id of exposed segmentations"  
  }  
]

• errorCallback: the function executed when an error occurs while gathering the exposed segmentations from the backend.

Return Value

The subscribe method returns a subscription object that includes an unsubscribe method.

subscription = {  
	unsubscribe: function() {}  
}

Required changes in Engagement JS SDK configuration

The underlying subscribe/notify mechanism has to be explicitly enabled in the JS SDK configuration by setting the exposed_segments.notify to true.

var sdkConfig = {  
  ...  
  exposed_segments: {  
    notify: true  
  }  
  ...  
}

Related configuration options

There is a separate section, exposed_segments, in the JS SDK configuration object related to this feature.

var sdkConfig = {  
  ...  
  exposed_segments: {  
    prefetch: false,  
    notify: false  
  }  
  ...  
}

prefetch

• Default value: false

By setting this option to true, the JS SDK will pre-fetch exposed segmentations as part of the initialization process, regardless of whether the getSegments function is called later or not at all on the page. When true, the segments will be re-fetched whenever the end customer's identity changes, i.e. when identify, anonymize, or linkCookie methods are called.

notify

• Default value: false

By setting this option to true, the JS SDK will re-fetch exposed segmentations whenever changes in the segments that the end customer fits into are anticipated due to JS SDK tracked events. This will work for subscribe or notify only when set to true.

FAQ

What will happen when you call multiple getSegments with various exposing categories?

If the force option is not set to true, there will be a single call to the backend. The backend will respond with all exposed segmentations and their associated segments for all exposing categories. The filtering of segments will then occur solely on the client side.

How can I get segments for multiple exposing categories at once?

While native methods do not offer a direct solution, you can wrap the getSegments function in a promise and utilize Promise.all for achieving the desired outcome:

function getSegmentsPromise(category) {  
    return new Promise((resolve, reject) => {  
        try {  
            window.exponea.getSegments(  
              category,  
              (result) => {  
                resolve(result);  
              },  
              (error) => reject(error);  
              );  
        } catch (error) {  
            reject(error);  
        }  
    });  
}

const combinedSegments = [  
  ...(await getSegmentsPromise('content')),  
  ...(await getSegmentsPromise('discovery'))  
]  
const combinedSegmentsUniqueBySegmentationId = Object.values(  
  [  
    ...(await getSegmentsPromise('content')),  
    ...(await getSegmentsPromise('discovery'))  
  ].reduce(  
    (acc,cur) => {  
      acc[cur.segmentation_id] = cur;  
      return acc  
  }, {})  
)

Will the subscribe/notify mechanism be triggered when:

• the segmentations have changed due to events tracked (or imported) in parallel from other channels/sessions?

• the definition of segmentations changes on the engagement backend?

• a new segment is exposed from the engagement backend?

The subscribe/notify mechanism functions by re-fetching segments from the server based on tracked events on the client side. It does not rely on a "push" mechanism from the server to the client for propagating newly exposed segments or modified segmentations.

Using the subscribe/notify mechanism, you ensure that you always receive the most up-to-date segments and segmentations whenever the client detects potential changes. The getSegments method provides fresh data during page refresh or navigation events.