Android SDK - Search and Category 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

Product Search API

Create the object of ProductSearchRequest for the request parameter to be passed to the Product Search API with different types of fields supported.

val productSearchRequest = ProductSearchRequest()
  .fl(listOf(
    "pid",
    "title",
    "brand",
    "price"
    )
  )
  .searchTerm("test")
  .fq("color", listOf("blue", "red"))
  .efq(attribute= "Fabric", values = listOf("Cotton", "Linen"), operator= Operator.OR)
  .sort(Sort("price", SortOrder.ASCENDING))
ProductSearchRequest productSearchRequest = new ProductSearchRequest()
   .fl(Arrays.asList(
     "pid",
     "title",
     "brand",
     "price"
   ))
   .searchTerm("test");

Then call the productSearchApi method in BrApi, and pass the request object along with a callback listener instance. The results get captured in the callback method as either success or failure.

BrApi.productSearchApi(productSearchRequest, brApiCompletionListener = object :
  BrApiCompletionListener {
  override fun onBrApiSuccess(response: Any) {
    if (response is CoreResponse) {
      //gets required response in response object of type CoreResponse
    }
  }
    
  override fun onBrApiFailure(error: BrApiError) {
    // if the API fails, handle error here.
  }
})
BrApi.INSTANCE.productSearchApi(productSearchRequest, new BrApiCompletionListener() {
  @Override
  public void onBrApiSuccess(@NonNull Object response) {
    if(response instanceof CoreResponse) {
      //gets required response in response object of type CoreResponse
    }
  }

  @Override
  public void onBrApiFailure(@NonNull BrApiError error) {
    // if the API fails, handle errors here.
  }
});

Supported parameters for creating the ProductSearchRequest object:

ParameterDescriptionMethod calls
rowsThe number of matching items to return per results page in the API response. The maximum value is 200..rows(10)
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..start(0)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(“example.com”)
flThe attributes that you want to be returned in your API response, such as product IDs and prices.

All fl parameters for Product Search or Category requests must include pid as one of their values. Any attribute from your product feed may be used as a value for fl.
Can be set in the following ways:

.fl(“pid,title”)

.fl(listOf(“pid”, “title”))

.fl(arrayOf(“pid”, “title”))
searchTermThe query text..searchTerm(“test”)
fqThe fq parameter applies a faceted filter to the returned products, searching for products that fit your parameter values..fq("color:"red"")

.fq("color", listOf("blue", "red"))

.fq("color", "red")
stats.fieldThis parameter allows you to display the maximum and minimum values of any numeric field in your data set for a user query..statsField("sale_price,length,width")

.statsField(
listOf(
"sale_price",
"length",
"width"
)
)

.statsField(
arrayOf(
"sale_price",
"length",
"width"
)
)
efqThe efq parameter applies a complex boolean filter to search results to include or exclude items that fit your parameter values.efq(“attribute:(\“value\”)”)

efq(attribute= "Fabric", value= “Cotton”)

//efq with NOT
.efq(attribute= "Fabric", value= “Cotton”, isNot=true)

//single attribute multiple values

.efq(attribute= "Fabric", values = listOf("Cotton", "Linen"), operator= Operator.OR)

//multiple attributes with operator
.efq(values = mapOf("Fabric" to "Cotton", "Color" to "Red"), operator= Operator.AND)
facet.rangeReturn a count of ranged facets, such as price and sale price. Use numeric attributes only.

You need to parse the values that are in the facets_counts section of the response. The facet_queries section has custom range facets for numeric fields that you define in your request.

In the case of the V3 Facet format, the facets object gives you both numeric and text facets that you can display to your site's users.

In the case of the Legacy Facet format, the facet_fields section gives you facets that you can display to your site's users, such as brands and colors.

Note: Customers whose go-live date is after September 7, 2023, will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.
.facetRange(“price”)

.facetRange(listOf("price","rating"))
facet.prefixThe facet.prefix parameter limits faceting to terms that start with the specified string prefix..facetPrefix(facetName = “brand”, prefixValue = “c”)

//FOR WIDGET API
facetPrefixWidget(facetName = “”, prefixValue = “”)
sortYou can alter the sequence in which products are displayed by passing the sort parameter.//using simple string
.sort("price+asc")

//using Sort Object
.sort(Sort("price", SortOrder.ASCENDING))

//multiple sorts
.sort(listOf(Sort("reviews", SortOrder.ASCENDING), Sort("price", SortOrder.DESCENDING)))

//multiple sort with String
.sort(arrayOf("reviews+desc", "sale_price+desc"))
user_idThe universal customer ID of the user..userId(“usr123”)
view_idA 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. You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog.
.viewId(“”)
widget_idThe widget_id provided in the Dashboard for the Dynamic Widgets feature, which is used to provide curated results..widgetId(“widget123”)

BOPIS

ParameterDescriptionMethod calls
llBOPIS-specific parameter to specify the end-customer's latitude-longitude..latLong(“38.880657,-77.396935”)
flReturns the distance from the point specified in the ll parameter..fl(“store_lat_lon,pid,title”)
fqAllows filtering by distance from the point specified in the ll parameter..fq("store_lat_lon:"100"")

