Send click and conversion events with InstantSearch iOS

As of May 1st, 2024, Apple requires all iOS apps to include a privacy manifest. Ensure you incorporate our provided privacy manifest files into your documentation. 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:

1
2
3
4
5
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:

1
pod 'InstantSearch/Insights', '~> 7.7'

Run pod update to download the dependencies.

Carthage

If you use Carthage, add the following line to your Cartfile:

1
github "algolia/instantsearch-ios" ~> 7.7

Run the following commands from your project directory:

1
2
3
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.

1
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:

1
2
3
4
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:

1
2
3
4
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):

1
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.

1
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:

1
2
3
4
let searcher = HitsSearcher(appId: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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:

1
Insights.shared(appId: "YourApplicationID")?.isLoggingEnabled = true

After you’ve enabled it, check the output for success messages or errors.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 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 positions, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.