Skip to content

Commit 7bf6b96

Browse files
AlmajuAlmaju
authored
feat(ads-client): allow to request multiple ads (#7048)
* feat(ads-client): allow to request multiple ads * refactor(ads-client): rename multiple_ads into ads_multiset
1 parent b3d8cc2 commit 7bf6b96

File tree

4 files changed

+299
-190
lines changed

4 files changed

+299
-190
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
- Added request caching mechanism using SQLite with configurable TTL and max size.
3939
- Added configuration options for the cache.
4040
- Deserialize callbacks with `url::Url`
41+
- Support for multiple ads request (with count)
4142

4243
### Relay
4344
- **⚠️ Breaking Change:** The error handling for the Relay component has been refactored for stronger forward compatibility and more transparent error reporting in Swift and Kotlin via UniFFI.

‎components/ads-client/docs/usage.md‎

Lines changed: 66 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
21
# Mozilla Ads Client (MAC) — UniFFI API Reference
32

43
## Overview
4+
55
This document lists the Rust types and functions exposed via UniFFI by the `ads_client` component.
66
It only includes items that are part of the UniFFI surface. This document is aimed at users of the ads-client who want to know what is available to them.
77

@@ -30,20 +30,22 @@ If a cache configuration is provided, the client will initialize an on-disk HTTP
3030

3131
#### Methods
3232

33-
| Method | Return Type | Description |
34-
|--------|-------------|-------------|
35-
| `request_ads(&self, moz_ad_requests: Vec<MozAdsPlacementRequest>, options: Option<MozAdsRequestOptions>)` | `AdsClientApiResult<HashMap<String, MozAdsPlacement>>` | Requests ads for the given placement configurations. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placement_id`. |
36-
| `record_impression(&self, placement: MozAdsPlacement)` | `AdsClientApiResult<()>` | Records an impression for the given placement (fires the ad’s impression callback). |
37-
| `record_click(&self, placement: MozAdsPlacement)` | `AdsClientApiResult<()>` | Records a click for the given placement (fires the ad’s click callback). |
38-
| `report_ad(&self, placement: MozAdsPlacement)` | `AdsClientApiResult<()>` | Reports the given placement (fires the ad’s report callback). |
39-
| `cycle_context_id(&self)` | `AdsClientApiResult<String>` | Rotates the client’s context ID and returns the **previous** ID. |
40-
| `clear_cache(&self)` | `AdsClientApiResult<()>` | Clears the client’s HTTP cache. Returns an error if clearing fails. |
33+
| Method | Return Type | Description |
34+
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
35+
| `clear_cache(&self)` | `AdsClientApiResult<()>` | Clears the client’s HTTP cache. Returns an error if clearing fails. |
36+
| `cycle_context_id(&self)` | `AdsClientApiResult<String>` | Rotates the client’s context ID and returns the **previous** ID. |
37+
| `record_click(&self, placement: MozAd)` | `AdsClientApiResult<()>` | Records a click for the given placement (fires the ad’s click callback). |
38+
| `record_impression(&self, placement: MozAd)` | `AdsClientApiResult<()>` | Records an impression for the given placement (fires the ad’s impression callback). |
39+
| `report_ad(&self, placement: MozAd)` | `AdsClientApiResult<()>` | Reports the given placement (fires the ad’s report callback). |
40+
| `request_ads(&self, moz_ad_requests: Vec<MozAdsPlacementRequest>, options: Option<MozAdsRequestOptions>)` | `AdsClientApiResult<HashMap<String, MozAd>>` | Requests one ad per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placement_id`. |
41+
| `request_ads_multiset(&self, moz_ad_requests: Vec<MozAdsPlacementRequestWithCount>, options: Option<MozAdsRequestOptions>)` | `AdsClientApiResult<HashMap<String, Vec<MozAd>>>` | Requests up to `count` ads per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placement_id`. |
4142

4243
> **Notes**
44+
>
4345
> - We recommend that this client be initialized as a singleton or something similar so that multiple instances of the client do not exist at once.
44-
> - Responses from `request_ads` will omit placements with no fill. Those keys won’t appear in the returned map.
46+
> - Responses omit placements with no fill. Empty placements do not appear in the returned maps for either `request_ads` or `request_ads_multiset`.
4547
> - The HTTP cache is internally managed. Configuration can be set with `MozAdsClientConfig`. Per-request cache settings can be set with `MozAdsRequestOptions`.
46-
> - If cache_config is None, caching is disabled entirely.
48+
> - If `cache_config` is `None`, caching is disabled entirely.
4749

4850
---
4951

@@ -58,15 +60,15 @@ pub struct MozAdsClientConfig {
5860
}
5961
```
6062

61-
| Field | Type | Description |
62-
|------|------|-------------|
63-
| `enviornment` | `Enviornment` | Selects which MARS environment to connect to. Unless in a dev build, this value can only ever be Prod. |
64-
| `cache_config` | `Option<MozAdsCacheConfig>` | Optional configuration for the internal cache. |
65-
63+
| Field | Type | Description |
64+
| -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
65+
| `environment` | `Environment` | Selects which MARS environment to connect to. Unless in a dev build, this value can only ever be Prod. |
66+
| `cache_config` | `Option<MozAdsCacheConfig>` | Optional configuration for the internal cache. |
6667

6768
---
6869

6970
## `MozAdsCacheConfig`
71+
7072
Describes the behavior and location of the on-disk HTTP cache.
7173

7274
```rust
@@ -77,20 +79,17 @@ pub struct MozAdsCacheConfig {
7779
}
7880
```
7981

80-
8182
| Field | Type | Description |
8283
| --------------------------- | ------------- | ------------------------------------------------------------------------------------ |
8384
| `db_path` | `String` | Path to the SQLite database file used for cache storage. Required to enable caching. |
84-
| `default_cache_ttl_seconds` | `Option<u64>` | Default TTL for cached entries. If omitted, defaults to 300 seconds (5 minutes). |
85-
| `max_size_mib` | `Option<u64>` | Maximum cache size. If omitted, defaults to 10 MiB. |
86-
85+
| `default_cache_ttl_seconds` | `Option<u64>` | Default TTL for cached entries. If omitted, defaults to 300 seconds (5 minutes). |
86+
| `max_size_mib` | `Option<u64>` | Maximum cache size. If omitted, defaults to 10 MiB. |
8787

8888
**Defaults**
8989

9090
- default_cache_ttl_seconds: 300 seconds (5 min)
9191
- max_size_mib: 10 MiB
9292

93-
9493
---
9594

9695
## `MozAdsPlacementRequest`
@@ -104,16 +103,31 @@ pub struct MozAdsPlacementRequest {
104103
}
105104
```
106105

107-
| Field | Type | Description |
108-
|------|------|-------------|
109-
| `placement_id` | `String` | Unique identifier for the ad placement. Must be unique within one `request_ads` call. |
110-
| `iab_content` | `Option<IABContent>` | Optional IAB content classification for targeting. |
106+
| Field | Type | Description |
107+
| -------------- | -------------------- | ------------------------------------------------------------------------------------- |
108+
| `placement_id` | `String` | Unique identifier for the ad placement. Must be unique within one `request_ads` call. |
109+
| `iab_content` | `Option<IABContent>` | Optional IAB content classification for targeting. |
111110

112111
**Validation Rules:**
112+
113113
- `placement_id` values must be unique per request.
114114

115115
---
116116

117+
## `MozAdsPlacementRequestWithCount`
118+
119+
Describes a single ad placement and the maximum number of ads to request for that placement. A vector of these is used by the `request_ads_multiset` method on the client.
120+
121+
```rust
122+
pub struct MozAdsPlacementRequestWithCount {
123+
pub count: u32,
124+
pub placement_id: String,
125+
pub iab_content: Option<IABContent>,
126+
}
127+
```
128+
129+
---
130+
117131
## `MozAdsRequestOptions`
118132

119133
Options passed when making a single ad request.
@@ -124,12 +138,10 @@ pub struct MozAdsRequestOptions {
124138
}
125139
```
126140

127-
128-
| Field | Type | Description |
129-
| -------------- | ---------------------------- | ------------------------------------------------------------------ |
141+
| Field | Type | Description |
142+
| -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
130143
| `cache_policy` | `Option<RequestCachePolicy>` | Per-request caching policy. If `None`, uses the client’s default TTL with a `CacheFirst` mode. |
131144

132-
133145
---
134146

135147
## `RequestCachePolicy`
@@ -145,10 +157,9 @@ pub struct RequestCachePolicy {
145157

146158
| Field | Type | Description |
147159
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
148-
| `mode` | `CacheMode` | Strategy for combining cache and network. Can be `CacheFirst` or `NetworkFirst`. |
160+
| `mode` | `CacheMode` | Strategy for combining cache and network. Can be `CacheFirst` or `NetworkFirst`. |
149161
| `ttl_seconds` | `Option<u64>` | Optional per-request TTL override in seconds. `None` uses the client default. `Some(0)` disables caching for this request. |
150162

151-
152163
---
153164

154165
## `CacheMode`
@@ -162,32 +173,11 @@ pub enum CacheMode {
162173
}
163174
```
164175

165-
166-
| Variant | Behavior |
167-
| -------------- | ------------------------------------------------------------------------------------------------------ |
176+
| Variant | Behavior |
177+
| -------------- | -------------------------------------------------------------------------------------------------- |
168178
| `CacheFirst` | Check cache first, return cached response if found, otherwise make a network request and store it. |
169179
| `NetworkFirst` | Always fetch from network, then cache the result. |
170180

171-
172-
---
173-
174-
## `MozAdsPlacement`
175-
176-
Represents a served ad placement and its content.
177-
178-
```rust
179-
pub struct MozAdsPlacement {
180-
pub placement_requests: MozAdsPlacementRequest,
181-
pub content: MozAd,
182-
}
183-
```
184-
185-
| Field | Type | Description |
186-
|------|------|-------------|
187-
| `placement_requests` | `MozAdsPlacementRequest` | The configuration used to request this ad. |
188-
| `content` | `MozAd` | The ad creative and its callbacks. |
189-
190-
191181
---
192182

193183
## `MozAd`
@@ -205,34 +195,32 @@ pub struct MozAd {
205195
}
206196
```
207197

208-
| Field | Type | Description |
209-
|------|------|-------------|
210-
| `url` | `String` | Destination URL. |
211-
| `image_url` | `String` | Creative asset URL. |
212-
| `format` | `String` | Ad format e.g., `"skyscraper"`. |
213-
| `block_key` | `String` | The block key generated for the advertiser. |
214-
| `alt_text` | `Option<String>` | Alt text if available. |
215-
| `callbacks` | `AdCallbacks` | Lifecycle callback endpoints. |
216-
198+
| Field | Type | Description |
199+
| ----------- | ---------------- | ------------------------------------------- |
200+
| `url` | `String` | Destination URL. |
201+
| `image_url` | `String` | Creative asset URL. |
202+
| `format` | `String` | Ad format e.g., `"skyscraper"`. |
203+
| `block_key` | `String` | The block key generated for the advertiser. |
204+
| `alt_text` | `Option<String>` | Alt text if available. |
205+
| `callbacks` | `AdCallbacks` | Lifecycle callback endpoints. |
217206

218207
---
219208

220209
## `AdCallbacks`
221210

222211
```rust
223212
pub struct AdCallbacks {
224-
pub click: Option<String>,
225-
pub impression: Option<String>,
213+
pub click: String,
214+
pub impression: String,
226215
pub report: Option<String>,
227216
}
228217
```
229218

230-
| Field | Type | Description |
231-
|------|------|-------------|
232-
| `click` | `Option<String>` | Click callback URL. |
233-
| `impression` | `Option<String>` | Impression callback URL. |
234-
| `report` | `Option<String>` | Report callback URL. |
235-
219+
| Field | Type | Description |
220+
| ------------ | ---------------- | ------------------------ |
221+
| `click` | `String` | Click callback URL. |
222+
| `impression` | `String` | Impression callback URL. |
223+
| `report` | `Option<String>` | Report callback URL. |
236224

237225
---
238226

@@ -247,16 +235,16 @@ pub struct AdContentCategory {
247235
}
248236
```
249237

250-
| Field | Type | Description |
251-
|------|------|-------------|
252-
| `taxonomy` | `IABContentTaxonomy` | IAB taxonomy version. |
253-
| `category_ids` | `Vec<String>` | One or more IAB category identifiers. |
238+
| Field | Type | Description |
239+
| -------------- | -------------------- | ------------------------------------- |
240+
| `taxonomy` | `IABContentTaxonomy` | IAB taxonomy version. |
241+
| `category_ids` | `Vec<String>` | One or more IAB category identifiers. |
254242

255243
---
256244

257245
## `IABContentTaxonomy`
258246

259-
The [IAB Content Taxonomy](https://www.iab.com/guidelines/content-taxonomy/) version to be used in the request. e.g `IAB-1.0`
247+
The [IAB Content Taxonomy](https://www.iab.com/guidelines/content-taxonomy/) version to be used in the request. e.g `IAB-1.0`
260248

261249
```rust
262250
pub enum IABContentTaxonomy {
@@ -267,6 +255,7 @@ pub enum IABContentTaxonomy {
267255
IAB3_0,
268256
}
269257
```
258+
270259
> Note: The generated native bindings for the values may look different depending on the language (snake-case, camel case, etc.) as a result of UniFFI's formatting.
271260
272261
---
@@ -331,7 +320,6 @@ let options = MozAdsRequestOptions(
331320
let placements = client.requestAds(configs, options: options)
332321
```
333322

334-
335323
### Cache Invalidation
336324

337325
**TTL-based expiry (automatic):**
@@ -342,7 +330,7 @@ At the start of each send, the cache computes a cutoff from chrono::Utc::now() -
342330
After storing a cacheable miss, the cache enforces max_size by deleting the oldest rows until the total stored size is ≤ the maximum allowed size of the cache. Due to the small size of items in the cache and the relatively short TTL, this behavior should be rare.
343331

344332
**Manual clearing (explicit):**
345-
The cache can be manually cleared by the client using the exposed `client.clear_cache()` method. This clears *all* objects in the cache.
333+
The cache can be manually cleared by the client using the exposed `client.clear_cache()` method. This clears _all_ objects in the cache.
346334

347335
---
348336

0 commit comments

Comments
 (0)