Send Personalization Events iOS InstantSearch
InstantSearch Insights comes pre-packaged inside InstantSearch iOS starting from version 3.2. You can use a simplified approach for activating personalization events by capturing the hits widget provided with InstantSearch iOS.
Click and conversion events sent can be used for personalization purposes as well. Some events however can only be used for personalization purposes.
Capturing events on hits widget
Enabling click analytics
- Set
enableClickAnalytics
boolean property of hits widget totrue
- 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 and can be used in your personalization strategy. IfhitClickEventName
property value isnil
, no Click Analytics event will be captured for this widget. By default its value isnil
.
Example:
1
2
3
let widget: HitsTableWidget = ...
widget.enableClickAnalytics = true
widget.hitClickEventName = "my event name"
Capturing events on multi-hits widget
Enabling click analytics
The setup on the multi-hits widget is the same as the setup for single index hits widget, but you must specify a click event name for each section of widget.
- Set
enableClickAnalytics
boolean property of hits widget totrue
. - 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 on the dashboard and can be used in your personalization strategy. Ifnil
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 isnil
.
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 further event-capturing configuration including Personalization, please use Insights library explicitly as described further.
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.
Using Algolia Insights with iOS InstantSearch
Supported platforms
InstantSearch Insights iOS is supported on iOS, macOS, tvOS and watchOS, and is usable from both Swift and Objective-C.
Install
- Add a dependency on InstantSearchInsights:
- CocoaPods: add
pod 'InstantSearchInsights', '~> 2.0.0'
to yourPodfile
. - Carthage: add
github "algolia/instantsearch-ios-insights" ~> 2.0.0
to yourCartfile
.
- CocoaPods: add
- 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 the 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"];
Events
Sending events
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
// Swift
Insights.shared?.clicked(eventName: "click event",
indexName: "index name",
objectID: "object id"
Insights.shared?.converted(eventName: "conversion event",
indexName: "index name",
objectIDs: ["obj1", "obj2"]
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
// ObjC
[[Insights shared] clickedWithEventName:@"click event"
indexName:@"index name"
objectID:@"object id"
userToken:nil];
[[Insights shared] convertedWithEventName:@"conversion event"
indexName:@"index name"
objectID:@"object 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
// Success
[Algolia Insights - appName] Sync succeeded for EventsPackage(id: "37E9A093-8F86-4049-9937-23E99E4E4B33", events: [{
eventName = "search result click";
eventType = click;
index = "my index";
objectIDs = (
1234567
);
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]]];