Calling the Recommendations 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.

Item-based Recommendation Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
let widgetRequest = WidgetRequest()
  .itemIds(value: "1234")
ParameterDescriptionMethod call
item_idsSpecifies access to a particular set of items. For product catalog, this would be the PID(s)..itemIds(value: “1234”)

.itemIds(values: [“1234”, “98765”])
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(value: “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(value: “test”)
fieldsA comma-separated list of fields to be sent in the request..fields(value: “f1,f2”)

.fields(values: [“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(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)
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(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(value: “”)
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(value: “”)
  1. 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.
    }
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.

Category-based Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
let widgetRequest = WidgetRequest()
  .catId(value: "1234")
ParameterDescriptionMethod call
cat_idYour site's category ID..catId(value: “1234”)
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL..url(value: “example.com”)
facetFacets are disabled by default. To enable facets, set facet=true..facet(value: 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(value: "color:"red"")

.filterFacet(attribute: "color", value: "red")

.filterFacet(attribute: "color", values: ["red", "blue"], operator: Operator.OR)
fieldsA comma-separated list of fields to be sent in the request..fields(value: “f1,f2”)

.fields(values: [“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(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)
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(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(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(value: “”)
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(value: “”)
  1. 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.
    }
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.

Keyword-based Widget API

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

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

Personalization-based Widget API

  1. Create the WidgetRequest object using the supported parameters mentioned:
let widgetRequest = WidgetRequest()
  .query(value: "cap")
	.userId(value: “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(value: “u123”)
queryYour 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.

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

Global Recommendation Widget API

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

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