API Reference / InstantSearch Android / QueryRuleCustomData

QueryRuleCustomData

Signature 
QueryRuleCustomDataConnector(
    searcher: HitsSearcher,
    initialItem: T?,
    presenter: QueryRuleCustomDataPresenter<T>?,
)
See code examples

About this widget

The QueryRuleCustomData widget displays custom data from Rules.

You may want to use this widget to display banners or recommendations returned by Rules, and that match search parameters.

Examples

Instantiate a QueryRuleCustomDataConnector and launch an initial search on its Searcher, triggering a Rule that returns custom data.

Android view

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class MyActivity : AppCompatActivity() {

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

    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = 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.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = 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

searcher
type: HitsSearcher
Required

The Searcher that handles your searches.
initialItem
type: T?
Optional

Initial model value.
presenter
type: QueryRuleCustomDataPresenter<T>?
Optional

The Presenter defining how a model appears.
Copy 
1
2
3

val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(searcher) { banner ->
    bannerView.text = banner.text
}

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 that handles your searches.
  • QueryRuleCustomDataViewModel: The component encapsulating the logic applied to the custom model.
  • QueryRuleCustomDataPresenter: Defines the way we want to interact with a model.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

class MyActivity : AppCompatActivity() {

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

    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = 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. An easy way to achieve this is to 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

Let’s assume your custom JSON data contains a banner URL that can be decoded to the following structure:

Copy 
1
2

@Serializable
data class Banner(val bannerUrl: String)

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

Copy 
1

val queryRuleCustomData = QueryRuleCustomData(searcher, Banner.serializer())

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

Copy 
1

val queryRuleCustomData = QueryRuleCustomData<Banner>(searcher)
Did you find this page helpful?
InstantSearch Android v3