Android SDK - Recommendations and Pathways 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 the Pixel SDK, 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);
ParameterDescription
accountIdYour account identifier provided by Bloomreach
uuidA 13-digit random number
visitorTypeENUM type for New User or Returning User
domainKeyYour site domain's ID, which is provided by Bloomreach
authKeyThe Bloomreach-provided authentication key for the Bloomreach account that's sending the request
userIdThe universal customer ID of the user
environmentENUM to specify APIs to be pointed to which environment. STAGE or PROD.
Defaulted to STAGE

Triggering the APIs

Item-based Recommendation Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
  .itemIds("1234")
ParameterDescriptionMethod call
item_idsSpecifies 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”))
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(β€œexample.com”)
context_idcontext_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”)
fieldsA comma-separated list of fields to be sent in the request..fields(β€œf1,f2”)

.fields(listOf(β€œf1”, β€œf2”))

.fields(arrayOf(β€œf1”, β€œf2”))
filterThe 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)
rowsThe 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_idThe 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")
viewIdA 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(β€œβ€)
  1. 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.
  }
})
ParameterDescription
widgetIdThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.
widgetRequestRequest object which contains parameters to be passed to API.
brApiCompletionListenerInstance BrApiCompletionListener interface, which receives callback when API succeeds or fails.

Category-based Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
  .catId("1234")
ParameterDescriptionMethod call
cat_idYour site's category ID..catId(β€œ1234”)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(β€œexample.com”)
facetFacets are disabled by default. To enable facets, set facet=true..facet(true)
filter_facetWith 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)
fieldsA comma-separated list of fields to be sent in the request..fields(β€œf1,f2”)

.fields(listOf(β€œf1”, β€œf2”))

.fields(arrayOf(β€œf1”, β€œf2”))
filterThe 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)
startThe 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)
rowsThe 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_idThe 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()
viewIdA 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(β€œβ€)
  1. 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.
  }
})
ParameterDescription
widgetIdThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.
widgetRequestRequest object which contains parameters to be passed to API.
brApiCompletionListenerInstance BrApiCompletionListener interface, which receives callback when API succeeds or fails.

Keyword-based Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
  .query("cap")
ParameterDescriptionMethod call
queryYour 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.

  1. 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.
  }
})
ParameterDescription
widgetIdThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.
widgetRequestRequest object which contains parameters to be passed to API.
brApiCompletionListenerInstance BrApiCompletionListener interface, which receives callback when API succeeds or fails.

Personalization-based Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
val widgetRequest = WidgetRequest()
  .query("cap")
    .userId(β€œu123”)
ParameterDescriptionMethod call
user_idThe 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")
queryYour 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.

  1. 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.
  }
})
ParameterDescription
widgetIdThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.
widgetRequestRequest object which contains parameters to be passed to API.
brApiCompletionListenerInstance BrApiCompletionListener interface, which receives callback when API succeeds or fails.

Global Recommendation Widget API

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

  1. 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.
  }
})
ParameterDescription
widgetIdThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.
widgetRequestRequest object which contains parameters to be passed to API.
brApiCompletionListenerInstance BrApiCompletionListener interface, which receives callback when API succeeds or fails.