Upgrading InstantSearch Android

​

Upgrade from InstantSearch v4 to v5

​

Requirements

​

Update the build tools

[versions]
agp = "9.3.3"
kotlin = "2.4.20"

distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-bin.zip

• AGP includes Kotlin support. Remove the org.jetbrains.kotlin.android (kotlin-android) plugin from your Android modules.
• kotlin { compilerOptions } replaces kotlinOptions.
• composeOptions { kotlinCompilerExtensionVersion } is no longer needed. Apply the org.jetbrains.kotlin.plugin.compose plugin instead.

​

Target Java 11

Cannot inline bytecode built with JVM target 11 into bytecode that is being built with JVM target 1.8

android {
    compileSdk = 35
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

android {
    compileSdk = 37
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
    }
}

​

Update dependencies

implementation 'com.algolia:instantsearch-android:5.+'
implementation 'com.algolia:instantsearch-compose:5.+'          // optional
implementation 'com.algolia:instantsearch-android-paging3:5.+'  // optional
implementation 'com.algolia:instantsearch-android-loading:5.+'  // optional
implementation 'com.algolia:instantsearch-insights-android:5.+' // optional

​

Non-null onCheckedChanged parameters

override fun onCheckedChanged(group: RadioGroup?, checkedId: Int)
override fun onCheckedChanged(buttonView: CompoundButton?, isChecked: Boolean)

override fun onCheckedChanged(group: RadioGroup, checkedId: Int)
override fun onCheckedChanged(buttonView: CompoundButton, isChecked: Boolean)

​

Migration checklist

1. Update the build tools: Gradle 9, AGP 9.1.1 or later, Kotlin 2.4 or later
2. Set compileSdk to 37 in every Android module that depends on InstantSearch
3. Set the Java and Kotlin targets to 11 (compileOptions and jvmTarget) in those modules
4. Remove the kotlin-android plugin and migrate kotlinOptions to kotlin { compilerOptions } if you upgraded from AGP 8
5. Update the InstantSearch dependencies to 5.+
6. Align Compose: use a BOM that maps to Compose 1.12.1 or later, and declare material-icons-core or material-icons-extended if your code uses Icons
7. Fix OnCheckedChangeListener overrides that still use parameters with ?
8. Review the Android 17 behavior changes for your app before you set targetSdk to 37, in particular the large-screen changes (Android ignores orientation and resizing restrictions on screens 600dp and wider) and the local network permission. The library declares no Activity, Service, or permission, so it isn’t affected
9. Run your test suite on an Android 17 emulator or device

​

Upgrade from InstantSearch v3 to v4

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

​

Requirements

​

Wrapper types removed

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

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

val facet = Facet("red", 10)

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

​

Filters

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

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

​

Request options

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

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

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

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

​

Indexable interface

import com.algolia.instantsearch.core.Indexable

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

​

Removed features

​

Dependencies

// 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

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

​

Upgrade from InstantSearch v2 to v3

​

InstantSearch Android package

​

Kotlin API client

​

LogLevel

​

Public constants

​

Ktor client

​

Searchers

​

Extension modules

​

Upgrade from InstantSearch v1 to v2

• 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.