Calling the Search 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
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:
Parameter | Description | Method calls |
---|---|---|
rows | The number of matching items to return per results page in the API response. The maximum value is 200. | .rows(10) |
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. | .start(0) |
url | The absolute URL of the page where the request is initiated. Do not use a relative URL. | .url(“example.com”) |
fl | The 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”)) |
searchTerm | The query text. | .searchTerm(“test”) |
fq | The 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.field | This 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" ) ) |
efq | The 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.range | Return 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.prefix | The 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 = “”) |
sort | You 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_id | The universal customer ID of the user. | .userId(“usr123”) |
view_id | 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. 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_id | The widget_id provided in the Dashboard for the Dynamic Widgets feature, which is used to provide curated results. | .widgetId(“widget123”) |
BOPIS
Parameter | Description | Method calls |
---|---|---|
ll | BOPIS-specific parameter to specify the end-customer's latitude-longitude. | .latLong(“38.880657,-77.396935”) |
fl | Returns the distance from the point specified in the ll parameter. | .fl(“store_lat_lon,pid,title”) |
fq | Allows 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:
Parameter | Description | Method call |
---|---|---|
catalog_name | Named 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:
Parameter | Description | Method call |
---|---|---|
title | The 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:
Parameter | Description | Method calls |
---|---|---|
catalog_views | A 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")) |
q | Your site visitor's partial search query that Autosuggest should operate on. | .searchTerm(“test”) |
user_agent | The user agent of the browser that's making the search request. | .userAgent(“”) |
user_id | The universal customer ID of the user. | .userId(“”) |
url | The absolute URL of the page where the request is initiated. Do not use a relative URL. | .url(“example.com”) |
Updated 5 months ago