fix: remove topic guides from application-services docs
The topic guides moved to m-c: https://firefox-source-docs.mozilla.org/rust-components/index.html
This commit is contained in:
Bastian Gruber
Родитель
2db95b7c38
Коммит
1be85e819a
|
|
@ -39,14 +39,6 @@
|
|||
- [Releases](howtos/releases.md)
|
||||
- [CI Publishing tools and flow](build-and-publish-pipeline.md)
|
||||
- [How to upgrade NSS](howtos/upgrading-nss-guide.md)
|
||||
- [Topic Guides](topic-guides/topic-guides.md)
|
||||
- [Viaduct](topic-guides/viaduct.md)
|
||||
- [Swift]()
|
||||
- [Suggest](topic-guides/swift/suggest.md)
|
||||
- [Relevancy](topic-guides/swift/relevancy.md)
|
||||
- [Kotlin]()
|
||||
- [Suggest](topic-guides/kotlin/suggest.md)
|
||||
- [Relevancy](topic-guides/kotlin/relevancy.md)
|
||||
- [Rustdocs for components](rust-docs/index.html)
|
||||
- [as_ohttp_client](rust-docs/as_ohttp_client/index.html)
|
||||
- [autofill](rust-docs/autofill/index.html)
|
||||
|
|
|
|||
|
|
@ -1,75 +0,0 @@
|
|||
# Relevancy
|
||||
|
||||
The `relevancy` component tracks the user's interests locally, without sharing any data over the network. The component currently supports building an interest vector based on the URLs they visit.
|
||||
|
||||
## Setting up the store
|
||||
|
||||
To use the `RelevancyStore` in Kotlin, you need to import the relevant classes and data types from the `MozillaAppServices` library:
|
||||
|
||||
```kotlin
|
||||
import mozilla.appservices.relevancy.RelevancyStore
|
||||
import mozilla.appservices.relevancy.InterestVector
|
||||
```
|
||||
|
||||
To work with the `RelevancyStore`, you need to create an instance using a database path where the user’s interest data will be stored:
|
||||
|
||||
```kotlin
|
||||
val store = RelevancyStore(dbPath)
|
||||
```
|
||||
|
||||
* `dbPath`: This is the path to the SQLite database where the relevancy data is stored. The initialization is non-blocking, and the database is opened lazily.
|
||||
|
||||
## Ingesting relevancy data
|
||||
|
||||
To build the user's interest vector, call the `ingest` function with a list of URLs ranked by frequency. This method downloads the interest data, classifies the user's top URLs, and builds the interest vector. This process may take time and should only be called from a worker thread.
|
||||
|
||||
### Example usage of `ingest`:
|
||||
|
||||
```kotlin
|
||||
val topUrlsByFrequency = listOf("https://example.com", "https://another-example.com")
|
||||
val interestVector = store.ingest(topUrlsByFrequency)
|
||||
```
|
||||
* `topUrlsByFrequency`: A list of URLs ranked by how often and recently the user has visited them. This data is used to build the user's interest vector.
|
||||
* The `ingest` function returns an `InterestVector`, which contains the user's interest levels for different tracked categories.
|
||||
|
||||
The ingestion process includes:
|
||||
* Downloading the interest data from remote settings (eventually cached/stored in the database).
|
||||
* Matching the user’s top URLs against the interest data.
|
||||
* Storing the interest vector in the database.
|
||||
|
||||
> This method may execute for a long time and should only be called from a worker thread.
|
||||
|
||||
## Getting the user's interest vector
|
||||
|
||||
Once the user's interest vector has been built by ingestion, you can retrieve it using the `userInterestVector` function. This is useful for displaying the vector, for example, in an about page.
|
||||
|
||||
### Example usage of `userInterestVector`:
|
||||
|
||||
```kotlin
|
||||
val interestVector = store.userInterestVector()
|
||||
```
|
||||
* This method returns an `InterestVector`, which is a record with a field that measures the interest for each category we track. The counts are not normalized.
|
||||
|
||||
## Interrupting ongoing operations
|
||||
|
||||
If the application is shutting down or you need to stop ongoing database queries, you can call `interrupt()` to stop any work that the `RelevancyStore` is doing.
|
||||
|
||||
### Example usage of `interrupt`:
|
||||
|
||||
```kotlin
|
||||
store.interrupt()
|
||||
```
|
||||
|
||||
* This interrupts any in-progress work, like ingestion or querying operations.
|
||||
|
||||
## Shutdown
|
||||
|
||||
Before shutting down the application, you should call `close()` to close the database and other open resources.
|
||||
|
||||
### Example usage of `close`:
|
||||
|
||||
```kotlin
|
||||
store.close()
|
||||
```
|
||||
|
||||
* This will close any open resources and interrupt any in-progress queries running on other threads.
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
# Suggest
|
||||
|
||||
The API for the `SuggestStore` can be found in the [MozillaComponents Kotlin documentation](https://mozilla.github.io/application-services/kotlin/kotlin-components-docs/mozilla.appservices.suggest/-suggest-store/index.html).
|
||||
|
||||
> Make sure you initialize [`viaduct`](../viaduct.md) for this component.
|
||||
|
||||
> The `SuggestStore` is a synchronous, which needs to be wrapped in the asynchronous primitive of the target language you are using it in.
|
||||
|
||||
## 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`):
|
||||
|
||||
```kotlin
|
||||
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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```kotlin
|
||||
internal val store: SuggestStore = {
|
||||
SuggestStoreBuilder()
|
||||
.dataPath(context.getDatabasePath(DATABASE_NAME).absolutePath)
|
||||
.remoteSettingsServer(remoteSettingsServer)
|
||||
.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`](https://mozilla.github.io/application-services/kotlin/kotlin-components-docs/mozilla.appservices.suggest/-suggest-ingestion-constraints/index.html?query=data%20class%20SuggestIngestionConstraints(var%20providers:%20List%3CSuggestionProvider%3E?%20=%20null,%20var%20providerConstraints:%20SuggestionProviderConstraints?%20=%20null,%20var%20emptyOnly:%20Boolean%20=%20false) 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.
|
||||
|
||||
```kotlin
|
||||
store.value.ingest(SuggestIngestionConstraints(emptyOnly = true, providers = listOf(SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.WEATHER)))
|
||||
```
|
||||
|
||||
### Periodically
|
||||
|
||||
Ingest with `SuggestIngestionConstraints(emptyOnly=false)` on regular schedule (like once a day).
|
||||
|
||||
Example:
|
||||
|
||||
```kotlin
|
||||
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()`.
|
||||
|
||||
```kotlin
|
||||
store.value.query(
|
||||
SuggestionQuery(
|
||||
keyword = text,
|
||||
providers = listOf(SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.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.
|
||||
|
||||
```kotlin
|
||||
store.value.interrupt()
|
||||
```
|
||||
|
||||
## Shutdown the store
|
||||
|
||||
On shutdown, call `SuggestStore::Interrupt` with `InterruptKind::ReadWrite` to interrupt any in-progress ingestion and queries.
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Relevancy
|
||||
|
||||
The `relevancy` component tracks the user's interests locally, without sharing any data over the network. The component currently supports building an interest vector based on the URLs they visit.
|
||||
|
||||
## Setting up the store
|
||||
|
||||
You need to import the following components to work with the `RelevancyStore` (these come from the generated `relevancy.swift` file, produced by `uniffi`):
|
||||
|
||||
```swift
|
||||
import class MozillaAppServices.RelevancyStore
|
||||
import struct MozillaAppServices.InterestVector
|
||||
```
|
||||
|
||||
On startup of your application, you create a `RelevancyStore`. The store is initialized with a database path where the user’s interest vector will be stored:
|
||||
|
||||
```swift
|
||||
let store = try RelevancyStore(dbPath: pathToDatabase)
|
||||
```
|
||||
|
||||
* `dbPath`: This is the path to the SQLite database where the relevancy data is stored. The initialization is non-blocking, and the database is opened lazily.
|
||||
|
||||
## Ingesting relevancy data
|
||||
|
||||
Ingesting user data into the `RelevancyStore` builds the user's interest vector based on the top URLs they visit (measured by frequency). This should be called soon after startup but does not need to be scheduled periodically.
|
||||
|
||||
### Example usage of `ingest`:
|
||||
|
||||
```swift
|
||||
let topUrlsByFrequency: [String] = ["https://example.com", "https://another-example.com"]
|
||||
try store.ingest(topUrlsByFrequency: topUrlsByFrequency)
|
||||
```
|
||||
* `topUrlsByFrequency`: A list of URLs ranked by how often and recently the user has visited them. This data is used to build the user's interest vector.
|
||||
* The `ingest` function returns an `InterestVector`, which contains the user's interest levels for different tracked categories.
|
||||
|
||||
The ingestion process includes:
|
||||
* Downloading the interest data from remote settings (eventually cached/stored in the database).
|
||||
* Matching the user’s top URLs against the interest data.
|
||||
* Storing the interest vector in the database.
|
||||
|
||||
> This method may execute for a long time and should only be called from a worker thread.
|
||||
|
||||
## Getting the user's interest vector
|
||||
|
||||
After ingestion, you can retrieve the user's interest vector directly. This is useful for displaying the vector on an `about:` page or using it in other features.
|
||||
|
||||
### Example usage of `userInterestVector`:
|
||||
|
||||
```swift
|
||||
let interestVector = try store.userInterestVector()
|
||||
```
|
||||
* This method returns an `InterestVector`, which is a record with a field that measures the interest for each category we track. The counts are not normalized.
|
||||
|
||||
## Interrupting ongoing operations
|
||||
|
||||
If the application is shutting down or you need to stop ongoing database queries, you can call `interrupt()` to stop any work that the `RelevancyStore` is doing.
|
||||
|
||||
### Example usage of `interrupt`:
|
||||
|
||||
```swift
|
||||
store.interrupt()
|
||||
```
|
||||
|
||||
* This interrupts any in-progress work, like ingestion or querying operations.
|
||||
|
||||
## Shutdown
|
||||
|
||||
Before shutting down the application, you should call `close()` to close the database and other open resources.
|
||||
|
||||
### Example usage of `close`:
|
||||
|
||||
```swift
|
||||
store.close()
|
||||
```
|
||||
|
||||
* This will close any open resources and interrupt any in-progress queries running on other threads.
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
# Suggest
|
||||
|
||||
The API for the `SuggestStore` can be found in the [MozillaComponents Swift documentation](https://mozilla.github.io/application-services/swift/Classes/SuggestStore.html).
|
||||
|
||||
> Make sure you initialize [`viaduct`](../viaduct.md) for this component.
|
||||
|
||||
> The `SuggestStore` is a synchronous, which needs to be wrapped in the asynchronous primitive of the target language you are using it in.
|
||||
|
||||
## 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.swift` file, produced by `uniffi`):
|
||||
|
||||
```swift
|
||||
import class MozillaAppServices.SuggestStore
|
||||
import class MozillaAppServices.SuggestStoreBuilder
|
||||
import class MozillaAppServices.Viaduct
|
||||
import enum MozillaAppServices.SuggestionProvider
|
||||
import enum MozillaAppServices.RemoteSettingsServer
|
||||
import struct MozillaAppServices.SuggestIngestionConstraints
|
||||
import struct MozillaAppServices.SuggestionQuery
|
||||
```
|
||||
|
||||
On start up of your application, you create a `SuggestStore` (as a singleton). You do this via the `SuggestStoreBuilder`, which returns a `SuggestStore`:
|
||||
|
||||
```swift
|
||||
let store: SuggestStore
|
||||
|
||||
var builder = SuggestStoreBuilder()
|
||||
.dataPath(path: dataPath)
|
||||
|
||||
if let remoteSettingsServer {
|
||||
builder = builder.remoteSettingsServer(server: remoteSettingsServer)
|
||||
}
|
||||
|
||||
store = try builder.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`](https://mozilla.github.io/application-services/kotlin/kotlin-components-docs/mozilla.appservices.suggest/-suggest-ingestion-constraints/index.html?query=data%20class%20SuggestIngestionConstraints(var%20providers:%20List%3CSuggestionProvider%3E?%20=%20null,%20var%20providerConstraints:%20SuggestionProviderConstraints?%20=%20null,%20var%20emptyOnly:%20Boolean%20=%20false)) 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::empty_only=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.
|
||||
|
||||
### Periodically
|
||||
|
||||
Ingest with `SuggestIngestionConstraints::empty_only=false` on regular schedule (like once a day).
|
||||
|
||||
Example:
|
||||
|
||||
```swift
|
||||
try self.store.ingest(constraints: SuggestIngestionConstraints(
|
||||
emptyOnly: false,
|
||||
providers: [SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.WEATHER]
|
||||
))
|
||||
```
|
||||
|
||||
## 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()`.
|
||||
|
||||
```swift
|
||||
try self.store.query(query: SuggestionQuery(
|
||||
keyword: keyword,
|
||||
providers: [SuggestionProvider.AMP_MOBILE, SuggestionProvider.WIKIPEDIA, SuggestionProvider.WEATHER],
|
||||
limit: limit
|
||||
))
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```swift
|
||||
store.interrupt(kind: .readWrite)
|
||||
```
|
||||
|
||||
## Shutdown the store
|
||||
|
||||
On shutdown, call `SuggestStore::Interrupt` with `InterruptKind::ReadWrite` to interrupt any in-progress ingestion and queries.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
# Topic guides for Rust components
|
||||
|
||||
The topic guids are meant to make it easier to implement existing components in your language of choice.
|
||||
|
||||
## Content
|
||||
|
||||
- Suggest: [Swift](swift/suggest.md) | [Kotlin](kotlin/suggest.md)
|
||||
- Relevancy: [Swift](swift/relevancy.md) | [Kotlin](kotlin/relevancy.md)
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
# Viaduct
|
||||
|
||||
[`Viaduct`](https://github.com/mo zilla/application-services/blob/main/components/viaduct/README.md) initialization is required for all platforms and for multiple components.
|
||||
|
||||
There are 3 different options to use `viaduct`:
|
||||
|
||||
* Any `libxul` based can ignore initialization, since it's handled by `libxul`.
|
||||
* Using the reqwest backend, which uses the `reqwest` library and a `reqwest`-managed thread.
|
||||
* Implementing the C FFI like `libxul` does (https://searchfox.org/mozilla-central/source/toolkit/components/viaduct).
|
||||
Загрузка…
Ссылка в новой задаче