DOCSEARCHbyAlgolia
Submit Docs

InstantSearch iOS

repository·master·Indexed 24 days ago

https://github.com/algolia/instantsearch-ios

A high-level framework built on top of Algolia's Swift API Client that provides UI components and business logic for building instant-search experiences on iOS, tvOS, and watchOS. It supports both declarative UI patterns with SwiftUI and imperative UI patterns with UIKit, offering features such as multi-index search, query suggestions, facet filtering, and voice search integration.

Tokens
6.2K
Snippets
18
Records
29
Agent score
50%

What's inside InstantSearch iOS

  1. Manage user tracking and opt-out

    master

    Events are associated with users via a userToken. You can set this token at three levels of granularity:

    1. Global: Set Insights.shared?.userToken for a default value across all events.
    2. Application: Provide a userToken during Insights.register to apply it to every event tracked by that app.
    3. Individual Event: Pass a userToken directly to an event method (e.g., clicked) to override previous defaults.

    User Opt-out: To respect a user's request to stop tracking, set the isActive property to false on the Insights instance.

    // Global userToken default value
Insights.shared?.userToken = "userToken"

// Application userToken, overrides global default
Insights.register(appId: "yourApplicationID",
                  apiKey: "yourAPIKey",
                  userToken: "userToken")

// Event userToken, overrides previous defaults
Insights.shared?.clicked(eventName: "eventName",
                         indexName: "indexName",
                         objectID: "objectID1",
                         userToken: "userToken")

// Opt-out of tracking
Insights.shared?.isActive = false

  2. Core components of InstantSearchAgent

    master

    The InstantSearchAgent library (v0.1) consists of the following core components:

    • AgentStudioEndpoint: Builds the agent-studio/1/agents/{id}/completions?compatibilityMode=ai-sdk-5 URL.
    • AgentStudioTransport: A URLSession-backed transport for POST requests and SSE (Server-Sent Events) responses.
    • SSEStreamParser: An AsyncSequence that parses UIMessageChunk from URLSession.AsyncBytes.
    • ChatStore: An ObservableObject that aggregates chunks into UIMessages and exposes properties like messages, status, and error, along with methods like send, regenerate, stop, and clear.

  3. Run the Getting Started with SwiftUI example

    master

    To run the official SwiftUI search experience demonstration, follow these steps:

    1. Clone the repository:
      git clone git@github.com:algolia/instantsearch-ios.git
    2. Open the project: Open the Examples project using Xcode.
    3. Select the target: Choose the GettingStartedSwiftUIGuide target.
    4. Launch: Run the example in an iOS Simulator.

    The example demonstrates a complete search experience including:

    • A list to display search results
    • A search box for queries
    • Search statistics
    • A facet list for filtering results.
    git clone git@github.com:algolia/instantsearch-ios.git

  6. Run the InstantSearch iOS Showcase example

    master

    The Examples project in this repository provides a showcase of available widgets. To run it, follow these steps:

    1. Clone the repository: Use git to clone the source.
    2. Open the project: Open the Examples project using Xcode.
    3. Build and Run: Select the Examples target and build/run the project.
    4. Navigate the Showcase:
      • For UIKit widgets: Navigate to Showcase > Imperative UI.
      • For SwiftUI widgets: Navigate to Showcase > Declarative UI.
      • SwiftUI Previews: You can also view SwiftUI widgets directly via Xcode live previews.
    git clone git@github.com:algolia/instantsearch-ios.git

  7. Install InstantSearch iOS via CocoaPods

    master

    Add the desired product to your Podfile. You can install the full toolset or specific sub-libraries:

    • pod 'InstantSearch': The complete toolset including UIKit components.
    • pod 'InstantSearch/Insights': Access to the Insights library only.
    • pod 'InstantSearch/Core': Access to business logic without UIKit components.
    • pod 'InstantSearch/SwiftUI': Access to SwiftUI components.

    After updating your Podfile, run pod update in your terminal.

    pod 'InstantSearch', '~> 8.0'
# pod 'InstantSearch/Insights' for access to Insights library only
# pod 'InstantSearch/Core' for access business logic without UIKit components
# pod 'InstantSearch/SwiftUI' for access to SwiftUI components

  9. Initialize the InstantSearch Insights client

    master

    To start capturing search-related events, you must first register the Insights client using your Algolia Application ID and API Key. You can optionally provide a User Token for personalization; if omitted, an automatically-generated application-wide user token will be used.

    Note: The library correlates events with queryIDs generated by the search API when the clickAnalytics=true parameter is set in your search queries.

    Insights.register(appId: "testApp", 
                  apiKey: "testKey", 
                  userToken: "testToken")

  10. Run the Getting Started UIKit example

    master

    To run the official UIKit demonstration project, follow these steps:

    1. Clone the repository:
      git clone git@github.com:algolia/instantsearch-ios.git
    2. Open the project: Open the Examples project using Xcode.
    3. Select the target: Choose the GettingStartedUIKitGuide target in the Xcode scheme selector.
    4. Launch: Run the application in an iOS Simulator.

    The example demonstrates a complete search experience including:

    • A list to display search results
    • A search box for queries
    • Search statistics
    • A facet list for filtering results.
    git clone git@github.com:algolia/instantsearch-ios.git

  11. Install InstantSearchAgent via Swift Package Manager

    master

    To add the InstantSearchAgent library to your project using Swift Package Manager, add the following product to your target dependencies:

    .product(name: "InstantSearchAgent", package: "InstantSearch")

    Note that this library has no third-party dependencies and uses URLSession to communicate with the Agent Studio endpoint.