|
| 1 | +# Migrate from 3.x to 4.x |
| 2 | + |
| 3 | +The library version `4.0` uses Kotlin version `2.2` and Algolia Kotlin API Client `3.37`. Below are the steps to migrate. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Requirements](#requirements) |
| 8 | +- [Kotlin API Client](#kotlin-api-client) |
| 9 | +- [Removed Features](#removed-features) |
| 10 | +- [Breaking Changes](#breaking-changes) |
| 11 | + |
| 12 | +## Requirements |
| 13 | + |
| 14 | +InstantSearch Android 4.x has updated minimum requirements: |
| 15 | + |
| 16 | +| Requirement | 3.x | 4.x | |
| 17 | +|----------------|:----------|:----------| |
| 18 | +| Kotlin | 1.9+ | 2.2+ | |
| 19 | +| Android minSdk | 21 | 23 | |
| 20 | +| Android compileSdk | 33 | 35 | |
| 21 | +| Ktor | 2.3 | 3.3 | |
| 22 | +| Algolia Client | 2.x | 3.x | |
| 23 | + |
| 24 | +## Kotlin API Client |
| 25 | + |
| 26 | +The Algolia Kotlin API Client has been upgraded from version `2.x` to `3.x`. This is a major version upgrade with significant changes. |
| 27 | + |
| 28 | +### Key Changes |
| 29 | + |
| 30 | +#### Import Paths |
| 31 | +Some classes may have moved to different packages. Update your imports accordingly. |
| 32 | + |
| 33 | +#### Data Classes |
| 34 | +The primitive wrapper data classes have been removed: |
| 35 | +- `Attribute` - Use `String` directly |
| 36 | +- `ObjectID` - Use `String` directly |
| 37 | +- `AppID` - Use `String` directly |
| 38 | + |
| 39 | +**Before (3.x):** |
| 40 | +```kotlin |
| 41 | +val objectID = ObjectID("my-object-id") |
| 42 | +val attribute = Attribute("category") |
| 43 | +``` |
| 44 | + |
| 45 | +**After (4.x):** |
| 46 | +```kotlin |
| 47 | +val objectID = "my-object-id" |
| 48 | +val attribute = "category" |
| 49 | +``` |
| 50 | + |
| 51 | +#### API Method Changes |
| 52 | +Some API methods and response structures have changed. Refer to the [Algolia Kotlin Client 3.x documentation](https://github.com/algolia/algoliasearch-client-kotlin) for details. |
| 53 | + |
| 54 | +## Removed Features |
| 55 | + |
| 56 | +### SearcherAnswers |
| 57 | +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: |
| 58 | + |
| 59 | +**Removed:** |
| 60 | +- `SearcherAnswers` class |
| 61 | +- `SearcherAnswers` filter-state connection |
| 62 | +- Related telemetry hooks |
| 63 | + |
| 64 | +### SearcherPlaces |
| 65 | +The Places feature has been deprecated and removed. Please refer to [Algolia Places migration guide](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/geo-search/android/) for alternatives. |
| 66 | + |
| 67 | +## Breaking Changes |
| 68 | + |
| 69 | +### Insights Events |
| 70 | +The Insights implementation has been updated to use v3 events: |
| 71 | +- HTTP repository now sends events via `pushEvents` API |
| 72 | +- Filter strings are now parsed into stored filters |
| 73 | +- Automatic hits view tracking uses v3 event format |
| 74 | + |
| 75 | +### Facets |
| 76 | +- Facet list tracing now uses `FacetHits` instead of older structures |
| 77 | +- Facets search now serializes `SearchParamsObject` into `params` for SearchForFacetValues requests |
| 78 | + |
| 79 | +### Dependencies |
| 80 | +If you're updating your project, make sure to update related dependencies: |
| 81 | + |
| 82 | +```gradle |
| 83 | +// Update Kotlin |
| 84 | +kotlin = "2.2.0" |
| 85 | +
|
| 86 | +// Update Algolia Client |
| 87 | +implementation "com.algolia:algoliasearch-client-kotlin:3.37.2" |
| 88 | +
|
| 89 | +// Update Ktor if using directly |
| 90 | +ktor = "3.3.3" |
| 91 | +
|
| 92 | +// Update Compose if using |
| 93 | +androidx.compose.ui = "1.10.0" |
| 94 | +``` |
| 95 | + |
| 96 | +### Migration Steps |
| 97 | + |
| 98 | +1. **Update dependencies** in your `build.gradle` or `gradle/libs.versions.toml` |
| 99 | +2. **Update minimum SDK version** to 23 in your `build.gradle` |
| 100 | +3. **Remove wrapper classes**: Replace `ObjectID`, `Attribute`, `AppID` with `String` |
| 101 | +4. **Remove Answers usage**: If using `SearcherAnswers`, migrate to standard search |
| 102 | +5. **Remove Places usage**: If using `SearcherPlaces`, migrate to alternative geo-search solutions |
| 103 | +6. **Update API calls**: Review and update any direct Algolia API client calls according to client 3.x changes |
| 104 | +7. **Test thoroughly**: The new versions include significant internal changes, so comprehensive testing is recommended |
| 105 | + |
| 106 | +For more details on specific changes, refer to the [CHANGELOG](../../CHANGELOG.md). |
0 commit comments