Skip to content

[CDX-241] Docs: Update docs for filterName and filterValue #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
evanyan13 merged 2 commits into from
Dec 11, 2025
Merged

[CDX-241] Docs: Update docs for filterName and filterValue #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a240c4
Update docs for filterName and filterValue
Dec 5, 2025
e706b19
Update lint and docs formatting
Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,20 @@ public class CIOBrowseQueryBuilder {
Create a Browse request query builder

- Parameters:
- filterName: The primary filter name that the user browsed for
- filterValue: The primary filter value that the user browsed for
- filterName: The attribute name that defines what you are browsing by.
- Use "group_id" by default for browsing item groups.
- Possible values:
- "group_id"
- "collection_id"
- "[facet_name]" (where the facet name corresponds with a facet defined in the catalog)
- filterValue: The specific value to filter by, corresponding to the `filterName`.
- Use the specific group ID, collection ID, or facet value you wish to query for. Eg. "sales", "mens-jeans"

### Usage Example: ###
To retrieve the item group with ID "sales", set filterName to "group_id" and filterValue to "sales".
```
let query = CIOBrowseQueryBuilder(filterName: "group_id", filterValue: "sales")
```
*/
public init(filterName: String, filterValue: String) {
self.filterName = filterName
Expand Down Expand Up @@ -191,7 +203,7 @@ public class CIOBrowseQueryBuilder {

let preFilterExpression = "{\"or\":[{\"and\":[{\"name\":\"group_id\",\"value\":\"electronics-group-id\"},{\"name\":\"Price\",\"range\":[\"-inf\",200.0]}]},{\"and\":[{\"name\":\"Type\",\"value\":\"Laptop\"},{\"not\":{\"name\":\"Price\",\"range\":[800.0,\"inf\"]}}]}]}"

let query = CIOBrowseQueryBuilder(filterName: "potato", filterValue: "russet")
let query = CIOBrowseQueryBuilder(filterName: "group_id", filterValue: "sales")
.setFilters(CIOQueryFilters(groupFilter: nil, facetFilters: facetFilters))
.setPage(2)
.setPerPage(40)
Expand Down
13 changes: 10 additions & 3 deletions AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,14 @@ public struct CIOBrowseQuery: CIORequestData {
Create a Browse request query object

- Parameters:
- filterName: The primary filter name that the user browsed for
- filterValue: The primary filter value that the user browsed for
- filterName: The attribute name that defines what you are browsing by.
- Use "group_id" by default for browsing item groups.
- Possible values:
- "group_id"
- "collection_id"
- "[facet_name]" (where the facet name corresponds with a facet defined in the catalog)
- filterValue: The specific value to filter by, corresponding to the `filterName`.
- Use the specific group ID, collection ID, or facet value you wish to query for. Eg. "sales", "mens-jeans"
- filters: The filters used to refine results
- page: The page number of the results
- perPage: The number of results per page to return
Expand All @@ -103,6 +109,7 @@ public struct CIOBrowseQuery: CIORequestData {
- fmtOptions: The fmt options to use with the result set

### Usage Example: ###
To retrieve the item group with ID "sales", set filterName to "group_id" and filterValue to "sales".
```
let facetFilters = [(key: "Nutrition", value: "Organic"),
(key: "Nutrition", value: "Natural"),
Expand All @@ -118,7 +125,7 @@ public struct CIOBrowseQuery: CIORequestData {

let fmtOptions = [("groups_max_depth": "10")]

let browseQuery = CIOBrowseQuery(filterName: "group_id", filterValue: "Pantry", filters: CIOQueryFilters(groupFilter: nil, facetFilters: facetFilters), page: 1, perPage: 30, section: "Products", hiddenFields: ["price_CA", "currency_CA"], hiddenFacets: ["brand", "price_CA"], variationsMap: variationsMap, preFilterExpression: preFilterExpression, fmtOptions: fmtOptions)
let browseQuery = CIOBrowseQuery(filterName: "group_id", filterValue: "sales", filters: CIOQueryFilters(groupFilter: nil, facetFilters: facetFilters), page: 1, perPage: 30, section: "Products", hiddenFields: ["price_CA", "currency_CA"], hiddenFacets: ["brand", "price_CA"], variationsMap: variationsMap, preFilterExpression: preFilterExpression, fmtOptions: fmtOptions)
```
*/
public init(filterName: String, filterValue: String, filters: CIOQueryFilters? = nil, sortOption: CIOSortOption? = nil, page: Int? = nil, perPage: Int? = nil, section: String? = nil, hiddenFields: [String]? = nil, hiddenFacets: [String]? = nil, groupsSortOption: CIOGroupsSortOption? = nil, variationsMap: CIOQueryVariationsMap? = nil, preFilterExpression: String? = nil, fmtOptions: [FmtOption]? = nil) {
Expand Down
16 changes: 8 additions & 8 deletions AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ public class ConstructorIO: CIOSessionManagerDelegate {
(key: "Nutrition", value: "Natural"),
(key: "Brand", value: "Kraft Foods")]

let browseQuery = CIOBrowseQuery(filterName: "group_id", filterValue: "Pantry", filters: CIOQueryFilters(groupFilter: nil, facetFilters: facetFilters), page: 1, perPage: 30, section: "Products")
let browseQuery = CIOBrowseQuery(filterName: "group_id", filterValue: "sales", filters: CIOQueryFilters(groupFilter: nil, facetFilters: facetFilters), page: 1, perPage: 30, section: "Products")

constructorIO.browse(forQuery: browseQuery) { response in
let data = response.data!
Expand Down Expand Up @@ -441,8 +441,8 @@ public class ConstructorIO: CIOSessionManagerDelegate {
Track when a user views a browse product listing page

- Parameters:
- filterName: The name of the primary filter that the user browsed for (i.e "color")
- filterValue: The value of the primary filter that the user browsed for (i.e "blue")
- filterName: The name of the primary filter that the user browsed for (i.e "group_id")
- filterValue: The value of the primary filter that the user browsed for (i.e "sales")
- resultCount: The number of results returned in total
- customerIDs: **Deprecated**. Use `items` (v4.2.0) instead. The list of item id's returned in the browse
- resultID: Identifier of result set
Expand All @@ -453,10 +453,10 @@ public class ConstructorIO: CIOSessionManagerDelegate {
### Usage Example: ###
```
// Uses items parameter (preferred)
constructorIO.trackBrowseResultsLoaded(filterName: "Category", filterValue: "Snacks", resultCount: 674, items: [CIOItem(id: "1234567-AB", name: "Toothpicks")])
constructorIO.trackBrowseResultsLoaded(filterName: "group_id", filterValue: "sales", resultCount: 674, items: [CIOItem(id: "1234567-AB", name: "Toothpicks")])

// Uses customerIDs parameter (deprecated)
constructorIO.trackBrowseResultsLoaded(filterName: "Category", filterValue: "Snacks", resultCount: 674, customerIDs: ["1234567-AB", "1234765-CD", "1234576-DE"])
constructorIO.trackBrowseResultsLoaded(filterName: "group_id", filterValue: "sales", resultCount: 674, customerIDs: ["1234567-AB", "1234765-CD", "1234576-DE"])
```
*/
public func trackBrowseResultsLoaded(filterName: String, filterValue: String, resultCount: Int, customerIDs: [String]? = nil, items: [CIOItem]? = nil, resultID: String? = nil, analyticsTags: [String: String]? = nil, completionHandler: TrackingCompletionHandler? = nil) {
Expand All @@ -471,8 +471,8 @@ public class ConstructorIO: CIOSessionManagerDelegate {
- Parameters:
- customerID: The item ID.
- variationID: The variation ID
- filterName: The name of the primary filter that the user browsed for (i.e "color")
- filterValue: The value of the primary filter that the user browsed for (i.e "blue")
- filterName: The name of the primary filter that the user browsed for (i.e "group_id")
- filterValue: The value of the primary filter that the user browsed for (i.e "sales")
- resultPositionOnPage: The position of clicked item
- sectionName The name of the autocomplete section the term came from
- resultID: Identifier of result set
Expand All @@ -483,7 +483,7 @@ public class ConstructorIO: CIOSessionManagerDelegate {

### Usage Example: ###
```
constructorIO.trackBrowseResultClick(filterName: "Category", filterValue: "Snacks", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", resultID: "179b8a0e-3799-4a31-be87-127b06871de2")
constructorIO.trackBrowseResultClick(filterName: "group_id", filterValue: "sales", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", resultID: "179b8a0e-3799-4a31-be87-127b06871de2")
```
*/
public func trackBrowseResultClick(customerID: String, variationID: String? = nil, filterName: String, filterValue: String, resultPositionOnPage: Int?, sectionName: String? = nil, resultID: String? = nil, slCampaignID: String? = nil, slCampaignOwner: String? = nil, analyticsTags: [String: String]? = nil, completionHandler: TrackingCompletionHandler? = nil) {
Expand Down
28 changes: 17 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,17 @@

# Constructor.io Swift Client

An iOS Client for [Constructor.io](http://constructor.io/). [Constructor.io](http://constructor.io/) provides search as a service that optimizes results using artificial intelligence (including natural language processing, re-ranking to optimize for conversions, and user personalization).
An iOS Client for [Constructor.io](http://constructor.io/). [Constructor.io](http://constructor.io/) provides search as a service that optimizes results using artificial intelligence (including natural language processing, re-ranking to optimize for conversions, and user personalization).

## Documentation

Full API documentation is available on [Github Pages](https://constructor-io.github.io/constructorio-client-swift/)

## 1. Import

### 1.a Import using CocoaPods

First make sure you have [CocoaPods installed](https://guides.cocoapods.org/using/getting-started.html). Then create an empty text file in your project’s root directory called ‘Podfile’. Add the following lines to the file:
First make sure you have [CocoaPods installed](https://guides.cocoapods.org/using/getting-started.html). Then create an empty text file in your project’s root directory called ‘Podfile’. Add the following lines to the file:

```use_frameworks!
target ‘YOUR_TARGET_NAME’ do
Expand Down Expand Up @@ -39,7 +40,7 @@ Open the terminal (make sure you’re located in the project root) and type
carthage update
```

Drag the ```ConstructorIO.framework``` from Carthage/Build/iOS into your project and link it with your application target. Also, make sure to copy the framework by adding a new Copy Files phase.
Drag the `ConstructorIO.framework` from Carthage/Build/iOS into your project and link it with your application target. Also, make sure to copy the framework by adding a new Copy Files phase.

### 1.c Import using Swift Package Manager

Expand All @@ -61,7 +62,7 @@ Lastly, you'll just need to import `ConstructorAutocomplete` to your source file

## 2. Retrieve an API key

You can find this in your [Constructor.io dashboard](https://constructor.io/dashboard). Contact sales if you'd like to sign up, or support if you believe your company already has an account.
You can find this in your [Constructor.io dashboard](https://constructor.io/dashboard). Contact sales if you'd like to sign up, or support if you believe your company already has an account.

## 3. Create a Client Instance

Expand All @@ -83,13 +84,15 @@ constructorIO.userID = "abcdefghijk-123"
```

## 4. Retrieving the clientID and sessionID

If you are retrieving results from your backend servers instead of direclty using our SDK, there are certain personalization parameters that are needed to be passed along with your requests. And those parameters can be accessed from the Constructor instance.

1. **Client Id**

```swift
let constructorClientId = constructorIO.clientID
```

2. **Session Id**

```swift
Expand All @@ -99,6 +102,7 @@ let constructorSessionId = constructorIO.sessionID
In most cases, you will want to store those parameters as cookies preferably as **ConstructorioID_client_id** and **ConstructorioID_session_id** to be sent with your requests to your backend servers.

## 5. Setting test cell information for A/B tests

When A/B testing, it is important to specify which cell the user is being assigned to. Information about the test cell can be set through the `ConstructorIOConfig` object.

```kotlin
Expand Down Expand Up @@ -152,7 +156,7 @@ constructorIO.search(forQuery: query, filters: filters, groupsSortOption: groups
## 8. Request Browse Results

```swift
let query = CIOBrowseQuery(filterName: "potato", filterValue: "russet")
let query = CIOBrowseQuery(filterName: "group_id", filterValue: "sales")

// Specify the sort order in which groups are returned
let groupsSortOption = CIOGroupsSortOption(sortBy: CIOGroupsSortBy.value, sortOrder: CIOGroupsSortOrder.ascending)
Expand All @@ -177,6 +181,7 @@ constructorIO.recommendations(forQuery: query) { (response) in
```

### With an item id (and variation id) for the alternative/complementary items recommendations strategy

```swift
let itemId = "P18232"
let variationId = "P18232-123"
Expand All @@ -190,6 +195,7 @@ constructorIO.recommendations(forQuery: query) { (response) in
```

### With filters for the filtered item recommendations strategy

```swift
let filters = CIOQueryFilters(groupFilter: "cat_1234", facetFilters: [
(key: "Nutrition", value: "Organic"),
Expand Down Expand Up @@ -231,7 +237,7 @@ constructorIO.getQuizResults(forQuery: query) { (response) in

## 12. Instrument Behavioral Events

The iOS Client sends behavioral events to [Constructor.io](http://constructor.io/) in order to continuously learn and improve results for future Autosuggest and Search requests. The Client only sends events in response to being called by the consuming app or in response to user interaction . For example, if the consuming app never calls the SDK code, no events will be sent. Besides the explicitly passed in event parameters, all user events contain a GUID based user ID that the client sets to identify the user as well as a session ID.
The iOS Client sends behavioral events to [Constructor.io](http://constructor.io/) in order to continuously learn and improve results for future Autosuggest and Search requests. The Client only sends events in response to being called by the consuming app or in response to user interaction . For example, if the consuming app never calls the SDK code, no events will be sent. Besides the explicitly passed in event parameters, all user events contain a GUID based user ID that the client sets to identify the user as well as a session ID.

Three types of these events exist:

Expand Down Expand Up @@ -280,23 +286,23 @@ constructorIO.trackSearchResultClick(itemName: "Fashionable Toothpicks", custome

```swift
// Track when browse results are loaded into view
constructorIO.trackBrowseResultsLoaded(filterName: "Category", filterValue: "Snacks", resultCount: 674)
constructorIO.trackBrowseResultsLoaded(filterName: "group_id", filterValue: "sales", resultCount: 674)

// Track when browse results are loaded into view with items array (supported in v3.1.2 and above)
constructorIO.trackBrowseResultsLoaded(filterName: "Category", filterValue: "Snacks", resultCount: 674, customerIDs: ["1234567-AB", "1234765-CD", "1234576-DE"])
constructorIO.trackBrowseResultsLoaded(filterName: "group_id", filterValue: "sales", resultCount: 674, customerIDs: ["1234567-AB", "1234765-CD", "1234576-DE"])

// Track when a browse result is clicked
constructorIO.trackBrowseResultClick(filterName: "Category", filterValue: "Snacks", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", resultID: "179b8a0e-3799-4a31-be87-127b06871de2")
constructorIO.trackBrowseResultClick(filterName: "group_id", filterValue: "sales", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", resultID: "179b8a0e-3799-4a31-be87-127b06871de2")
```

### Sponsored Browse Events

```swift
// Track when sponsored browse results are loaded into view.
constructorIO.trackBrowseResultsLoaded(filterName: "Category", filterValue: "Snacks", resultCount: "674", items: CIOItem(customerID: "10001", slCampaignID: "campaign-1", slCampaignOwner: "owner-1"))
constructorIO.trackBrowseResultsLoaded(filterName: "group_id", filterValue: "sales", resultCount: "674", items: CIOItem(customerID: "10001", slCampaignID: "campaign-1", slCampaignOwner: "owner-1"))

// Track when a sponsored browse result is clicked
constructorIO.trackBrowseResultClick(filterName: "Category", filterValue: "Snacks", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", slCampaignID: "campaign-1", slCampaignOwner: "owner-1")
constructorIO.trackBrowseResultClick(filterName: "group_id", filterValue: "sales", customerID: "7654321-BA", variationID: "7654321-BA-738", resultPositionOnPage: 4, sectionName: "Products", slCampaignID: "campaign-1", slCampaignOwner: "owner-1")
```

### Recommendations Events
Expand Down
Loading