Upgrading InstantSearch Android

Upgrade your InstantSearch Android version

Upgrade from InstantSearch v3 to v4

In InstantSearch v4.0.0 and later, InstantSearch uses Kotlin 2.2 and the Algolia Kotlin API client 3.x. This client updates models and simplifies types.

Kotlin

val searcher = HitsSearcher(
  applicationID = "ALGOLIA_APPLICATION_ID",
  apiKey = "ALGOLIA_SEARCH_API_KEY",
  indexName = "indexName",
  isAutoSendingHitsViewEvents = true
)

InstantSearch v4.0 is a major upgrade and includes breaking changes. It removes wrapper types and legacy searchers (Answers and Places), and updates Insights to v3 events.

Requirements

InstantSearch Android 4.x has updated minimum requirements:

Requirement	3.x	4.x
Kotlin	1.9+	2.2+
Android minSdk	21	23
Android compileSdk	33	35
Ktor	2.3	3.3
Algolia client	2.x	3.x

Wrapper types removed

The Kotlin API client 3.x removed primitive wrapper types. Use plain String values instead:

Type	3.x	4.x
Application ID	ApplicationID("...")	"..."
API key	APIKey("...")	"..."
Index name	IndexName("...")	"..."
Attribute	Attribute("...")	"..."
Object ID	ObjectID("...")	"..."
Query ID	QueryID("...")	"..."
Event name	EventName("...")	"..."
User token	UserToken("...")	"..."

Before 3.x

val searcher = HitsSearcher(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourSearchOnlyAPIKey"),
    indexName = IndexName("index_name")
)

val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name"
)

Search parameters

Replaces the Query class with SearchParamsObject from the Algolia Kotlin Client 3.x:

Type	3.x	4.x
Query	Query(...)	SearchParamsObject(...)
Search parameters	SearchParameters	SearchParamsObject

Before 3.x

val query = Query(analytics = false)
val searcher = HitsSearcher(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourSearchOnlyAPIKey"),
    indexName = IndexName("index_name"),
    query = query
)

val query = SearchParamsObject(analytics = false)
val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    query = query
)

Response types

Search response types have been updated to match the Kotlin API client 3.x:

Type	3.x	4.x
Search response	ResponseSearch	SearchResponse
Facets response	ResponseSearchForFacets	SearchForFacetValuesResponse
Facet	Facet	FacetHits

Before 3.x

val facet = Facet("red", 10)

val facet = FacetHits("red", "", 10)

Filters

InstantSearch now owns its own filter model. Update your imports:

Type	3.x	4.x
Filter	com.algolia.search.model.filter.Filter	com.algolia.instantsearch.filter.Filter
FilterGroup	com.algolia.search.model.filter.FilterGroup	com.algolia.instantsearch.filter.FilterGroup
NumericOperator	com.algolia.search.model.filter.NumericOperator	com.algolia.instantsearch.filter.NumericOperator

Before 3.x

Filter.Facet(Attribute("color"), "red")

Filter.Facet("color", "red")

Request options

RequestOptions uses immutable construction from the Algolia Kotlin Client 3.x:

Before 3.x

val requestOptions = RequestOptions().also {
    it.headers[KeyForwardedFor] = "1.2.3.4"
}

val requestOptions = RequestOptions(
    headers = mapOf("X-Forwarded-For" to "1.2.3.4")
)

Insights

Insights has been updated to use v3 events and the pushEvents API:

Type	3.x	4.x
Event construction	InsightsEvent.Click(...)	Direct method calls
Event names	EventName("...")	"..."
User tokens	UserToken("...")	"..."

Before 3.x

sharedInsights?.clicked(
    InsightsEvent.Click(
        eventName = EventName("eventName"),
        indexName = IndexName("indexName"),
        userToken = UserToken("userToken"),
        timestamp = System.currentTimeMillis(),
        queryID = QueryID("queryId"),
        resources = InsightsEvent.Resources.ObjectIDs(
            listOf(ObjectID("objectID1"))
        )
    )
)

sharedInsights?.clickedObjectIDsAfterSearch(
    eventName = "eventName",
    indexName = "indexName",
    userToken = "userToken",
    timestamp = System.currentTimeMillis(),
    queryID = "queryId",
    objectIDs = listOf("objectID1"),
    positions = listOf(1)
)

Trackers

Tracker initialization now uses String for event names:

Before 3.x

val hitsTracker = HitsTracker(
    eventName = EventName("hits"),
    searcher = searcher,
    insights = sharedInsights(indexName)
)

val hitsTracker = HitsTracker(
    eventName = "hits",
    searcher = searcher,
    insights = sharedInsights(indexName)
)

