Skip to main content
Since May 1st, 2024, Apple requires all iOS apps to include a privacy manifest. For more details, see Privacy Manifest.
Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. For more information, see Get started with click and conversion events. To send events from your InstantSearch iOS app, follow these steps:
  1. Add the insights client.
  2. Add click events) when users click search results.
  3. Track conversions that start in your InstantSearch app.

​
Add the InstantSearch Insights library

Add the library as a dependency using Swift Package Manager, CocoaPods, or Carthage, and add import InstantSearchInsights to your source files.

​
Swift Package Manager

To use Swift Package Manager, open your project with Xcode. Go to File > Add Packages and enter the URL of the InstantSearch iOS library (https://github.com/algolia/instantsearch-ios). In the Choose Package Products for instantsearch-ios dialog, include InstantSearchInsights If you’re a framework author and use InstantSearch Insights as a dependency, update your Package.swift file:
Swift
let package = Package(
    dependencies: [
        .package(name: "InstantSearch", url: "https://github.com/algolia/instantsearch-ios", from: "7.7.0")
    ]
)
Add .product(name: "InstantSearchInsights", package: "InstantSearch") to your target dependencies list.

​
CocoaPods

If you use CocoaPods, add the following line to your Podfile:
Ruby
pod("InstantSearch/Insights", "~> 7.7")
Run pod update to download the dependencies.

​
Carthage

If you use Carthage, add the following line to your Cartfile:
Cartfile
github "algolia/instantsearch-ios" ~> 7.7
Run the following commands from your project directory: 
carthage update
./Carthage/Checkouts/instant-search-ios/carthage-prebuild
carthage build
Carthage can’t build only specific components in a repository. The previous commands build all components and their dependencies. But you don’t need to copy frameworks you aren’t using. For example, if you don’t use all the InstantSearch components, you can delete all InstantSearch frameworks except InstantSearchInsights from the Carthage build directory.

​
Add the Insights client

To add the Insights client, you’ll need your Algolia application ID, (search) API key, and a userToken to identify your users. You can find your application ID and API key in the Algolia dashboard.
Swift
Insights.register(appId: "testApp", apiKey: "testKey", userToken: "testToken")
To send events without timestamps, and be automatically attributed on the server, set the generateTimestamps parameter to false:
Swift
Insights.register(appId: "testApp",
                  apiKey: "testKey",
                  userToken: "testToken",
                  generateTimestamps = false)
To specify the region you prefer to use, set the region parameter to .de or .us:
Swift
Insights.register(appId: "testApp",
                  apiKey: "testKey",
                  userToken: "testToken",
                  region: .de)

​
Customize the events flush delay

By default, the client sends events to Algolia every 30 minutes. You can adjust this delay by changing the flushDelay value (in seconds):
Swift
Insights.flushDelay = 60

​
Set the Insights API region

By default, each time you send an event, Algolia geo-routes the API call so that the call targets the closest servers. The analytics API supports two regions: United States and Germany. You can specify the region you prefer to use as follows.
Swift
Insights.region = .de

​
Enable automatic view events

InstantSearch can automatically send view events when hits are returned from Algolia. To enable this feature, set isAutoSendingHitsViewEvents to true when you initialize HitsSearcher:
Swift
let searcher = HitsSearcher(appId: "ALGOLIA_APPLICATION_ID",
                            apiKey: "ALGOLIA_SEARCH_API_KEY",
                            indexName: "indexName",
                            isAutoSendingHitsViewEvents: true)

​
Send click events from hits widgets

To send click events when users select a search result in a Hits widget, use the following code:
Swift
let searcher = HitsSearcher(appID: "ALGOLIA_APPLICATION_ID",
                            apiKey: "ALGOLIA_SEARCH_API_KEY",
                            indexName: "indexName")
let hitsInteractor = HitsInteractor<Hit<JSON>>()

// Establish a connection between the searcher and hits interactor
hitsInteractor.connectSearcher(searcher)

// Declare a HitsTracker which takes care of activating clickAnalytics
// in the Query and extracts queryID from a received result for
// the index in the question
let hitsTracker = HitsTracker(eventName: "didClickItem", searcher: searcher)

// Did click the 10th item in the list
let hit = hitsInteractor.hit(atIndex: 10)!
hitsTracker.trackClick(for: hit, position: 10)
If you’re using multiple Hits widgets, you must enable sending click events on each one separately. Check your click events in the Events Debugger. For more information, see Validate your events.

​
Send click, conversion, and view events

Use the following methods to send click, conversion, or view events:
Swift
Insights.shared?.clickedAfterSearch(eventName: "click event",
                                    indexName: "indexName",
                                    objectID: "object id",
                                    position: 1,
                                    queryID: "query id")

Insights.shared?.convertedAfterSearch(eventName: "conversion event",
                                      indexName: "indexName",
                                      objectIDs: ["obj1", "obj2"],
                                      queryID: "query id")

Insights.shared?.viewed(eventName: "view event",
                        indexName: "indexName",
                        filters: ["brand:apple"])
Conversions often happen outside your search pages. For example, the Order completed event for a successful purchase happens in the shopping cart. To capture these conversions, keep track of the query ID across your app. When you add events, check them in the Events Debugger in the Algolia dashboard. For more information, see Validate your events.

​
Enable logging

You can also check if you’ve sent an event by enabling logging:
Swift
Insights.shared(appId: "ALGOLIA_APPLICATION_ID")?.isLoggingEnabled = true
After you’ve enabled it, check the output for success messages or errors. 
// Success
[Algolia Insights - appName] Sync succeded for EventsPackage(id: "37E9A093-8F86-4049-9937-23E99E4E4B33", events: [{
    eventName = "search result click";
    eventType = click;
    index = "my index";
    objectIDs =     (
        1234567
    );
    positions =     (
        3
    );
    queryID = 08a76asda34fl30b7d06b7aa19a9e0;
    timestamp = 1545069313405;
    userToken = "C1D1322E-8CBF-432F-9875-BE3B5AFDA498";
}], region: nil)

//Error
[Algolia Insights - appName] The objectID field is missing (Code: 422)
For the positions parameter of the clickedObjectIdsAfterSearch method, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.
⌘I