Calling the Search APIs - iOS

Setup

To set up the SDK before using, complete the following steps:

Add the package

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

Initialization

To initialize the Discovery Pixel SDK in your app, first import the discovery_ios_sdk module in your UIApplicationDelegate:

import discovery_ios_sdk

Then initialize the API Discovery SDK (brApiRequest) in your app delegate's application(_:didFinishLaunchingWithOptions:) method as shown:

class AppDelegate: NSObject, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
  //...
  //...
    
//Initialise API 
    let brApiRequest = BrApiRequest(
      accountId: "<ACCOUNT_ID>",
      uuid: "<13_digit_random_number>",
      visitorType: VisitorType.NEW_USER,
      domainKey: "documentation_site",
      environment: Env.PROD)
        
    BrApi.shared.intialise(brApiRequest: brApiRequest)

 	  return true
  }
}

If you are using SwiftUI, use the UIApplicationDelegateAdaptor property wrapper to tell SwiftUI it should use your AppDelegate class for the application delegate.

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Make sure to replace all the placeholder values for the parameter values in the snippet above.


Here is a reference of all the different parameters you can set based on your requirements:

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

Note: Import the discovery_ios_sdk module on the files where you need to trigger 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.

let productSearchRequest = ProductSearchRequest()
  .searchTerm(q: "table")
  .fl(value: "pid")
  .url(value: "example.com")

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

BrApi.shared.productSearchApi(productSearchRequest: productSearchRequest) { response in
	//gets required response in response object
  } failure: { error in
      // if the API fails, handle error 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(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(start: 0)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(value: “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(value: “pid,title”)

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

.fq("color", values: [“blue”, “red”])

.fq(attribute: "color", value: "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(value: "sale_price,length,width")

.statsField(values:
[
"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: ["Cotton", "Linen"], operator= Operator.OR)
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 facetscounts 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 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(value: “price”)

.facetRange(values: ["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(value: "price+asc")

//multiple sort with String
.sort(values: ["reviews+desc", "sale_price+desc"])
user_idThe universal customer ID of the user..userId(value: “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(value: “”)
widget_idThe widget_id provided in the Dashboard for the Dynamic Widgets feature, which is used to provide curated results..widgetId(value: “widget123”)

BOPIS

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

let categorySearchRequest = CategorySearchRequest()
  .fl(values: 
    [
      "pid",
      "title",
      "brand",
      "price"
    ]
  )
  .searchTerm(q: "test")

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

BrApi.shared.categorySearchApi(categorySearchRequest: productSearchRequest) { response in
	//gets required response in response object
    } failure: { error in
   	    // 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.

let contentSearchRequest = ContentSearchRequest()
  .fl(
    values: [
      "pid",
      "title",
      "brand",
      "price"
    ]
  )
  .catalogName(value: "Chair")
  .searchTerm(q: "test")

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

BrApi.shared.contentSearchApi(contentSearchRequest: contentSearchRequest) { response in
  //gets required response in response object
    } failure: { error in
   	  // 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(value: “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.

let bestSellerRequest = BestSellerRequest()
  .fl(
    istOf(
      "pid",
      "title",
      "brand",
      "price"
    )
    )
    .searchTerm("test")

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

BrApi.shared.bestSellerApi(bestSellerRequest: bestSellerRequest) { response in
  //gets required response in response object
    } failure: { error in
   	  // if the API fails, handle error here.
    }

Supported parameters for creating the BestSellerRequest object:

ParameterDescriptionMethod call
titleThe title or name of the product..title(value: “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.

let autoSuggestRequest = AutosuggestRequest()
  .catalogViews(value: “product:store1|p1:s1”)

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

BrApi.shared.autoSuggestApi(autoSuggestApi: autoSuggestApi) { response in
  //gets required response in response object
    } failure: { error in
      // 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(value: “product:store1|p1:s1”)
qYour site visitor's partial search query that Autosuggest should operate on..searchTerm(q: “test”)
user_agentThe user agent of the browser that's making the search request..userAgent(value: “”)
user_idThe universal customer ID of the user..userId(value: “”)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(value: “”)