Skip to content

feat(ads-client): add OHTTP support (AC-94) #7315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Almaju wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(ads-client): add OHTTP support (AC-94) #7315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5bbdfb6
refactor(ads-client): restructure modules, strategy pattern for cache…
Almaju Apr 13, 2026
5e46fdd
feat(ads-client): add per-request OHTTP support
Almaju Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/workflows/ads-client-tests.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,21 @@ jobs:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source $HOME/.cargo/env
rustup toolchain install
- name: Build NSS
env:
NSS_DIR: ${{ github.workspace }}/libs/desktop/linux-x86-64/nss
NSS_STATIC: 1
run: |
sudo apt-get update
sudo apt-get install -y ninja-build zlib1g-dev tclsh python3
python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip setuptools six
git clone https://chromium.googlesource.com/external/gyp.git tools/gyp
cd tools/gyp && pip install . && cd ../..
./libs/verify-desktop-environment.sh
- name: Run ads-client integration tests against MARS staging
env:
NSS_DIR: ${{ github.workspace }}/libs/desktop/linux-x86-64/nss
NSS_STATIC: 1
run: cargo test -p ads-client-integration-tests -- --ignored
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@

## ✨ What's New ✨

### Ads Client
- Add per-request OHTTP support via the `ohttp` flag on `MozAdsRequestOptions` and `MozAdsCallbackOptions`. When enabled, individual MARS requests are routed through viaduct's OHTTP layer with automatic preflight for geo/user-agent override headers.

### Logins
- New `allow_empty_passwords` feature flag to allow storing logins with empty passwords. This feature is intended to be enabled on desktop during the migration.
- Add `ignore_form_action_origin_validation_errors` feature flag that allows logins with non-URL `form_action_origin` values (e.g. "email", "UserCode") to be imported without error. URL normalization for valid URLs is still applied.
Expand Down
2 changes: 1 addition & 1 deletion components/ads-client/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ once_cell = "1.5"
uniffi = { version = "0.31" }
url = { version = "2", features = ["serde"] }
uuid = { version = "1.3", features = ["v4"] }
viaduct = { path = "../viaduct" }
viaduct = { path = "../viaduct", features = ["ohttp"] }
sql-support = { path = "../support/sql" }

[dev-dependencies]
Expand Down
42 changes: 39 additions & 3 deletions components/ads-client/docs/usage-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@ const client = MozAdsClientBuilder()
| Method | Return Type | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clearCache()` | `void` | Clears the client's HTTP cache. Throws on failure. |
| `recordClick(clickUrl)` | `void` | Records a click using the provided callback URL (typically from `ad.callbacks.click`). |
| `recordImpression(impressionUrl)` | `void` | Records an impression using the provided callback URL (typically from `ad.callbacks.impression`). |
| `reportAd(reportUrl)` | `void` | Reports an ad using the provided callback URL (typically from `ad.callbacks.report`). |
| `recordClick(clickUrl, options?)` | `void` | Records a click using the provided callback URL (typically from `ad.callbacks.click`). Optional `MozAdsCallbackOptions` can enable OHTTP. |
| `recordImpression(impressionUrl, options?)` | `void` | Records an impression using the provided callback URL (typically from `ad.callbacks.impression`). Optional `MozAdsCallbackOptions` can enable OHTTP. |
| `reportAd(reportUrl, reason, options?)` | `void` | Reports an ad using the provided callback URL (typically from `ad.callbacks.report`). Optional `MozAdsCallbackOptions` can enable OHTTP. |
| `requestImageAds(mozAdRequests, options?)` | `Object.<string, MozAdsImage>` | Requests one image ad per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns an object keyed by `placementId`. |
| `requestSpocAds(mozAdRequests, options?)` | `Object.<string, Array.<MozAdsSpoc>>` | Requests spoc ads per placement. Each placement request specifies its own count. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns an object keyed by `placementId`. |
| `requestTileAds(mozAdRequests, options?)` | `Object.<string, MozAdsTile>` | Requests one tile ad per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns an object keyed by `placementId`. |
Expand Down Expand Up @@ -246,12 +246,48 @@ Options passed when making a single ad request.
/**
* @typedef {Object} MozAdsRequestOptions
* @property {MozAdsRequestCachePolicy|null} cachePolicy - Per-request caching policy.
* @property {boolean} ohttp - Whether to route this request through OHTTP (default: false).
*/
```

| Field | Type | Description |
| -------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `cachePolicy` | `MozAdsRequestCachePolicy \| null` | Per-request caching policy. If `null`, uses the client's default TTL with a `CacheFirst` mode. |
| `ohttp` | `boolean` | Whether to route this request through OHTTP. Defaults to `false`. |

