Guides / Building Search UI / Going further

Send events with InstantSearch iOS

The InstantSearch Insights library allows developers to send click, conversion, and view events. For search-related events, it correlates the event with the queryIDs generated when you’ve set the clickAnalytics parameter to true.

Algolia uses valid search-related events for Click and Conversion Analytics. Click and Conversion Analytics form the foundation for more advanced features like A/B Testing and Dynamic Re-Ranking. Algolia uses all valid events for Personalization. Even if you aren’t planning on implementing Personalization right away, it’s helpful to consider sending events as if you were. This lets you implement Personalization later on with a robust corpus of well-formatted user data.

Supported platforms

InstantSearch Insights iOS is supported on iOS, macOS, tvOS. and watchOS.

Install the InstantSearch Insights library

Add a dependency on InstantSearch Insights using Swift Package Manager, CocoaPods, or Carthage, and add import InstantSearchInsights to your source files.

Swift Package Manager

To use Swift Package Manager, you should use Xcode 11 to open your project. Click File -> Swift Packages -> Add Package Dependency, and enter the URL of the InstantSearch repository (https://github.com/algolia/instantsearch-ios). Select InstantSearchInsights in the list of products that show up.

If you’re a framework author and use InstantSearch Insights as a dependency, update your Package.swift file:

1
2
3
4
5
6
7
let package = Package(
    // 7.7.0 ..< 8.0.0
    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

CocoaPods is a dependency manager for Cocoa projects.

  • If you don’t have CocoaPods installed on your machine, open your terminal and run sudo gem install cocoapods.
  • If your project doesn’t have a Podfile, open your terminal and run pod init to create one.

To install InstantSearch Insights, add the following line to your Podfile:

1
pod 'InstantSearch/Insights', '~> 7.7'
  • On your terminal, run pod update.

Carthage

Carthage is a simple, decentralized dependency manager for Cocoa.

To install InstantSearch, add the following line to your Cartfile:

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

Launch the following commands from the project directory:

1
2
3
carthage update
./Carthage/Checkouts/instant-search-ios/carthage-prebuild
carthage build

Carthage doesn’t provide a way to build only specific subcomponents (or equivalent CocoaPods subspecs) of a repository. It builds all components and their dependencies with the preceding commands. However, you don’t need to copy frameworks you aren’t using into your project. For instance, if you don’t use all the InstantSearch components, you can delete all InstantSearch frameworks except InstantSearchInsights from the Carthage Build directory.

Initialize the Insights client

First, you need to initialize the Insights client with your application ID, API key, and index name: find them in the API Keys section of the dashboard. Every event you send should have a userToken field to specify the user it relates to.

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

Sending events

Once you’ve registered your index with the application ID and the API key, you can start sending events. For examples of the different kinds of events and what user behaviors translate into them, refer to the guide on capturing user behaviors as events.

Insights events (view, click, and conversion) don’t take immediate effect. There’s a delay of from a few minutes up to an hour (depending on whether they’re sent after a search or not and how long after a search they’re sent).

For a better estimation, see how long it takes for Insights events to be taken into account.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Insights.shared?.clickedAfterSearch(eventName: "click event",
                                    indexName: "index name",
                                    objectID: "object id",
                                    position: 1,
                                    queryID: "query id")

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

Insights.shared?.viewed(eventName: "view event",
                        indexName: "index name",
                        filters: ["brand:apple"])

Tracking queryID on other pages

Conversion events don’t always happen on a search results page. For example, a user could buy an item from a product detail page, meaning you must pass the queryID to that page.

Send click events from hits widgets

InstantSearch Insights iOS comes pre-packaged inside InstantSearch iOS. This simplifies the tracking of click events on search results generated using the InstantSearch iOS Hits widgets. You still need to send click events from other sources, and view and conversion events.

If you’re using multiple Hits widgets, you must enable sending click events on each one separately. This gives allows you to decide which click events to track and which to ignore.

1
2
3
4
5
6
7
8
9
let searcher = HitsSearcher(appID: "appID", apiKey: "apiKey", 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)

Logging and debugging

To check if you’ve sent an event, first enable logging:

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

After you’ve enabled it, you can 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.

Customizing the events flush delay

By default, the client transmits tracked events every 30 minutes. You can customize this delay by changing the flushDelay value (in seconds) as follows:

1
Insights.flushDelay = 60

Setting API region

By default, each time you send an event, Algolia geo-routes the API call so that the call targets the closest servers. Today 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
Did you find this page helpful?