Skip to content

Migration_3.x_4.x.md

Latest commit

 

History

History
106 lines (77 loc) · 3.58 KB

Migration_3.x_4.x.md

File metadata and controls

106 lines (77 loc) · 3.58 KB

Migrate from 3.x to 4.x

The library version 4.0 uses Kotlin version 2.2 and Algolia Kotlin API Client 3.37. Below are the steps to migrate.

Table of Contents

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

Kotlin API Client

The Algolia Kotlin API Client has been upgraded from version 2.x to 3.x. This is a major version upgrade with significant changes.

Key Changes

Import Paths

Some classes may have moved to different packages. Update your imports accordingly.

Data Classes

The primitive wrapper data classes have been removed:

  • Attribute - Use String directly
  • ObjectID - Use String directly
  • AppID - Use String directly

Before (3.x):

val objectID = ObjectID("my-object-id")
val attribute = Attribute("category")

After (4.x):

val objectID = "my-object-id"
val attribute = "category"

API Method Changes

Some API methods and response structures have changed. Refer to the Algolia Kotlin Client 3.x documentation for details.

Removed Features

SearcherAnswers

The Answers feature has been removed as it's no longer supported by Algolia. If you were using SearcherAnswers, you'll need to migrate to alternative search approaches:

Removed:

  • SearcherAnswers class
  • SearcherAnswers filter-state connection
  • Related telemetry hooks

SearcherPlaces

The Places feature has been deprecated and removed. Please refer to Algolia Places migration guide for alternatives.

Breaking Changes

Insights Events

The Insights implementation has been updated to use v3 events:

  • HTTP repository now sends events via pushEvents API
  • Filter strings are now parsed into stored filters
  • Automatic hits view tracking uses v3 event format

Facets

  • Facet list tracing now uses FacetHits instead of older structures
  • Facets search now serializes SearchParamsObject into params for SearchForFacetValues requests

Dependencies

If you're updating your project, make sure to update related dependencies:

// Update Kotlin
kotlin = "2.2.0"

// Update Algolia Client
implementation "com.algolia:algoliasearch-client-kotlin:3.37.2"

// Update Ktor if using directly
ktor = "3.3.3"

// Update Compose if using
androidx.compose.ui = "1.10.0"

Migration Steps

  1. Update dependencies in your build.gradle or gradle/libs.versions.toml
  2. Update minimum SDK version to 23 in your build.gradle
  3. Remove wrapper classes: Replace ObjectID, Attribute, AppID with String
  4. Remove Answers usage: If using SearcherAnswers, migrate to standard search
  5. Remove Places usage: If using SearcherPlaces, migrate to alternative geo-search solutions
  6. Update API calls: Review and update any direct Algolia API client calls according to client 3.x changes
  7. Test thoroughly: The new versions include significant internal changes, so comprehensive testing is recommended

For more details on specific changes, refer to the CHANGELOG.