Calling the Recommendations APIs - Android
Integration Prerequisite
The version of the Android SDK used in your application should be 24 or above.
Setup
To set up the SDK before using, complete the following steps:
Add the dependency
If you have already integrated Pixels using the SDK before, there is no need to add any additional dependencies.
If not, you can follow the steps given here to add the dependency.
Initialization
In order to initialize the API SDK with your credentials at the start of the application, call the following method at the launch point.
First, Create a BrApiRequest
object with the parameters given below:
val brApiRequest = BrApiRequest(
accountId = "<ACCOUNT_ID>",
uuid = β<Device_UUID>β,
visitorType = VisitorType.NEW_USER,
domainKey = β<DOMAIN_KEY>β,
authKey = "NO_AUTH",
userId = "<USER_ID>",
environment = Env.STAGE
)
BrApiRequest brApiRequest = new BrApiRequest(
"<ACCOUNT_ID>",
"<UUID>",
VisitorType.NEW_USER,
"<DOMAIN_KEY>",
"NO_AUTH",
"<USER_ID>",
Env.STAGE
);
Then initialize the BrApi
class with BrApiRequest
object:
BrApi.init(brApiRequest)
BrApi.INSTANCE.init(brApiRequest);
Parameter | Description |
---|---|
accountId | Your account identifier provided by Bloomreach |
uuid | A 13-digit random number |
visitorType | ENUM type for New User or Returning User |
domainKey | Your site domain's ID, which is provided by Bloomreach |
authKey | The Bloomreach-provided authentication key for the Bloomreach account that's sending the request |
userId | The universal customer ID of the user |
environment | ENUM to specify APIs to be pointed to which environment. STAGE or PROD. Defaulted to STAGE |
Triggering the APIs
Item-based Recommendation Widget API
- Create the
WidgetRequest
object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
.itemIds("1234")
Parameter | Description | Method call |
---|---|---|
item_ids | Specifies access to a particular set of items. For product catalog, this would be the PID(s). | .itemIds(β1234β) .itemIds(listOf(β1234β, β98765β)) .itemIds(arrayOf(β1234β, β98765β)) |
url | The absolute URL of the page where the request is initiated. Do not use a relative URL. | .url(βexample.comβ) |
context_id | context_id takes a single product ID for producing Context-based merchandising results for the widget. Contextual Merchandising uses Context ID as a primary input for generating the recall set of the widget results. In the event that not enough results are produced based on context_id, the system depends on Item ID(s) as a fallback to fill the recall set of the widget. | .contextId(βtestβ) |
fields | A comma-separated list of fields to be sent in the request. | .fields(βf1,f2β) .fields(listOf(βf1β, βf2β)) .fields(arrayOf(βf1β, βf2β)) |
filter | The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your feed. Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results. | filter(ββ) .filter("price", 10.. 100, true) .filter("fabric", listOf("cotton", "linen"), Operator.AND) .filter("fabric", listOf("cotton", "linen"), Operator.OR) .filter("fabric", listOf("cotton"), Operator.OR) //multple filter .filter("fabric", listOf("cotton, linen"), Operator.OR) .filter("price", 10, 100, true) .filter("color_groups", "blue", true) |
rows | The number of matching items to return per results page in the API response. The maximum value is 200. The result size is used from the Dashboard if it is not sent in the API. | .rows(100) |
user_id | The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. | .userId("test123") |
viewId | A unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views. | .viewid(ββ) |
- To make the API call, use the following code snippet and pass the following parameters:
BrApi.itemBasedRecommendationWidgetApi("2l726795", widgetRequest, brApiCompletionListener = object : BrApiCompletionListener {
override fun onBrApiSuccess(response: Any) {
if (response is RecsAndPathwaysResponse) {
//gets required response in response object of type RecsAndPathwaysResponse
}
}
override fun onBrApiFailure(error: BrApiError) {
// if the API fails, handle error here.
}
})
Parameter | Description |
---|---|
widgetId | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
widgetRequest | Request object which contains parameters to be passed to API. |
brApiCompletionListener | Instance BrApiCompletionListener interface, which receives callback when API succeeds or fails. |
Category-based Widget API
- Create the
WidgetRequest
object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
.catId("1234")
Parameter | Description | Method call |
---|---|---|
cat_id | Your site's category ID. | .catId(β1234β) |
url | The absolute URL of the page where the request is initiated. Do not use a relative URL. | .url(βexample.comβ) |
facet | Facets are disabled by default. To enable facets, set facet=true. | .facet(true) |
filter_facet | With the filter parameter, after a user selects a facet value for filtering, the other facet values in that field are not returned by the API and are no longer visible. The filter_facet parameter allows other facet values to be returned after a facet value has been selected. | .filterFacet("color:"red"") .filterFacet("color", "red") .filterFacet("color", listOf("red", "blue"), Operator.OR) |
fields | A comma-separated list of fields to be sent in the request. | .fields(βf1,f2β) .fields(listOf(βf1β, βf2β)) .fields(arrayOf(βf1β, βf2β)) |
filter | The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your feed. Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results. | .filter(ββ) .filter("price", 10.. 100, true) .filter("fabric", listOf("cotton", "linen"), Operator.AND) .filter("fabric", listOf("cotton", "linen"), Operator.OR) .filter("fabric", listOf("cotton"), Operator.OR) //multple filter .filter("fabric", listOf("cotton, linen"), Operator.OR) .filter("price", 10, 100, true) .filter("color_groups", "blue", true) |
start | The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0. The maximum value is 10000. | .start(0) |
rows | The number of matching items to return per results page in the API response. The maximum value is 200. The result size is used from the Dashboard if it is not sent in the API. | .rows(100) |
user_id | The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. | .userId() |
viewId | A unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views. | .viewid(ββ) |
- To make the API call, use the following code snippet and pass the following parameters:
BrApi.categoryBasedWidgetApi("2l726795", widgetRequest, brApiCompletionListener = object : BrApiCompletionListener {
override fun onBrApiSuccess(response: Any) {
if (response is RecsAndPathwaysResponse) {
//gets required response in response object of type RecsAndPathwaysResponse
}
}
override fun onBrApiFailure(error: BrApiError) {
// if the API fails, handle error here.
}
})
Parameter | Description |
---|---|
widgetId | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
widgetRequest | Request object which contains parameters to be passed to API. |
brApiCompletionListener | Instance BrApiCompletionListener interface, which receives callback when API succeeds or fails. |
Keyword-based Widget API
- Create the
WidgetRequest
object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
.query("cap")
Parameter | Description | Method call |
---|---|---|
query | Your site visitor's search query. Search queries are composed of one or more terms. | .query(βcapβ) |
Note: Rest of the parameters are the same as mentioned for Category-based Widget API above.
- To make the API call, use the following code snippet and pass the following parameters:
BrApi.keywordBasedWidgetApi("2l726795", widgetRequest, brApiCompletionListener = object : BrApiCompletionListener {
override fun onBrApiSuccess(response: Any) {
if (response is RecsAndPathwaysResponse) {
//gets required response in response object of type RecsAndPathwaysResponse
}
}
override fun onBrApiFailure(error: BrApiError) {
// if the API fails, handle error here.
}
})
Parameter | Description |
---|---|
widgetId | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
widgetRequest | Request object which contains parameters to be passed to API. |
brApiCompletionListener | Instance BrApiCompletionListener interface, which receives callback when API succeeds or fails. |
Personalization-based Widget API
- Create the
WidgetRequest
object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
.query("cap")
.userId(βu123β)
Parameter | Description | Method call |
---|---|---|
user_id | The universal customer ID of the user. Required for Personalization-based Recommendation widgets. The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. | .userId("abc123") |
query | Your site visitor's search query. Search queries are composed of one or more terms. | .query(βcapβ) |
Note: Rest of the parameters are the same as mentioned for Item-based Recommendation Widget API above.
- To make the API call, use the following code snippet and pass the following parameters:
BrApi.personalizationBasedWidgetApi("2l726795", widgetRequest, brApiCompletionListener = object : BrApiCompletionListener {
override fun onBrApiSuccess(response: Any) {
if (response is RecsAndPathwaysResponse) {
//gets required response in response object of type RecsAndPathwaysResponse
}
}
override fun onBrApiFailure(error: BrApiError) {
// if the API fails, handle error here.
}
})
Parameter | Description |
---|---|
widgetId | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
widgetRequest | Request object which contains parameters to be passed to API. |
brApiCompletionListener | Instance BrApiCompletionListener interface, which receives callback when API succeeds or fails. |
Global Recommendation Widget API
- Create the
WidgetRequest
object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
Note: The parameters are the same as mentioned for Item-based Recommendation Widget API above.
- To make the API call, use the following code snippet and pass the following parameters:
BrApi.globalRecommendationWidgetApi("2l726795", widgetRequest, brApiCompletionListener = object : BrApiCompletionListener {
override fun onBrApiSuccess(response: Any) {
if (response is RecsAndPathwaysResponse) {
//gets required response in response object of type RecsAndPathwaysResponse
}
}
override fun onBrApiFailure(error: BrApiError) {
// if the API fails, handle error here.
}
})
Parameter | Description |
---|---|
widgetId | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
widgetRequest | Request object which contains parameters to be passed to API. |
brApiCompletionListener | Instance BrApiCompletionListener interface, which receives callback when API succeeds or fails. |
Updated 4 months ago