Indexable interface

Hit models for tracking must implement the Indexable interface:

Kotlin

import com.algolia.instantsearch.core.Indexable

data class Product(
    override val objectID: String,
    val name: String
) : Indexable

Removed features

The following features have been removed in v4:

Feature	Status
SearcherAnswers	Removed (Answers deprecated by Algolia)
SearcherPlaces	Removed (Places deprecated by Algolia)
Wrapper types (Attribute, ObjectID, etc.)	Removed (use String)

Dependencies

Update your dependencies in build.gradle or gradle/libs.versions.toml:

// Kotlin
kotlin = "2.2.0"

// Algolia
implementation("com.algolia:instantsearch-android:4.0.0")
implementation("com.algolia:algoliasearch-client-kotlin:3.37.2")

// Ktor (if using directly)
ktor = "3.3.3"

// Compose (if using)
composeUi = "1.10.0"
composeCompiler = "2.2.0"

Migration checklist

1. Update dependencies to the versions listed above
2. Update minSdk to 23 in your build.gradle
3. Remove wrapper types: replace ApplicationID, APIKey, IndexName, Attribute, ObjectID, QueryID, EventName, UserToken with plain String
4. Update query types: replace Query with SearchParamsObject
5. Update response types: replace ResponseSearch with SearchResponse, Facet with FacetHits
6. Update filter imports: use com.algolia.instantsearch.filter.Filter instead of com.algolia.search.model.filter.Filter
7. Update Insights: use v3 event methods instead of InsightsEvent constructors
8. Implement Indexable: ensure hit models implement Indexable for tracking
9. Remove Answers/Places: if using SearcherAnswers or SearcherPlaces, migrate to standard search
10. Test thoroughly: the new versions include significant internal changes

Upgrade event tracking

Starting from v3.2.0, InstantSearch makes it easier to send view events using the isAutoSendingHitsViewEvents option on HitsSearcher:

Kotlin

val searcher = HitsSearch(
  applicationID = ApplicationID("ALGOLIA_APPLICATION_ID"),
  apiKey = APIKey("ALGOLIA_SEARCH_API_KEY"),
  indexName = IndexName("indexName"),
  isAutoSendingHitsViewEvents = true
)

From v3.2.0 to v3.3.0, this option was set to true by default. Ensure you’re using the latest version of InstantSearch to send the required events.

Upgrade from InstantSearch v2 to v3

The library version 3.0 uses Kotlin 1.6 and Algolia Kotlin API Client 2.0. Below are the steps to migrate.

This new version removes all deprecated methods and features from v2.

InstantSearch Android package

InstantSearch Android package has changed. Update your imports accordingly:

Module	2.x	3.x
InstantSearch Android	com.algolia.instantsearch.helper.android	com.algolia.instantsearch.android

Kotlin API client

The Kotlin API client (and its underlying Ktor client) is part of the library’s binary interface. Read the migration guide, or apply the following changes:

LogLevel

The library uses LogLevel from the Kotlin API client instead of Ktor’s Loglevel:

Subsystem	2.x	3.x
LogLevel	io.ktor.client.features.logging.LogLevel	com.algolia.search.logging.LogLevel

Public constants

Constants (for example, KeyIndexName, KeyEnglish, and RouteIndexesV1) aren’t exposed. Use your constants instead.

Ktor client

For more information, refer to Ktor’s migration guide.

Searchers

Legacy searchers are removed. Migrate as follows:

Searcher	2.x	3.x
Single Index Searcher	SearcherSingleIndex	HitsSearcher
Facets Searcher	SearcherForFacets	FacetsSearcher
Multi Index Searcher	SearcherMultipleIndex	MultiSearcher

Extension modules

Multiple extensions have been extracted to modules:

Subsystem	Module
AndroidX SwipeRefreshLayout	com.algolia:instantsearch-android-loading
AndroidX Paging 3	com.algolia:instantsearch-android-paging3
AndroidX Paging 2	Removed

Upgrade from InstantSearch v1 to v2

InstantSearch v2 introduces a new architecture and new widgets, which brings several breaking changes from v1:

• No longer an InstantSearch component automatically connecting widgets. You are now in control of the Searcher and responsible for connecting and disconnecting it from widgets and other components.

• The widgets are now built around ViewModels, holding their data and business logic.

  Compared to the V1 where widgets were Android Views, now the core of the widget is its view-model, and the UI is behind an interface to ensure minimal coupling.

You can learn more about the philosophy of InstantSearch v2 in What is InstantSearch. Once ready to start migrating, learn the steps to building an InstantSearch v2 app in the getting started guide..

The InstantSearch Android v1 documentation is available on the legacy docs page.