feat(ads-client): add reason parameter to report_ad per MARS /v1/t spec

The /v1/t tracking endpoint requires a `reason` query parameter for
report interactions. Add MozAdsReportReason enum with Inappropriate,
NotInterested, and SeenTooManyTimes variants and thread it through
the full stack, appending it to the callback URL before the request.

Author: Almaju

CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### Ads Client
 - Added `rotation_days` parameter to `MozAdsClientBuilder` to allow embedders to configure the context ID rotation period. ([#7262](https://github.com/mozilla/application-services/pull/7262))
+- Added `reason` parameter to `report_ad` to comply with the MARS `/v1/t` tracking endpoint spec. Accepted values: `inappropriate`, `not_interested`, `seen_too_many_times`.
 
 ### Logins
 - **BREAKING**: Removed `time_of_last_breach` field from `LoginMeta` and `Login`. This can be derived from Remote Settings during runtime instead.

components/ads-client/src/client.rs

@@ -9,6 +9,23 @@ use std::time::Duration;
 use crate::client::ad_response::{AdImage, AdResponse, AdResponseValue, AdSpoc, AdTile};
 use crate::client::config::{AdsClientConfig, Environment};
 use crate::error::{RecordClickError, RecordImpressionError, ReportAdError, RequestAdsError};
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum ReportReason {
+    Inappropriate,
+    NotInterested,
+    SeenTooManyTimes,
+}
+
+impl ReportReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            ReportReason::Inappropriate => "inappropriate",
+            ReportReason::NotInterested => "not_interested",
+            ReportReason::SeenTooManyTimes => "seen_too_many_times",
+        }
+    }
+}
 use crate::http_cache::{HttpCache, RequestCachePolicy};
 use crate::mars::MARSClient;
 use crate::telemetry::Telemetry;
@@ -199,9 +216,9 @@ where
             })
     }
 
-    pub fn report_ad(&self, report_url: Url) -> Result<(), ReportAdError> {
+    pub fn report_ad(&self, report_url: Url, reason: ReportReason) -> Result<(), ReportAdError> {
         self.client
-            .report_ad(report_url)
+            .report_ad(report_url, reason)
             .inspect_err(|e| {
                 self.telemetry.record(e);
             })

components/ads-client/src/ffi.rs

@@ -11,6 +11,7 @@ use crate::client::ad_request::{AdContentCategory, AdPlacementRequest, IABConten
 use crate::client::ad_response::{
     AdCallbacks, AdImage, AdSpoc, AdTile, SpocFrequencyCaps, SpocRanking,
 };
+use crate::client::ReportReason;
 use crate::client::config::{AdsCacheConfig, AdsClientConfig, Environment};
 use crate::client::AdsClient;
 use crate::error::ComponentError;
@@ -191,6 +192,23 @@ pub struct MozAdsRequestCachePolicy {
     pub ttl_seconds: Option<u64>,
 }
 
+#[derive(Clone, Copy, Debug, uniffi::Enum)]
+pub enum MozAdsReportReason {
+    Inappropriate,
+    NotInterested,
+    SeenTooManyTimes,
+}
+
+impl From<MozAdsReportReason> for ReportReason {
+    fn from(reason: MozAdsReportReason) -> Self {
+        match reason {
+            MozAdsReportReason::Inappropriate => ReportReason::Inappropriate,
+            MozAdsReportReason::NotInterested => ReportReason::NotInterested,
+            MozAdsReportReason::SeenTooManyTimes => ReportReason::SeenTooManyTimes,
+        }
+    }
+}
+
 #[derive(Clone, Copy, Debug, Default, uniffi::Enum)]
 pub enum MozAdsCacheMode {
     #[default]

components/ads-client/src/lib.rs

@@ -111,11 +111,17 @@ impl MozAdsClient {
     }
 
     #[handle_error(ComponentError)]
-    pub fn report_ad(&self, report_url: String) -> AdsClientApiResult<()> {
+    pub fn report_ad(
+        &self,
+        report_url: String,
+        reason: MozAdsReportReason,
+    ) -> AdsClientApiResult<()> {
         let url = AdsClientUrl::parse(&report_url)
             .map_err(|e| ComponentError::ReportAd(CallbackRequestError::InvalidUrl(e).into()))?;
         let inner = self.inner.lock();
-        inner.report_ad(url).map_err(ComponentError::ReportAd)
+        inner
+            .report_ad(url, reason.into())
+            .map_err(ComponentError::ReportAd)
     }
 
     pub fn clear_cache(&self) -> AdsClientApiResult<()> {

components/ads-client/src/mars.rs

@@ -7,6 +7,8 @@ use crate::{
     client::{
         ad_request::AdRequest,
         ad_response::{AdResponse, AdResponseValue},
+        config::Environment,
+        ReportReason,
     },
     error::{
         check_http_status_for_error, CallbackRequestError, FetchAdsError, RecordClickError,
@@ -88,7 +90,10 @@ where
         Ok(())
     }
 
-    pub fn report_ad(&self, callback: Url) -> Result<(), ReportAdError> {
+    pub fn report_ad(&self, mut callback: Url, reason: ReportReason) -> Result<(), ReportAdError> {
+        callback
+            .query_pairs_mut()
+            .append_pair("reason", reason.as_str());
         Ok(self.make_callback_request(callback)?)
     }
 
@@ -140,6 +145,10 @@ mod tests {
     fn test_report_ad_with_valid_url_should_succeed() {
         viaduct_dev::init_backend_dev();
         let _m = mock("GET", "/report_ad_callback_url")
+            .match_query(mockito::Matcher::UrlEncoded(
+                "reason".into(),
+                "not_interested".into(),
+            ))
             .with_status(200)
             .create();
 
@@ -149,7 +158,7 @@ mod tests {
             &mockito::server_url()
         ))
         .unwrap();
-        let result = client.report_ad(url);
+        let result = client.report_ad(url, ReportReason::NotInterested);
         assert!(result.is_ok());
     }