diff --git a/AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift b/AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift index 7d853d80..b9a7b0c5 100644 --- a/AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift +++ b/AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift @@ -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 @@ -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) diff --git a/AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift b/AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift index 0b34eae4..d5309608 100644 --- a/AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift +++ b/AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift @@ -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 @@ -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"), @@ -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) { diff --git a/AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift b/AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift index 2954c364..40325479 100644 --- a/AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift +++ b/AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift @@ -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! @@ -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 @@ -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) { @@ -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 @@ -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) { diff --git a/README.md b/README.md index f2f4ab09..a111d238 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -83,6 +84,7 @@ 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** @@ -90,6 +92,7 @@ If you are retrieving results from your backend servers instead of direclty usin ```swift let constructorClientId = constructorIO.clientID ``` + 2. **Session Id** ```swift @@ -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 @@ -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) @@ -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" @@ -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"), @@ -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: @@ -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