Calling the Recommendations APIs

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:

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

Note: Import the discovery_ios_sdk module on the files where you need to trigger APIs.

Item-based Recommendation Widget API

Create the WidgetRequest object using the supported parameters mentioned:

let widgetRequest = WidgetRequest()
  .itemIds(value: "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(value: “1234”) .itemIds(values: [“1234”, “98765”])
url	The absolute URL of the page where the request is initiated. Do not use a relative URL.	.url(value: “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(value: “test”)
fields	A comma-separated list of fields to be sent in the request.	.fields(value: “f1,f2”) .fields(values: [“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(value: “”) .filter(attribute: "fabric", values: ["cotton", "linen"], operator: Operator.AND) .filter(attribute: "fabric", values: ["cotton", "linen"], operator: Operator.OR) .filter(attribute: "price", startRange: 10, endRange: 100, isNot: true) .filter(attribute: "color_groups", value: "blue", isNot: 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(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(value: “”)
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(value: “”)

To make the API call, use the following code snippet and pass the following parameters:

BrApi.shared.itemBasedRecommendationWidgetApi(widgetId: “2l726795”, widgetRequest: widgetRequest) { response in
  //gets required response in response object of type RecsAndPathwaysResponse
    } failure: { error in
      // 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.

Category-based Widget API

Create the WidgetRequest object using the supported parameters mentioned:

let widgetRequest = WidgetRequest()
  .catId(value: "1234")

Parameter	Description	Method call
cat_id	Your site's category ID.	.catId(value: “1234”)
url	The absolute URL of the page where the request is initiated. Do not use a relative URL.	.url(value: “example.com”)
facet	Facets are disabled by default. To enable facets, set facet=true.	.facet(value: 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(value: "color:"red"") .filterFacet(attribute: "color", value: "red") .filterFacet(attribute: "color", values: ["red", "blue"], operator: Operator.OR)
fields	A comma-separated list of fields to be sent in the request.	.fields(value: “f1,f2”) .fields(values: [“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(value: “”) .filter(attribute: "fabric", values: ["cotton", "linen"], operator: Operator.AND) .filter(attribute: "fabric", values: ["cotton", "linen"], operator: Operator.OR) .filter(attribute: "price", startRange: 10, endRange: 100, isNot: true) .filter(attribute: "color_groups", value: "blue", isNot: 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(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(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(value: “”)
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(value: “”)

To make the API call, use the following code snippet and pass the following parameters:

BrApi.shared.categoryBasedWidgetApi(widgetId: “2l726795”, widgetRequest: widgetRequest) { response in
  //gets required response in response object of type RecsAndPathwaysResponse
    } failure: { error in
   	  // 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.

Keyword-based Widget API

Create the WidgetRequest object using the supported parameters mentioned:

let widgetRequest = WidgetRequest()
  .query(value: "cap")

Parameter	Description	Method call
query	Your site visitor's search query. Search queries are composed of one or more terms.	.query(value: “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.shared.keywordBasedWidgetApi(widgetId: “2l726795”, widgetRequest: widgetRequest) { response in
  //gets required response in response object of type RecsAndPathwaysResponse
    } failure: { error in
   	  // 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.

Personalization-based Widget API

Create the WidgetRequest object using the supported parameters mentioned:

let widgetRequest = WidgetRequest()
  .query(value: "cap")
	.userId(value: “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(value: “u123”)
query	Your site visitor's search query. Search queries are composed of one or more terms.	.query(value: “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.shared.personalizationBasedWidgetApi(widgetId: “2l726795”, widgetRequest: widgetRequest) { response in
  //gets required response in response object of type RecsAndPathwaysResponse
    } failure: { error in
   	  // 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.

Global Recommendation Widget API

Create the WidgetRequest object using the supported parameters mentioned:

let 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.shared.globalRecommendationWidgetApi(widgetId: “2l726795”, widgetRequest: widgetRequest) { response in
  //gets required response in response object of type RecsAndPathwaysResponse
    } failure: { error in
   	  // 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.