API Reference / InstantSearch Android / QueryRuleCustomData

QueryRuleCustomData

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

About this widget # A

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 # A

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("AJ0P3S7DWQ"),
        apiKey = APIKey("90dfaaf5755e694f341fe68f6e41a6d4"),
        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("AJ0P3S7DWQ"),
        apiKey = APIKey("90dfaaf5755e694f341fe68f6e41a6d4"),
        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 # A

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# A

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("AJ0P3S7DWQ"),
        apiKey = APIKey("90dfaaf5755e694f341fe68f6e41a6d4"),
        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# A

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