Implement Click and Conversion Analytics

Embedded Click Analytics for hit events

InstantSearch Insights comes pre-packaged inside InstantSearch iOS starting from version 3.2. You can use a simplified approach for activation of hits click events capturing on the hits widgets provided with InstantSearch iOS. The capturing of click analytics events must be activated on each hits widget separately, giving you the flexibility to decide which click events are captured, and which are ignored.

Capturing of Click Analytics event on hits widget

Activation

1. Set enableClickAnalytics boolean property of hits widget to true
2. Set a non-nil string value to hitClickEventName property of hits widget instance. This value will appear as a click event name on the dashboard. If hitClickEventName property value is nil, no Click Analytics event will be captured for this widget. By default its value is nil.

Example:

1
2
3
let widget: HitsTableWidget = ...
widget.enableClickAnalytics = true
widget.hitClickEventName = "my event name"

Capturing of Click Analytics event on multi-hits widget

Activation

The setup is the same as for single index hits widget, but you must specify a click event name for each section of widget.

1. Set enableClickAnalytics boolean property of hits widget to true
2. Specify a non-nil string for each section you want to track using setHitClick(eventName: String, forSection: Int) method. This value will appear as a click event name of click analytics on the dashboard. If nil value is set for a section, no Click Analytics event will be captured for this section of widget. By default the value of click event name for each section is nil.

Example:

1
2
3
4
let widget: MultiHitsTableWidget = ...
widget.enableClickAnalytics = true
widget.setHitClick(eventName: "my event name 0", forSection: 0)
widget.setHitClick(eventName: "my event name 1", forSection: 1)

For a further event capturing configuration including Personalization, please use Insights library explicitly as described further.

Using Algolia Insights with iOS InstantSearch

Introduction

InstantSearch Insights iOS library allows developers to capture search-related events. The events may be related to search queries (such as click an conversion events used for Click Analytics or A/B testing). It does so by correlating events with queryIDs generated by the search API when a query parameter clickAnalytics=true is set. Additionally, the library captures search-independent events which can be used for the purpose of search experience personalization. There are three types of these events which are currently supported: click, conversion, and view.

Supported platforms

InstantSearch Insights iOS is supported on iOS, macOS, tvOS and watchOS, and is usable from both Swift and Objective-C.

Install

1. Add a dependency on InstantSearchInsights:
   • CocoaPods: add pod 'InstantSearchInsights', '~> 2.0.0' to your Podfile.
   • Carthage: add github "algolia/instantsearch-ios-insights" ~> 2.0.0 to your Cartfile.
2. Add import InstantSearchInsights to your source files.

Initialize the Insights client

You first need to initialize the Insights client. For that you need your Application ID and API Key. You can find them on your Algolia account. Also, for the purpose of personalization an application User Token can be specified via the corresponding optional parameter. In case of a non-specified user token, an automatically-generated application-wide user token will be used.

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

1
2
3
4
// ObjC
[Insights registerWithAppId:@"testApp"
                     apiKey:@"testKey"
                  userToken:@"testToken"];

Sending metrics

Insights events (click, conversion, view) used for analytics and/or personalization do not take immediate effect. The delay can range from 10 to 60 minutes depending on how long after the search they are sent. For precise times, see our page on when Insights events take effect.

Once you have registered your index with the Application ID and the API key, you can easily start sending metrics.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Swift
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"])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// ObjC
[[Insights shared] clickedAfterSearchWithEventName:@"click event"
                                         indexName:@"index name"
                                          objectID:@"object id"
                                          position:1
                                           queryID:@"query id"
                                         userToken:nil];

[[Insights shared] convertedAfterSearchWithEventName:@"conversion event"
                                           indexName:@"index name"
                                            objectID:@"object id"
                                             queryID:@"query id"
                                           userToken:nil];

[[Insights shared] viewedWithEventName:@"view event"
                             indexName:@"index name"
                               filters:@[@"brand:apple"]
                             userToken:nil];

Logging and debugging

In case you want to check if the metric was sent correctly, you need to enable the logging first.

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

After you 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)

Events flush delay

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

1
2
// Swift
Insights.flushDelay = 60

1
2
// ObjC
[Insights setFlushDelay: 60];

Setting API region

By default each analytics API call is geo-routed so that each call targets the closest API. Today the analytics API supports two regions: United States and Germany. You can specify the region your prefer to use as follows:

1
2
// Swift
Insights.region = .de

1
2
// ObjC
[Insights setRegion: [Region de]]];

Usage

Check InstantSearch Insights for iOS and the general Click Analytics Overview.

To get a more meaningful search experience, please follow our Getting Started Guide.

Getting Help

• Need help? Ask a question to the Algolia Community or on Stack Overflow.
• Found a bug? You can open a GitHub issue.

Getting involved

• If you want to contribute please feel free to submit pull requests.
• If you have a feature request please open an issue.
• If you use InstantSearch in your app, we would love to hear about it! Drop us a line on discourse or twitter.