> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QueryRuleCustomData

> Shows custom data from applied index rules.

```kotlin Signature theme={"system"}
QueryRuleCustomDataConnector(
    searcher: HitsSearcher,
    initialItem: T?,
    presenter: QueryRuleCustomDataPresenter<T>?,
)
```

## About this widget

The `QueryRuleCustomData` widget displays custom data from [Rules](/doc/guides/managing-results/rules/detecting-intent).

You can use this widget to display banners or recommendations returned by rules when they match search parameters.

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-android/tree/master/examples/android">
  Browse the QueryRuleCustomData example code on GitHub.
</Card>

## Examples

Instantiate a `QueryRuleCustomDataConnector` and launch an initial search on its [`Searcher`](/doc/api-reference/widgets/instantsearch/android), triggering a Rule that returns custom data.

### Android view

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {

    @Serializable
    data class Banner(val text: String) // Custom data model

    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(searcher)
    val connection = ConnectionHandler(queryRuleCustomData)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val bannerView = TextView(this)

        queryRuleCustomData.subscribe { banner ->
            banner?.text?.let { bannerView.text = it } // Display the banner
        }

        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

### Compose UI

InstantSearch provides the `QueryRuleCustomDataState` as a state model,
which is an implementation of the `QueryRuleCustomDataPresenter` interface.

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val queryRuleCustomDataState = QueryRuleCustomDataState<Banner>()
    val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(
        searcher = searcher,
        presenter = queryRuleCustomDataState
    )
    val connection = ConnectionHandler(queryRuleCustomData)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MyQueryRuleCustomData(queryRuleCustomDataState) // your own UI composable to display your custom data
        }
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}

@Serializable
data class Banner(val text: String) // your custom data model
```

## Parameters

<ParamField body="searcher" type="HitsSearcher" required>
  The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
</ParamField>

<ParamField body="initialItem" type="T?">
  Initial model value.
</ParamField>

<ParamField body="presenter" type="QueryRuleCustomDataPresenter<T>?">
  The Presenter defining how a model appears.

  ```kotlin Kotlin icon=code theme={"system"}
  val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(searcher) { banner ->
      bannerView.text = banner.text
  }
  ```
</ParamField>

## Low-level API

If you want to fully control the `QueryRuleCustomData` components and connect them manually,
you can use the following components:

* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches.
* `QueryRuleCustomDataViewModel`. The component encapsulating the logic applied to the custom model.
* `QueryRuleCustomDataPresenter`. Defines how to interact with a model.

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {

    @Serializable
    data class Banner(val text: String) // Custom data model

    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val queryRuleCustomDataViewModel = QueryRuleCustomDataViewModel(Banner.serializer())
    val queryRuleCustomData = QueryRuleCustomDataConnector(searcher, queryRuleCustomDataViewModel)
    val connection = ConnectionHandler(queryRuleCustomData)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val bannerView = TextView(this)

        queryRuleCustomData.subscribe { banner ->
            banner?.text?.let { bannerView.text = it } // Display the banner
        }

        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

## Serialization

You must provide a `DeserializationStrategy<T>` implementation to deserialize your custom models.
To do this, annotate your custom model class with `@Serialization`.
The Kotlin serialization compiler plugin then automatically generates an implementation for you,
accessible using the `.serializer()` function on the class's companion object.

### Example

Suppose your custom JSON data contains a banner URL that can be decoded to the following structure:

```kotlin Kotlin icon=code theme={"system"}
@Serializable
data class Banner(val bannerUrl: String)
```

You can then either explicitly pass your serializer to the widget:

```kotlin Kotlin icon=code theme={"system"}
val queryRuleCustomData = QueryRuleCustomData(searcher, Banner.serializer())
```

Or, pass your custom model class as a generic argument:

```kotlin Kotlin icon=code theme={"system"}
val queryRuleCustomData = QueryRuleCustomData<Banner>(searcher)
```