This guide walks you through the steps needed to create a full InstantSearch Android experience from scratch.
This guide walks you through the steps needed to create a full InstantSearch Android experience from scratch.
It includes:
* A search box for users to type queries
* A list to display search results
* A list to results
* Statistics about the search
## Before you begin
To use InstantSearch, you need an Algolia account.
[Sign up](https://dashboard.algolia.com/users/sign_up) for a new account or use the following credentials
(which include a pre-loaded dataset of products appropriate for this guide):
* : `latency`
* Search : `1f6fd3a6fb973cb08419fe7d288fa4db`
- name: `instant_search`
### Create a new project and add InstantSearch Android
In Android Studio, create a new Project:
* On the Target screen, select **Phone and Tablet**
* On the Add an Activity screen, select **Empty Activity**
In your app's `build.gradle`, add the following dependency:
```groovy build.gradle icon=braces theme={"system"}
implementation 'com.algolia:instantsearch-android:4.+'
implementation 'com.algolia:instantsearch-android-paging3:4.+'
```
This guide uses InstantSearch Android with [Android Architecture Components](https://developer.android.com/topic/libraries/architecture), so you also need to add the following dependencies:
```groovy build.gradle icon=braces theme={"system"}
implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.+'
implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.+'
```
To perform network operations in your app, `AndroidManifest.xml` must include the following permissions:
```xml XML icon=code-xml theme={"system"}
```
Setup [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization#setup) by adding the serialization plugin to your `build.gradle`:
```groovy build.gradle icon=braces theme={"system"}
plugins {
// ...
id 'org.jetbrains.kotlin.plugin.serialization' version '2.2.0'
}
```
## Implementation
### Architecture overview
* `MainActivity`: This activity controls the displayed fragment.
* `MyViewModel`: A `ViewModel` from Android Architecture Components. The business logic lives here.
* `ProductFragment`: This fragment displays a list of search results in a `RecyclerView`, a `SearchView` input, and a `Stats` indicator.
* `FacetFragment`: This fragment displays a list of facets to filter your search results.
### Initialize a searcher
The central part of your search experience is the `Searcher`.
The `Searcher` performs a and obtains search results.
Most InstantSearch components connected to the `Searcher`.
In this guide, you'll only target one index, so instantiate a `HitsSearcher` with the proper credentials.
Go to `MyViewModel.kt` file and add the following code:
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
val searcher = HitsSearcher(
applicationID = "latency",
apiKey = "1f6fd3a6fb973cb08419fe7d288fa4db",
indexName = "instant_search"
)
override fun onCleared() {
super.onCleared()
searcher.cancel()
}
}
```
A `ViewModel` is a good place to put your data sources. This way, the data persists during orientation changes and you can share it across multiple fragments.
### Display results: `Hits`
Suppose you want to display search results in a `RecyclerView`.
To simultaneously provide a good user experience and display thousands of products,
you can implement an infinite scrolling mechanism using the [Paging Library](https://developer.android.com/topic/libraries/architecture/paging) from Android Architecture Component.
To display your results:
Create a `LiveData` object, which holds a `PagedList` of `Product`.
Create the `Product` data class which contains a single `name` field.
```kotlin Kotlin icon=code theme={"system"}
@Serializable
data class Product(
val name: String
)
```
Create the `product_item.xml` file.
```xml XML icon=code-xml theme={"system"}
```
Create the `ProductViewHolder` to bind a `Product` item to a `RecyclerView.ViewHolder`.
```kotlin Kotlin icon=code theme={"system"}
class ProductViewHolder(view: View) : RecyclerView.ViewHolder(view) {
private val itemName = view.findViewById(R.id.itemName)
fun bind(product: Product) {
itemName.text = product.name
}
}
```
Create a `ProductAdapter` by extending `PagingDataAdapter`. The `ProductAdapter` binds products to the `ViewHolder`.
```kotlin Kotlin icon=code theme={"system"}
class ProductAdapter : PagingDataAdapter(ProductDiffUtil) {
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ProductViewHolder {
return ProductViewHolder(parent.inflate(R.layout.list_item_small))
}
override fun onBindViewHolder(holder: ProductViewHolder, position: Int) {
getItem(position)?.let { holder.bind(it) }
}
object ProductDiffUtil : DiffUtil.ItemCallback() {
override fun areItemsTheSame(oldItem: Product, newItem: Product) = oldItem.objectID == newItem.objectID
override fun areContentsTheSame(oldItem: Product, newItem: Product) = oldItem == newItem
}
}
```
In your `ViewModel` use a `Paginator` with your searcher:
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
// Searcher initialization
// ...
val paginator = Paginator(
searcher = searcher,
pagingConfig = PagingConfig(pageSize = 50, enablePlaceholders = false),
transformer = { hit -> hit.deserialize(Product.serializer()) }
)
override fun onCleared() {
super.onCleared()
searcher.cancel()
}
}
```
Now that your `ViewModel` has some data, you can create a simple `product_fragment.xml` with a `Toolbar` and a `RecyclerView` to display the products:
```xml XML icon=code theme={"system"}
```
In the `ProductFragment`, get a reference of `MyViewModel` using `activityViewModels()`.
Then, observe the `LiveData` to update the `ProductAdapter` on every new page of products.
Finally, configure the `RecyclerView` by setting its adapter and `LayoutManager`.
```kotlin Kotlin icon=code theme={"system"}
class ProductFragment : Fragment(R.layout.fragment_product) {
private val viewModel: MyViewModel by activityViewModels()
private val connection = ConnectionHandler()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
val adapterProduct = ProductAdapter()
viewModel.paginator.liveData.observe(viewLifecycleOwner) { pagingData ->
adapterProduct.submitData(lifecycle, pagingData)
}
view.findViewById(R.id.productList).let {
it.itemAnimator = null
it.adapter = adapterProduct
it.layoutManager = LinearLayoutManager(requireContext())
it.autoScrollToStart(adapterProduct)
}
}
override fun onDestroyView() {
super.onDestroyView()
connection.clear()
}
}
```
To display the `ProductFragment`, update `activity_main.xml` to have a container for the fragments:
```xml XML icon=code theme={"system"}
```
Update `MainActivity` to display `ProductFragment`:
```kotlin Kotlin icon=code theme={"system"}
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
showProductFragment()
}
fun showProductFragment() {
supportFragmentManager.commit {
replace(R.id.container)
}
}
}
```
You have now learned how to display search results in an infinite scrolling `RecyclerView`.
### Searching your data: `SearchBox`
To search your data, users need an input field. Any change in this field should trigger a new request, and then update the search results.
To achieve this, use a `SearchBoxConnector`. This takes a `Searcher` and connected to `Pagiantor` using `connectPaginator`.
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
// Searcher initialization
// Hits initialization
// ...
val searchBox = SearchBoxConnector(searcher)
val connection = ConnectionHandler(searchBox)
init {
connection += searchBox.connectPaginator(paginator)
}
override fun onCleared() {
super.onCleared()
searcher.cancel()
connection.clear()
}
}
```
Most InstantSearch components should be connected and disconnected in accordance to the [Android Lifecycle](https://developer.android.com/topic/libraries/architecture/lifecycle) to avoid memory leaks.
A `ConnectionHandler` handles a set of `Connection` s for you: Each `+=` call with a component implementing the `Connection` interface will connect it and make it active. Whenever you want to free resources or deactivate a component, call the `disconnect` method.
You can now add a `SearchView` in your `Toolbar`:
```xml XML icon=code-xml theme={"system"}
```
Connect the `SearchBoxViewAppCompat` to the `SearchBoxConnectorPagedList` stored in `MyViewModel` using a new `ConnectionHandler` that conforms to the `ProductFragment` lifecycle:
```kotlin Kotlin icon=code theme={"system"}
class ProductFragment : Fragment(R.layout.fragment_product) {
private val viewModel: MyViewModel by activityViewModels()
private val connection = ConnectionHandler()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
// Hits
// ...
val searchBoxView = SearchBoxViewAppCompat(searchView)
connection += viewModel.searchBox.connectView(searchBoxView)
}
override fun onDestroyView() {
super.onDestroyView()
connection.clear()
}
}
```
You can now build and run your app, and see a basic search experience. The results change with each key stroke.
### Displaying metadata: `Stats`
It's a good practice to show the number of hits that were returned for a search. You can use the `Stats` components to do this with minimal code.
Add a `StatsConnector` to your `MyViewModel`, and connect it with a `ConnectionHandler`.
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
// Searcher initialization
// Hits initialization
// SearchBox initialization
// ...
val stats = StatsConnector(searcher)
val connection = ConnectionHandler(searchBox, stats)
override fun onCleared() {
super.onCleared()
searcher.cancel()
connection.clear()
}
}
```
Add a `TextView` to your `product_fragment.xml` file to display the stats.
```xml XML icon=code-xml theme={"system"}
```
Next, connect the `StatsConnector` to a `StatsTextView` in your `ProductFragment`.
```kotlin Kotlin icon=code theme={"system"}
class ProductFragment : Fragment(R.layout.fragment_product) {
private val viewModel: MyViewModel by activityViewModels()
private val connection = ConnectionHandler()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
// Hits
// SearchBox
// ...
val statsView = StatsTextView(view.findViewById(R.id.stats))
connection += viewModel.stats.connectView(statsView, DefaultStatsPresenter())
}
override fun onDestroyView() {
super.onDestroyView()
connection.clear()
}
}
```
You can now build and run your app and see your new search experience in action.
### Filter your data: `FacetList`
Filtering search results helps your users find what they want. You can create a `FacetList` to filter products by category.
Create a drawable resource `ic_check.xml`. This resource displays checked filters.
```xml XML icon=code-xml theme={"system"}
```
Create a `facet_item.xml` file. This is the layout for a `RecyclerView.ViewHolder`.
```xml XML icon=code-xml theme={"system"}
```
Implement the `FacetListViewHolder` and its `Factory`, so that later on it works with a `FacetListAdapter`.
```kotlin Kotlin icon=code theme={"system"}
import com.algolia.client.model.search.FacetHits
class MyFacetListViewHolder(view: View) : FacetListViewHolder(view) {
override fun bind(facet: FacetHits, selected: Boolean, onClickListener: View.OnClickListener) {
view.setOnClickListener(onClickListener)
val facetCount = view.findViewById(R.id.facetCount)
facetCount.text = facet.count.toString()
facetCount.visibility = View.VISIBLE
view.findViewById(R.id.icon).visibility = if (selected) View.VISIBLE else View.INVISIBLE
view.findViewById(R.id.facetName).text = facet.value
}
object Factory : FacetListViewHolder.Factory {
override fun createViewHolder(parent: ViewGroup): FacetListViewHolder {
return MyFacetListViewHolder(parent.inflate(R.layout.list_facet_selectable))
}
}
}
```
You can use a new component to handle the filtering logic: the [`FilterState`](/doc/api-reference/widgets/filter-state/android).
Pass the `FilterState` to your `FacetListConnector`. The `FacetListConnector` needs an attribute: you should use `"categories"`.
Inject `MyFacetListViewHolder.Factory` into your `FacetListAdapter`. The `FacetListAdapter` is an out of the box `RecyclerView.Adapter` for a `FacetList`.
Connect the different parts together:
* The `Searcher` connects itself to the `FilterState`, and applies its filters with every search.
* The `FilterState` connects to your products `Paginator` to invalidate search results when new filter are applied.
* The `facetList` connects to its adapter.
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
// Client, Searcher...
// Products
// Stats
// ...
val filterState = FilterState()
val facetList = FacetListConnector(
searcher = searcher,
filterState = filterState,
attribute = "categories",
selectionMode = SelectionMode.Single
)
val facetPresenter = DefaultFacetListPresenter(
sortBy = listOf(FacetSortCriterion.CountDescending, FacetSortCriterion.IsRefined),
limit = 100
)
val connection = ConnectionHandler(searchBox, stats, facetList)
init {
// SearchBox
// ..
connection += searcher.connectFilterState(filterState)
connection += filterState.connectPaginator(paginator)
}
override fun onCleared() {
super.onCleared()
searcher.cancel()
connection.clear()
}
}
```
To display your facets, create a `facet_fragment.xml` layout with a `RecyclerView`.
```xml XML icon=code-xml theme={"system"}
```
Create a `FacetFragment` and configure your `RecyclerView` with its adapter and `LayoutManager`.
```kotlin Kotlin icon=code theme={"system"}
class FacetFragment : Fragment(R.layout.fragment_facet) {
private val viewModel: MyViewModel by activityViewModels()
private val connection = ConnectionHandler()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
val adapterFacet = FacetListAdapter(MyFacetListViewHolder.Factory)
val facetList = view.findViewById(R.id.facetList)
connection += viewModel.facetList.connectView(adapterFacet, viewModel.facetPresenter)
facetList.let {
it.adapter = adapterFacet
it.layoutManager = LinearLayoutManager(requireContext())
it.autoScrollToStart(adapterFacet)
}
}
override fun onDestroyView() {
super.onDestroyView()
connection.clear()
}
}
```
Add the code to switch to `FacetFragment` in `MainActivity` with "navigation up" support.
```kotlin Kotlin icon=code theme={"system"}
class MainActivity : AppCompatActivity() {
val viewModel: MyViewModel by viewModels()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_getting_started)
showProductFragment()
}
private fun showFacetFragment() {
supportFragmentManager.commit {
add(R.id.container)
addToBackStack("facet")
}
}
private fun showProductFragment() {
supportFragmentManager.commit {
replace(R.id.container)
}
}
override fun onSupportNavigateUp(): Boolean {
if (supportFragmentManager.popBackStackImmediate()) return true
return super.onSupportNavigateUp()
}
}
```
Add a filters button in `product_fragment.xml`
```xml XML icon=code-xml theme={"system"}
```
Add `displayFilters` and `navigateToFilters()` to `MyViewModel` to trigger filters display:
```kotlin Kotlin icon=code theme={"system"}
class MyViewModel : ViewModel() {
// Client, Searcher...
// Products
// Stats
// FilterState
// ...
private val _displayFilters = MutableLiveData()
val displayFilters: LiveData get() = _displayFilters
fun navigateToFilters() {
_displayFilters.value = Unit
}
override fun onCleared() {
super.onCleared()
searcher.cancel()
connection.clear()
}
}
```
In `ProductFragment`, add a listener to the filters button to switch to `FacetFragment`:
```kotlin Kotlin icon=code theme={"system"}
class ProductFragment : Fragment() {
private val connection = ConnectionHandler()
override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
return inflater.inflate(R.layout.product_fragment, container, false)
}
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
val viewModel = ViewModelProvider(requireActivity())[MyViewModel::class.java]
// Hits
// SearchBox
// Stats
// ...
view.findViewById
To display your results:
Filtering search results helps your users find what they want. You can create a `FacetList` to filter products by category.
Create a drawable resource `ic_check.xml`. This resource displays checked filters.
```xml XML icon=code-xml theme={"system"}