---

## `MozAdsCallbackOptions`

Options passed when making callback requests (click, impression, report).

```javascript
/**
* @typedef {Object} MozAdsCallbackOptions
* @property {boolean} ohttp - Whether to route this callback through OHTTP (default: false).
*/
```

| Field | Type | Description |
| ------- | --------- | ------------------------------------------------------------------ |
| `ohttp` | `boolean` | Whether to route this callback through OHTTP. Defaults to `false`. |

#### OHTTP Usage Example

```javascript
// Request ads over OHTTP
const ads = client.requestTileAds(placements, {
ohttp: true
});

// Record a click over OHTTP
client.recordClick(ad.callbacks.click, { ohttp: true });

// Record an impression over OHTTP
client.recordImpression(ad.callbacks.impression, { ohttp: true });
```

> **Note:** OHTTP must be configured at the viaduct level before use. When `ohttp` is `true`, the client automatically performs a preflight request to obtain geo-location and user-agent headers, which are injected into the MARS request.

---

Expand Down
41 changes: 37 additions & 4 deletions components/ads-client/docs/usage-kotlin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ val client = MozAdsClientBuilder()
| Method | Return Type | Description |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clearCache()` | `Unit` | Clears the client's HTTP cache. Throws on failure. |
| `recordClick(clickUrl: String)` | `Unit` | Records a click using the provided callback URL (typically from `ad.callbacks.click`). |
| `recordImpression(impressionUrl: String)` | `Unit` | Records an impression using the provided callback URL (typically from `ad.callbacks.impression`). |
| `reportAd(reportUrl: String)` | `Unit` | Reports an ad using the provided callback URL (typically from `ad.callbacks.report`). |
| `recordClick(clickUrl: String, options: MozAdsCallbackOptions?)` | `Unit` | Records a click using the provided callback URL (typically from `ad.callbacks.click`). |
| `recordImpression(impressionUrl: String, options: MozAdsCallbackOptions?)` | `Unit` | Records an impression using the provided callback URL (typically from `ad.callbacks.impression`). |
| `reportAd(reportUrl: String, reason: MozAdsReportReason, options: MozAdsCallbackOptions?)` | `Unit` | Reports an ad using the provided callback URL (typically from `ad.callbacks.report`). |
| `requestImageAds(mozAdRequests: List<MozAdsPlacementRequest>, options: MozAdsRequestOptions?)` | `Map<String, MozAdsImage>` | Requests one image ad per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placementId`. |
| `requestSpocAds(mozAdRequests: List<MozAdsPlacementRequestWithCount>, options: MozAdsRequestOptions?)` | `Map<String, List<MozAdsSpoc>>` | Requests spoc ads per placement. Each placement request specifies its own count. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placementId`. |
| `requestTileAds(mozAdRequests: List<MozAdsPlacementRequest>, options: MozAdsRequestOptions?)` | `Map<String, MozAdsTile>` | Requests one tile ad per placement. Optional `MozAdsRequestOptions` can adjust caching behavior. Returns a map keyed by `placementId`. |
Expand Down Expand Up @@ -219,13 +219,46 @@ Options passed when making a single ad request.

```kotlin
data class MozAdsRequestOptions(
val cachePolicy: MozAdsRequestCachePolicy?
val cachePolicy: MozAdsRequestCachePolicy?,
val ohttp: Boolean = false
)
```

| Field | Type | Description |
| -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `cachePolicy` | `MozAdsRequestCachePolicy?` | Per-request caching policy. If `null`, uses the client's default TTL with a `CacheFirst` mode. |
| `ohttp` | `Boolean` | Whether to route this request through OHTTP. Defaults to `false`. |

---

## `MozAdsCallbackOptions`

Options passed when making callback requests (click, impression, report).

```kotlin
data class MozAdsCallbackOptions(
val ohttp: Boolean = false
)
```

| Field | Type | Description |
| ------- | --------- | ------------------------------------------------------------------ |
| `ohttp` | `Boolean` | Whether to route this callback through OHTTP. Defaults to `false`. |

#### OHTTP Usage Example

```kotlin
// Request ads over OHTTP
val ads = client.requestTileAds(placements, MozAdsRequestOptions(ohttp = true))

// Record a click over OHTTP
client.recordClick(ad.callbacks.click, MozAdsCallbackOptions(ohttp = true))

// Record an impression over OHTTP
client.recordImpression(ad.callbacks.impression, MozAdsCallbackOptions(ohttp = true))
```

> **Note:** OHTTP must be configured at the viaduct level before use. When `ohttp` is `true`, the client automatically performs a preflight request to obtain geo-location and user-agent headers, which are injected into the MARS request.

---

Expand Down
Loading
Loading