Category Search API

Create the object of CategorySearchRequest for the request parameter to be passed to the Category search API with different types of fields supported.

val categorySearchRequest = CategorySearchRequest()
  .fl(
    listOf(
      "pid",
      "title",
      "brand",
      "price"
    )
  )
  .searchTerm("test")

Then, call the categorySearchApi method in BrApi, and pass the request object along with callback listener instance. The results gets captured in callback method as either success or failure.

BrApi.categorySearchApi(categorySearchRequest, brApiCompletionListener = object :
  BrApiCompletionListener {
  override fun onBrApiSuccess(response: Any) {
    if (response is CoreResponse) {
      //gets required response in response object of type CoreResponse
    }
  }

  override fun onBrApiFailure(error: BrApiError) {
    // if the API fails, handle error here.
  }
  
  })
}

Note: The Parameters for creating the object are same as the ones mentioned in Product Search API above.

Content Search API

Create the object of ContentSearchRequest for the request parameter to be passed to the Content search API with different types of fields supported.

val contentSearchRequest = ContentSearchRequest()
  .fl(
    listOf(
      "pid",
      "title",
      "brand",
      "price"
    )
  )
  .catalogName("Chair")
  .searchTerm("test")

Then, call the contentSearchApi method in BrApi, and pass the request object along with callback listener instance. The results gets captured in callback method as either success or failure.

BrApi.contentSearchApi(contentSearchRequest, brApiCompletionListener = object :
  BrApiCompletionListener {
  override fun onBrApiSuccess(response: Any) {
    if (response is CoreResponse) {
      //gets required response in response object of type CoreResponse
    }
  }

  override fun onBrApiFailure(error: BrApiError) {
    // if the API fails, handle error here.
  }})
}

Supported parameters for creating the ContentSearchRequest object:

ParameterDescriptionMethod call
catalog_nameNamed identifier of the catalog. A catalog is a grouping of items into a broader category such as blogs, videos, etc. A catalog is a representation of a group of items and must have a unique name, that is also unique to a domain (if you have multiple sites).

Catalogs are created in the DataConnect UI by default, you can rename the catalogs when you set up your catalogs initially.
.catalogName(“catNamee”)

Note: Rest of the parameters for creating the object are same as the ones mentioned in Product Search API above.

Bestseller API

Create the object of BestSellerRequest for the request parameter to be passed to the BestSeller API with different types of fields supported.

val bestSellerRequest = BestSellerRequest()
  .fl(
    listOf(
      "pid",
      "title",
      "brand",
      "price"
    )
  )
  .searchTerm("test")

Then, call the bestSellerApi method in BrApi, and pass the request object along with callback listener instance. The results gets captured in callback method as either success or failure.

BrApi.bestSellerApi(bestSellerRequest, brApiCompletionListener = object :
  BrApiCompletionListener {
  override fun onBrApiSuccess(response: Any) {
    if (response is CoreResponse) {
      //gets required response in response object of type CoreResponse
    }
  }

  override fun onBrApiFailure(error: BrApiError) {
    // if the API fails, handle error here.
  }
})

Supported parameters for creating the BestSellerRequest object:

ParameterDescriptionMethod call
titleThe title or name of the product..title(“productName”)

Note: Rest of the parameters for creating the object are same as the ones mentioned in Product Search API above.

Autosuggest API

Create the object of AutosuggestRequest for the request parameter to be passed to the Autosuggest API with different types of fields supported.

val autoSuggestRequest = AutosuggestRequest()
  .catalogViews(mapOf("product" to "store", "p1" to "sq"))

Then, call the autoSuggestApi method in BrApi, and pass the request object along with callback listener instance. The results gets captured in callback method as either success or failure.

BrApi.autoSuggestApi(autoSuggestRequest, brApiCompletionListener = object :
   BrApiCompletionListener {
   override fun onBrApiSuccess(response: Any) {
     if (response is SuggestResponse) {
       //gets required response in response object of type CoreResponse
     }
   }

   override fun onBrApiFailure(error: BrApiError) {
     // if the API fails, handle error here.
   }

})

Supported parameters for creating the AutosuggestRequest object:

ParameterDescriptionMethod calls
catalog_viewsA list of catalog views that you want to see in your suggestions. You must specify the catalog name within the catalog view. For Product catalogs, the catalog name is the same value as your domain_key.

A catalog_views value contains the view_ids within a catalog separated by a colon. If you pass multiple catalogs in catalog_views, they must be pipe-separated. Attributes suggestions are enabled for the first two catalogs mentioned as part of catalog_views and only for the first view passed in each of the first two catalogs.
.catalogViews(“product:store1|p1:s1”)

.catalogViews(mapOf("product" to "store", "p1" to "s1"))
qYour site visitor's partial search query that Autosuggest should operate on..searchTerm(“test”)
user_agentThe user agent of the browser that's making the search request..userAgent(“”)
user_idThe universal customer ID of the user..userId(“”)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(“example.com”)