Calling the Recommendations APIs

📘
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.

Calling the Recommendations APIs - Android

📘
Integration Prerequisite

Setup

Add the dependency

Initialization

Triggering the APIs

Item-based Recommendation Widget API

Category-based Widget API

Keyword-based Widget API

Personalization-based Widget API

Global Recommendation Widget API

📘Integration Prerequisite

Setup

Add the dependency

Initialization

Triggering the APIs

Item-based Recommendation Widget API

Category-based Widget API

Keyword-based Widget API

Personalization-based Widget API

Global Recommendation Widget API

📘
Integration Prerequisite