InstantSearch Insights has been migrated to the main InstantSearch repository. You still can use the Insights part of the InstantSearch separately by following the provided instructions. This repository is no longer supported, please create your issues and submit your contributions to the main InstantSearch repository.
By Algolia.
InstantSearch Insights iOS library allows developers to capture search-related events. The events maybe 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. As well library allows to capture 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.
InstantSearch Insights iOS is supported on iOS, macOS, tvOS and watchOS, and is usable from both Swift and Objective-C.
- Add a dependency on InstantSearchInsights:
- CocoaPods: add
pod 'InstantSearchInsights', '~> 2.3'
to yourPodfile
. - Carthage: add
github "algolia/instantsearch-ios-insights" ~> 2.3.1
to yourCartfile
.
- Add
import InstantSearchInsights
to your source files.
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 non-specified user token an automatically-generated application-wide user token will be used.
// Swift
Insights.register(appId: "testApp", apiKey: "testKey", userToken: "testToken")
// ObjC
[Insights registerWithAppId:@"testApp"
apiKey:@"testKey"
userToken:@"testToken"];
Once that you registered your Application ID and the API Key you can easily start sending metrics.
// 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"])
// 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];
In case you want to check if the metric was sent correctly, you need to enable the logging first
// Swift
Insights.shared(appId: "appId")?.isLoggingEnabled = true
After you enabled it, you can check the output for success or error messages
// 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)
By default the client transmits tracked events every 30 seconds. You can customize this delay by changing flushDelay
value (in seconds) as follows:
// Swift
Insights.flushDelay = 60
// ObjC
[Insights setFlushDelay: 60];
By default each analytics API call is geo-routed so that each call targets the closest API. Today the analytics API suports two regions: United States and Germany. You can specify the region your prefer to use as follows:
// Swift
Insights.region = .de
// ObjC
[Insights setRegion: [Region de]]];
To get a more meaningful search experience, please follow our Getting Started Guide.
- Need help? Ask a question to the Algolia Community or on Stack Overflow.
- Found a bug? You can open a GitHub issue.
- Questions about Algolia? You can search our FAQ in our website.
- 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.
InstantSearch iOS Insights is MIT licensed.