{"id":26103317,"url":"https://github.com/constructor-io/constructorio-client-swift","last_synced_at":"2025-04-12T17:23:40.747Z","repository":{"id":24924860,"uuid":"102783535","full_name":"Constructor-io/constructorio-client-swift","owner":"Constructor-io","description":"Constructor.io Client for iOS Applications","archived":false,"fork":false,"pushed_at":"2025-04-05T00:06:16.000Z","size":20726,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-12T17:23:12.059Z","etag":null,"topics":["constructorio-integrations","ios-sdk","search","swift"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Constructor-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-07T20:39:06.000Z","updated_at":"2025-04-05T00:06:21.000Z","dependencies_parsed_at":"2024-01-31T23:37:10.064Z","dependency_job_id":"fab4d016-d3ee-4ce2-a89c-8d98a3550683","html_url":"https://github.com/Constructor-io/constructorio-client-swift","commit_stats":{"total_commits":279,"total_committers":13,"mean_commits":21.46153846153846,"dds":0.6451612903225806,"last_synced_commit":"f0b5b3c07e30b47f194930302316c2a09d8e5052"},"previous_names":[],"tags_count":97,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-client-swift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-client-swift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-client-swift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-client-swift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Constructor-io","download_url":"https://codeload.github.com/Constructor-io/constructorio-client-swift/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248602853,"owners_count":21131701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["constructorio-integrations","ios-sdk","search","swift"],"created_at":"2025-03-09T20:06:21.857Z","updated_at":"2025-04-12T17:23:40.717Z","avatar_url":"https://github.com/Constructor-io.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://img.shields.io/badge/platform-iOS-blue.svg?style=flat\" alt=\"Platform iOS\" /\u003e \u003cimg src=\"https://img.shields.io/badge/Swift-3.0+-blue.svg\" alt=\"Swift 3+ compatible\" /\u003e \u003cimg src=\"https://img.shields.io/badge/Objective--C-compatible-blue.svg\" alt=\"Objective-C compatible\" /\u003e \u003cimg  src=\"http://img.shields.io/badge/license-MIT-blue.svg?style=flat\" alt=\"License: MIT\" /\u003e\n\n# Constructor.io Swift Client\n\nAn 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).\n\n## Documentation\nFull API documentation is available on [Github Pages](https://constructor-io.github.io/constructorio-client-swift/)\n\n## 1. Import\n\n### 1.a Import using CocoaPods\n\nFirst 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:\n\n```use_frameworks!\ntarget ‘YOUR_TARGET_NAME’ do\n   pod ‘ConstructorAutocomplete'\nend\n```\n\nOpen the terminal (make sure you’re located in the project root) and type\n\n```bash\npod install\n```\n\n### 1.b Import using Carthage\n\nFirst, make sure you have [Carthage installed](https://github.com/Carthage/Carthage#installing-carthage). Then create an empty text file called ‘Cartfile’ in your project root directory. Now, add the following lines:\n\n```\ngithub \"Constructor-io/constructorio-client-swift\"\n```\n\nOpen the terminal (make sure you’re located in the project root) and type\n\n```bash\ncarthage update\n```\n\nDrag 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.\n\n### 1.c Import using Swift Package Manager\n\nTo install using SwiftPM. Go into Xcode and click on `File` \u003e `Add Package Dependency` and enter [Constructor's Swift Client repository URL](https://github.com/constructor-io/constructorio-client-swift).\n\nIf you develop frameworks and would like to utilize the Swift API Client as a dependency, update your `Package.swift` file with the following:\n\n```swift\nlet package = Package(\n    // 3.3.13 ..\u003c 4.0.0\n    dependencies: [\n        .package(url: \"https://github.com/constructor-io/constructorio-client-swift\", from: \"3.3.13\")\n    ],\n    // ...\n)\n```\n\nLastly, you'll just need to import `ConstructorAutocomplete` to your source files to begin using it.\n\n## 2. Retrieve an API key\n\nYou 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.\n\n## 3. Create a Client Instance\n\nMake sure to import the `ConstructorAutocomplete` module at the top of your source file and then write the following\n\n```swift\n// Create the client config\nlet config = ConstructorIOConfig(\n   apiKey: \"YOUR API KEY\",\n   baseURL: \"https://ac.cnstrc.com\", // default service url. protocol must be specified (i.e. https)\n   resultCount: AutocompleteResultCount(numResultsForSection: [\"Search Suggestions\" : 3, \"Products\" : 0])\n)\n\n// Create the client instance\nlet constructorIO = ConstructorIO(config: config)\n\n// Set the user ID (for a logged in user) used for cross device personalization\nconstructorIO.userID = \"abcdefghijk-123\"\n```\n\n## 4. Retrieving the clientID and sessionID\nIf 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.\n\n1. **Client Id**\n\n```swift\nlet constructorClientId = constructorIO.clientID\n```\n2. **Session Id**\n\n```swift\nlet constructorSessionId = constructorIO.sessionID\n```\n\nIn 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.\n\n## 5. Setting test cell information for A/B tests\nWhen 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.\n\n```kotlin\nlet testCell = CIOABTestCell\n\nlet config = ConstructorIOConfig(\n   apiKey: \"YOUR API KEY\",\n   baseURL: \"https://ac.cnstrc.com\", // default service url. protocol must be specified (i.e. https)\n   testCells: [CIOABTestCell(key: \"constructorio_test\", value: \"control_1\")]\n)\n\n// Create the client instance\nlet constructorIO = ConstructorIO(config: config)\n\n// The test cells in the config can be edited after instantiating the client instance\nconstructorIO.config.testCells = [CIOABTestCell(key: \"constructorio_test\", value: \"experiment_1\")]\n```\n\n## 6. Request Autocomplete Results\n\n```swift\nlet query = CIOAutocompleteQuery(query: \"apple\", numResultsForSection: [\"Products\": 6, \"Search Suggestions\": 8])\n\nconstructorIO.autocomplete(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 7. Request Search Results\n\n```swift\nlet filters = CIOQueryFilters(groupFilter: \"Bread\", facetFilters: [\n  (key: \"Nutrition\", value: \"Organic\"),\n  (key: \"Nutrition\", value: \"Natural\"),\n  (key: \"Nutrition\", value: \"Whole-grain\")\n])\nlet query = CIOSearchQuery(query: \"Dave's Bread\", page: 5, filters: filters)\n\n// Specify the sort order in which groups are returned\nlet groupsSortOption = CIOGroupsSortOption(sortBy: CIOGroupsSortBy.value, sortOrder: CIOGroupsSortOrder.ascending)\n\nconstructorIO.search(forQuery: query, filters: filters, groupsSortOption: groupsSortOption) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 8. Request Browse Results\n\n```swift\nlet query = CIOBrowseQuery(filterName: \"potato\", filterValue: \"russet\")\n\n// Specify the sort order in which groups are returned\nlet groupsSortOption = CIOGroupsSortOption(sortBy: CIOGroupsSortBy.value, sortOrder: CIOGroupsSortOrder.ascending)\n\nconstructorIO.browse(forQuery: query, groupsSortOption: groupsSortOption) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 9. Request Recommendation Results\n\n```swift\nlet query = CIORecommendationsQuery(podID: \"pdp_best_sellers\", filters: filters)\n\nconstructorIO.recommendations(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n### With an item id (and variation id) for the alternative/complementary items recommendations strategy\n```swift\nlet itemId = \"P18232\"\nlet variationId = \"P18232-123\"\nlet query = CIORecommendationsQuery(podID: \"pdp_complementary_items\", itemID: itemId, variationID: variationId)\n\nconstructorIO.recommendations(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n### With filters for the filtered item recommendations strategy\n```swift\nlet filters = CIOQueryFilters(groupFilter: \"cat_1234\", facetFilters: [\n  (key: \"Nutrition\", value: \"Organic\"),\n  (key: \"Nutrition\", value: \"Natural\"),\n  (key: \"Brand\", value: \"Kroger\")\n])\nlet query = CIORecommendationsQuery(podID: \"pdp_filtered_items\", filters: filters)\n\nconstructorIO.recommendations(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 10. Request Quiz Next Question\n\n```swift\nlet query = CIOQuizQuery(quizID: \"quiz-1\", answers: [[\"1\"], [\"2\"]])\n\nconstructorIO.getQuizNextQuestion(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 11. Request Quiz Results\n\n```swift\nlet query = CIOQuizQuery(quizID: \"quiz-1\", answers: [[\"1\"], [\"2\"]])\n\nconstructorIO.getQuizResults(forQuery: query) { (response) in\n  let data = response.data!\n  let error = response.error!\n  // ...\n}\n```\n\n## 12. Instrument Behavioral Events\n\nThe 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.\n\nThree types of these events exist:\n\n1. **General Events** are sent as needed when an instance of the Client is created or initialized\n2. **Autocomplete Events** measure user interaction with autocomplete results\n3. **Search Events** measure user interaction with search results\n4. **Browse Events** measure user interaction with browse results\n5. **Recommendation Events** measure user interaction with recommendations\n6. **Quiz Events** measure user interaction with quiz results\n7. **Conversion Events** measure user events like `add to cart` or `purchase`\n\n### Autocomplete Events\n\n```swift\n// Track when the user focuses into the search bar\nconstructorIO.trackInputFocus(searchTerm: \"\")\n\n// Track when the user selects an autocomplete suggestion\nconstructorIO.trackAutocompleteSelect(searchTerm: \"toothpicks\", originalQuery: \"tooth\", sectionName: \"Search Suggestions\", group: CIOGroup(displayName: \"Dental Health\", groupID: \"dental-92dk2\", path: \"health-2911e/dental-92dk2\"), resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n\n// Track when the user submits a search (either by selecting a suggestion or not selecting a suggestion)\nconstructorIO.trackSearchSubmit(searchTerm: \"toothpicks\", originalQuery: \"tooth\")\n```\n\n### Search Events\n\n```swift\n// Track when search results are loaded into view (customer ID's are the ID's of shown items)\nconstructorIO.trackSearchResultsLoaded(searchTerm: \"tooth\", resultCount: 789, customerIDs: [\"1234567-AB\", \"1234765-CD\", \"1234576-DE\"])\n\n// Track when a search result is clicked\nconstructorIO.trackSearchResultClick(itemName: \"Fashionable Toothpicks\", customerID: \"1234567-AB\", variationID: \"1234567-AB-7463\", searchTerm: \"tooth\", sectionName: \"Products\",  resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n```\n\n### Browse Events\n\n```swift\n// Track when browse results are loaded into view\nconstructorIO.trackBrowseResultsLoaded(filterName: \"Category\", filterValue: \"Snacks\", resultCount: 674)\n\n// Track when browse results are loaded into view with items array (supported in v3.1.2 and above)\nconstructorIO.trackBrowseResultsLoaded(filterName: \"Category\", filterValue: \"Snacks\", resultCount: 674, customerIDs: [\"1234567-AB\", \"1234765-CD\", \"1234576-DE\"])\n\n// Track when a browse result is clicked\nconstructorIO.trackBrowseResultClick(filterName: \"Category\", filterValue: \"Snacks\", customerID: \"7654321-BA\", variationID: \"7654321-BA-738\", resultPositionOnPage: 4, sectionName: \"Products\", resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n```\n\n### Recommendations Events\n\n```swift\n// Track when recommendation results are viewed\nconstructorIO.trackRecommendationResultsView(podID: \"pdp_best_sellers\", numResultsViewed: 5, resultPage: 1, resultCount: 10, resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n\n// Track when recommendation results are viewed with items array (supported in v3.3.13 and above)\nconstructorIO.trackRecommendationResultsView(podID: \"pdp_best_sellers\", numResultsViewed: 5, customerIDs: [\"1234567-AB\", \"1234765-CD\", \"1234576-DE\"], resultPage: 1, resultCount: 10, resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n\n// Track when a recomendation result is clicked\nconstructorIO.trackRecommendationResultClick(podID: \"pdp_best_sellers\", strategyID: \"best_sellers\", customerID: \"P183021\", variationID: \"7281930\", numResultsPerPage: 30, resultPage: 1, resultCount: 15, resultPositionOnPage: 1, resultID: \"179b8a0e-3799-4a31-be87-127b06871de2\")\n```\n\n### Quiz Events\n\n```swift\n// Track when a quiz result is clicked\nConstructorIo.trackQuizResultClick(quizID: \"coffee-quiz\", quizVersionID: \"1231244\", quizSessionID: \"123\", customerID: \"123\", itemName: \"espresso\")\n\n// Track when quiz results are loaded\nConstructorIo.trackQuizResultsLoaded(quizID: \"coffee-quiz\", quizVersionID: \"1231244\", quizSessionID: \"123\", resultCount: 20)\n\n// Track when a quiz result is converted on\nConstructorIo.trackQuizConversion(quizID: \"coffee-quiz\", quizVersionID: \"1231244\", quizSessionID: \"123\", customerID: \"123\", variationID: \"167\", itemName: \"espresso\", revenue: 20.0)\n\n```\n\n### Conversion Events\n\n```swift\n// Track when an item converts (a.k.a. is added to cart) regardless of the user journey that led to adding to cart\nconstructorIO.trackConversion(itemName: \"Fashionable Toothpicks\", customerID: \"1234567-AB\", variationID: \"1234567-AB-47398\", revenue: 12.99, searchTerm: \"tooth\", conversionType: \"add_to_cart\")\n\n// Track when items are purchased\nconstructorIO.trackPurchase(customerIDs: [\"123-AB\", \"456-CD\"], revenue: 34.49, orderID: \"343-315\")\n\n// Tracking items w/ variations in purchases (supported in v2.5.5 and above)\nlet purchaseItems = [\n  CIOItem(customerID: \"custID1\", variationID: \"varID1\", quantity: 2),\n  CIOItem(customerID: \"custID2\", variationID: \"varID2\", quantity: 3)\n]\nconstructorIO.trackPurchase(items: purchaseItems, revenue: 93.89, orderID: \"423-2432\")\n```\n\n### Miscellaneous Events\n\n```swift\n// Track when a product detail page is loaded (a.k.a after a user clicks on an item)\nconstructorIO.trackItemDetailLoad(customerID: \"10001\", itemName: \"item1\", variationID: \"var1\", sectionName: \"Products\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-client-swift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructor-io%2Fconstructorio-client-swift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-client-swift/lists"}