Segmentation
Implement Real-Time Segments using the Android SDK
The Real-Time Segments feature personalizes the product search, category and pathway results in real-time based on customer demographic and behavioral data. The feature combines Bloomreach Discovery’s extensive search algorithms and Bloomreach Engagement’s rich customer data to get the best of both worlds.
Refer to the Discovery Real-Time Segments documentation for more details about this feature.
This page describes the integration steps required to retrieve any segmentation data changes assigned to the current customer.
Use Real-Time Segments
To use real-time segments in your app, you must register one or more customized SegmentationDataCallback
instances.
Each instance must define the following three items:
- A
exposingCategory
indicating your point of interest for segmentation:- Possible values are
content
,discovery
, ormerchandise
. You will get updates only for segmentation data assigned to the specifiedexposingCategory
.
- Possible values are
- A boolean flag
includeFirstLoad
to force a fetch of segmentation data:- Setting this flag to
true
triggers a segmentation data fetch immediately. - The SDK will notify this callback instance with the new data even if the data has not changed from the last known state.
- If the data has changed, the SDK will also notify any other registered callbacks.
- Setting this flag to
false
also triggers a segmentation data fetch, but the SDK only notifies the instance if the new data differs from the last known state.
- Setting this flag to
- A handler method
onNewData
for new segmentation data:- The method will receive all segmentation data for
exposingCategory
assigned to the current customer. - The data are provided as a list of
Segment
objects; eachSegment
containsid
andsegmentation_id
values.
- The method will receive all segmentation data for
Example
Exponea.registerSegmentationDataCallback(object : SegmentationDataCallback() {
override val exposingCategory = "discovery"
override val includeFirstLoad = true
override fun onNewData(segments: List<Segment>) {
Logger.i(this, "Segments: Got new segments: $segments")
}
})
The data payload of each Segment
is as follows:
{
"id": "66140257f4cb337324209871",
"segmentation_id": "66140215fb50effc8a7218b4"
}
Get Segmentation Data Directly
The SDK provides an API to get segmentation data directly. Invoke the Exponea.getSegments
method, passing a exposingCategory
value as argument:
Exponea.getSegments(exposingCategory = exposingCategory) { segments ->
Logger.i(this, "Segments: Got new segments: $segments")
}
Segments data received by getSegments
method are primary loaded from valid cache. Cache is automatically fetched from server if:
- cache is empty or was loaded for previous customer
- cache data are older than 5 seconds
- method is forced to fetch segments from server by developer
If you want to force to fetch segmentations data from server, use force
parameter with true
value as argument:
Exponea.getSegments(exposingCategory = exposingCategory, force = true) { segments ->
Logger.i(this, "Segments: Got new segments: $segments")
}
The
getSegments
method loads segmentation data for the requestedcategory
and the current customer as identified byExponea.identifyCustomer
. Please bear in mind that the callback is invoked in a background thread.
Segmentation Data Reload Triggers
There are a few cases when the SDK refreshes segmentation data, and this process could occur multiple times. However, the SDK only notifies registered callbacks if the data have changed or if includeFirstLoad
is true
. Refer to Callback Behavior for more details about the callback notification process.
A data reload is triggered in the following cases:
- When a callback instance is registered while the SDK is fully initialized.
- During SDK initialization if there is any callback registered.
- When
Exponea.identifyCustomer
is called with a hard ID. - When any event is tracked successfully.
When a segmentation data reload is triggered, the process waits 5 seconds before starting, in order to ensure duplicate update requests especially for higher frequency of events tracking.
It is required to set
Exponea.flushMode
toIMMEDIATE
to get accurate results. The process of segment calculation needs all tracked events to be uploaded to server to calculate results effectively.
Callback Behavior
The SDK allows you to register multiple SegmentationDataCallback
instances for multiple categories or for the same category. You may register a callback with the SDK anytime (before and after initialization). Callback instances remain active until the application terminates or until you unregister the callback.
The callback behavior follows the following principles:
- A callback receives data assigned only for the specified
exposingCategory
. - A callback is always notified if data differs from the previous reload in the scope of the specified
exposingCategory
. - A newly registered callback is also notified for unchanged data if
includeFirstLoad
istrue
, but only once. On subsequent updates, the callback is notified only if the data have changed. - A deregistered callback stops listening for data changes.
- A callback is always notified in a background thread.
Consider keeping the number of callbacks within a reasonable value.
Deregister a Callback
Deregistration of a callback instance is up to the developer. If you don't deregister a callback instance, the SDK will keep it active until the application terminates.
To deregister callback successfully, call
Exponea.unregisterSegmentationDataCallback
with the callback instance you already registered, otherwise the callback will not be unregistered.
val segmentCallbackInstance = object : SegmentationDataCallback() {
override val exposingCategory = "discovery"
override val includeFirstLoad = true
override fun onNewData(segments: List<Segment>) {
Logger.i(this, "Segments: Got new segments: $segments")
}
}
Exponea.registerSegmentationDataCallback(segmentCallbackInstance)
// you have to keep segmentCallbackInstance
Exponea.unregisterSegmentationDataCallback(segmentCallbackInstance)
A callback can deregister itself with segmentCallbackInstance.unregister()
as a shortcut to Exponea.unregisterSegmentationDataCallback(segmentCallbackInstance)
. Deregistering a callback is effective immediately.
Listen to Multiple Segmentation Categories
Although a SegmentationDataCallback
allows only one exposingCategory
, you can register multiple callbacks for multiple categories. As the SDK notifies all registered callbacks in a background thread, you may provide a collector of changed values.
val dataCollector = MutableLiveData<Pair<String, List<Segment>>>()
Exponea.registerSegmentationDataCallback(object : SegmentationDataCallback() {
override val exposingCategory = "discovery"
override val includeFirstLoad = false
override fun onNewData(segments: List<Segment>) {
dataCollector.postValue(Pair(exposingCategory, segments))
}
})
Exponea.registerSegmentationDataCallback(object : SegmentationDataCallback() {
override val exposingCategory = "merchandise"
override val includeFirstLoad = false
override fun onNewData(segments: List<Segment>) {
dataCollector.postValue(Pair(exposingCategory, segments))
}
})
dataCollector.observeForever {
Logger.i(this, "New data arrived! Category is ${it.first} with values ${it.second}")
// will produce example log "New data arrived! Category is discovery with values [{"id": "66140257f4cb337324209871", "segmentation_id": "66140215fb50effc8a7218b4"}]"
}
Troubleshooting
Enable Verbose Logging
The SDK logs a lot of useful information related to segmentation data updates on the
VERBOSE
level. You can set the logger level usingExponea.logger.logLevel
before initializing the SDK.
All log messages related to the segmentation process are prefixed with
Segments:
to make them easier to find. Bear in mind that some supporting processes (such as HTTP communication) are logging without this prefix.
The process of updating segmentation data may be canceled due to the current state of the SDK. Segmentation data are assigned to the current customer and the process is active only if there are any callbacks registered. The SDK logs information about all these validations.
Log Messages
If you are not receiving segmentation data updates, you may see the following log messages:
-
The SDK tracked an event successfully but there is no registered callback for segments. Please register at least one callback.Segments: Skipping segments update process after tracked event due to no callback registered
-
The SDK starts an update of segmentation data after a callback registration but this callback is missing while processing. Please ensure that you don't deregister the callback prematurely.Segments: Adding of callback triggers fetch for no callbacks registered
-
The SDK is trying to reload segmentation data but there is no registered callback for segments. Please register at least one callback.Segments: Skipping segments reload process for no callback
-
The SDK initialization flow tries to reload segmentation data but there is no registered callback for segments. To check segmentation data on SDK initialization, please register at least one callback before SDK initialization.Segments: Skipping initial segments update process for no callback
-
The SDK initialization flow detects that all registered callbacks haveSegments: Skipping initial segments update process as is not required
includeFirstLoad
withfalse
value. To check segmentation data on SDK initialization, please register at least one callback withincludeFirstLoad
withtrue
value before SDK initialization.
If you are not receiving segmentation data while registering a customer, please check your usage of ExponeaExponea.shared.identifyCustomer
or Exponea.shared.anonymize
. You may face these logs:
-
The segmentation data update process started but was subsequently canceled by an invocation ofSegments: Segments change check has been cancelled meanwhile
Exponea.shared.anonymize
. If this is unwanted behavior, check yourExponea.shared.anonymize
usage. -
The segmentation data update process started for the current customer but the customer ID was subsequently changed by an invocation ofSegments: Check process was canceled because customer has changed
Exponea.shared.identifyCustomer
for another customer. If this is unwanted behaviour, check yourExponea.shared.identifyCustomer
usage. -
The segmentation data update process requires to link IDs but that part of the process failed. Please refer to the error log messages and check yourSegments: Customer IDs <customer_ids> merge failed, unable to fetch segments
Exponea.identifyCustomer
usage. This should not happen, please discuss this with the Bloomreach support team. -
The segmentation data update process detects that data has been fetched for a previous customer. This should not lead to any problem as there is another fetch process registered for the new customer, but you may face a short delay for new data retrieval. If you see this log often, check yourSegments: New data are ignored because were loaded for different customer
Exponea.shared.identifyCustomer
usage. -
Please read the error message carefully. This message is logged if the data retrieval failed for some technical reason, such as an unstable network connection.Segments: Fetch of segments failed: <error message>
Updated 10 days ago