Suggest

The API for the SuggestStore can be found in the MozillaComponents Kotlin documentation.

Note

Make sure you initialize Viaduct for this component.

Warning

The SuggestStore is synchronous, which means it needs to be wrapped in the asynchronous primitive of the target language you are using.

Setting up the store

You need to import one or more of the following primitives to work with the SuggestStore (these come from the generated suggest.kt file, produced by uniffi):

import mozilla.appservices.remotesettings.RemoteSettingsServer
import mozilla.appservices.suggest.SuggestApiException
import mozilla.appservices.suggest.SuggestIngestionConstraints
import mozilla.appservices.suggest.SuggestStore
import mozilla.appservices.suggest.SuggestStoreBuilder
import mozilla.appservices.suggest.Suggestion
import mozilla.appservices.suggest.SuggestionQuery

import MozillaAppServices

Create a SuggestStore as a singleton. You do this via the SuggestStoreBuilder, which returns a SuggestStore. No I/O or network requests are performed during construction, which makes this safe to do at any point in the application startup:

internal val store: SuggestStore = {
    SuggestStoreBuilder()
        .dataPath(context.getDatabasePath(DATABASE_NAME).absolutePath)
        .remoteSettingsServer(remoteSettingsServer)
        .build()

let store: SuggestStore = {
    let storeBuilder = SuggestStoreBuilder()
    storeBuilder.dataPath(context.getDatabasePath(DATABASE_NAME).absolutePath)
    storeBuilder.remoteSettingsServer(remoteSettingsServer)
    return storeBuilder.build()
}

  • You need to set the dataPath, which is the path (the SQLite location) where you store your suggestions.

  • The remoteSettingsServer is only needed if you want to set the server to anything else but prod. If so, you pass a RemoteSettingsServer object.

Ingesting suggestions

Ingesting suggestions happens in two different ways: On startup, and then, periodically, in the background.

  • SuggestIngestionConstraints is used to control what gets ingested.

  • Use the providers field to limit ingestion by provider type.

  • Use the providerConstraints field to add additional constraints, currently this is only used for exposure suggestions.

On Start Up

Ingest with SuggestIngestionConstraints(emptyOnly=true) shortly after each startup. This ensures we have something in the DB on the first run and also after upgrades where we often will clear the DB to start from scratch.

store.value.ingest(SuggestIngestionConstraints(
    emptyOnly = true,
    providers = listOf(SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.WEATHER)
))

store.value.ingest(SuggestIngestionConstraints(
    emptyOnly: true,
    providers: [.AMP_MOBILE, .WIKIPEDIA, .WEATHER]
))

Periodically

Ingest with SuggestIngestionConstraints(emptyOnly=false) on a regular schedule (like once a day).

store.value.ingest(SuggestIngestionConstraints(emptyOnly = false))

store.value.ingest(SuggestIngestionConstraints(emptyOnly: false))

Querying Suggestions

Call SuggestStore::query to fetch suggestions for the suggest bar. The providers parameter should be the same value that got passed to ingest().

store.value.query(
    SuggestionQuery(
        keyword = text,
        providers = listOf(SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.WEATHER),
        limit = MAX_NUM_OF_FIREFOX_SUGGESTIONS,
    ),
)

store.value.query(
    SuggestionQuery(
        keyword: text,
        providers: [.AMP_MOBILE, .WIKIPEDIA, .WEATHER],
        limit: MAX_NUM_OF_FIREFOX_SUGGESTIONS
    )
)

Interrupt querying

Call SuggestStore::Interrupt with InterruptKind::Read to interrupt any in-progress queries when the user cancels a query and before running the next query.

store.value.interrupt()

store.value.interrupt()

Shutdown the store

On shutdown, call SuggestStore::Interrupt with InterruptKind::ReadWrite to interrupt any in-progress ingestion and queries.

store.value.interrupt()

store.value.interrupt()