Unhide frequency cap filtering API classes
Test: atest CtsAdServices*
Bug: 221876775
Change-Id: I779425dee74c3ab81c6c602bdaae2c4704bce7a4
diff --git a/adservices/framework/api/current.txt b/adservices/framework/api/current.txt
index 8f52523..3bdbe24 100644
--- a/adservices/framework/api/current.txt
+++ b/adservices/framework/api/current.txt
@@ -55,6 +55,7 @@
method @NonNull public android.adservices.adselection.TestAdSelectionManager getTestAdSelectionManager();
method @RequiresPermission(android.adservices.common.AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE) public void reportImpression(@NonNull android.adservices.adselection.ReportImpressionRequest, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>);
method @RequiresPermission(android.adservices.common.AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE) public void selectAds(@NonNull android.adservices.adselection.AdSelectionConfig, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>);
+ method @RequiresPermission(android.adservices.common.AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE) public void updateAdCounterHistogram(@NonNull android.adservices.adselection.UpdateAdCounterHistogramRequest, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>);
}
public class AdSelectionOutcome {
@@ -93,6 +94,20 @@
method @RequiresPermission(android.adservices.common.AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE) public void resetAllAdSelectionConfigRemoteOverrides(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>);
}
+ public class UpdateAdCounterHistogramRequest {
+ method public int getAdEventType();
+ method public long getAdSelectionId();
+ method @NonNull public android.adservices.common.AdTechIdentifier getCallerAdTech();
+ }
+
+ public static final class UpdateAdCounterHistogramRequest.Builder {
+ ctor public UpdateAdCounterHistogramRequest.Builder(long, int, @NonNull android.adservices.common.AdTechIdentifier);
+ method @NonNull public android.adservices.adselection.UpdateAdCounterHistogramRequest build();
+ method @NonNull public android.adservices.adselection.UpdateAdCounterHistogramRequest.Builder setAdEventType(int);
+ method @NonNull public android.adservices.adselection.UpdateAdCounterHistogramRequest.Builder setAdSelectionId(long);
+ method @NonNull public android.adservices.adselection.UpdateAdCounterHistogramRequest.Builder setCallerAdTech(@NonNull android.adservices.common.AdTechIdentifier);
+ }
+
}
package android.adservices.appsetid {
@@ -116,6 +131,8 @@
public final class AdData implements android.os.Parcelable {
method public int describeContents();
+ method @NonNull public java.util.Set<java.lang.Integer> getAdCounterKeys();
+ method @Nullable public android.adservices.common.AdFilters getAdFilters();
method @NonNull public String getMetadata();
method @NonNull public android.net.Uri getRenderUri();
method public void writeToParcel(@NonNull android.os.Parcel, int);
@@ -125,10 +142,25 @@
public static final class AdData.Builder {
ctor public AdData.Builder();
method @NonNull public android.adservices.common.AdData build();
+ method @NonNull public android.adservices.common.AdData.Builder setAdCounterKeys(@NonNull java.util.Set<java.lang.Integer>);
+ method @NonNull public android.adservices.common.AdData.Builder setAdFilters(@Nullable android.adservices.common.AdFilters);
method @NonNull public android.adservices.common.AdData.Builder setMetadata(@NonNull String);
method @NonNull public android.adservices.common.AdData.Builder setRenderUri(@NonNull android.net.Uri);
}
+ public final class AdFilters implements android.os.Parcelable {
+ method public int describeContents();
+ method @Nullable public android.adservices.common.FrequencyCapFilters getFrequencyCapFilters();
+ method public void writeToParcel(@NonNull android.os.Parcel, int);
+ field @NonNull public static final android.os.Parcelable.Creator<android.adservices.common.AdFilters> CREATOR;
+ }
+
+ public static final class AdFilters.Builder {
+ ctor public AdFilters.Builder();
+ method @NonNull public android.adservices.common.AdFilters build();
+ method @NonNull public android.adservices.common.AdFilters.Builder setFrequencyCapFilters(@Nullable android.adservices.common.FrequencyCapFilters);
+ }
+
public final class AdSelectionSignals implements android.os.Parcelable {
method public int describeContents();
method @NonNull public static android.adservices.common.AdSelectionSignals fromString(@NonNull String);
@@ -151,6 +183,46 @@
field @NonNull public static final android.os.Parcelable.Creator<android.adservices.common.AdTechIdentifier> CREATOR;
}
+ public final class FrequencyCapFilters implements android.os.Parcelable {
+ method public int describeContents();
+ method @NonNull public java.util.List<android.adservices.common.KeyedFrequencyCap> getKeyedFrequencyCapsForClickEvents();
+ method @NonNull public java.util.List<android.adservices.common.KeyedFrequencyCap> getKeyedFrequencyCapsForImpressionEvents();
+ method @NonNull public java.util.List<android.adservices.common.KeyedFrequencyCap> getKeyedFrequencyCapsForViewEvents();
+ method @NonNull public java.util.List<android.adservices.common.KeyedFrequencyCap> getKeyedFrequencyCapsForWinEvents();
+ method public void writeToParcel(@NonNull android.os.Parcel, int);
+ field public static final int AD_EVENT_TYPE_CLICK = 3; // 0x3
+ field public static final int AD_EVENT_TYPE_IMPRESSION = 1; // 0x1
+ field public static final int AD_EVENT_TYPE_VIEW = 2; // 0x2
+ field public static final int AD_EVENT_TYPE_WIN = 0; // 0x0
+ field @NonNull public static final android.os.Parcelable.Creator<android.adservices.common.FrequencyCapFilters> CREATOR;
+ }
+
+ public static final class FrequencyCapFilters.Builder {
+ ctor public FrequencyCapFilters.Builder();
+ method @NonNull public android.adservices.common.FrequencyCapFilters build();
+ method @NonNull public android.adservices.common.FrequencyCapFilters.Builder setKeyedFrequencyCapsForClickEvents(@NonNull java.util.List<android.adservices.common.KeyedFrequencyCap>);
+ method @NonNull public android.adservices.common.FrequencyCapFilters.Builder setKeyedFrequencyCapsForImpressionEvents(@NonNull java.util.List<android.adservices.common.KeyedFrequencyCap>);
+ method @NonNull public android.adservices.common.FrequencyCapFilters.Builder setKeyedFrequencyCapsForViewEvents(@NonNull java.util.List<android.adservices.common.KeyedFrequencyCap>);
+ method @NonNull public android.adservices.common.FrequencyCapFilters.Builder setKeyedFrequencyCapsForWinEvents(@NonNull java.util.List<android.adservices.common.KeyedFrequencyCap>);
+ }
+
+ public final class KeyedFrequencyCap implements android.os.Parcelable {
+ method public int describeContents();
+ method @NonNull public int getAdCounterKey();
+ method @NonNull public java.time.Duration getInterval();
+ method public int getMaxCount();
+ method public void writeToParcel(@NonNull android.os.Parcel, int);
+ field @NonNull public static final android.os.Parcelable.Creator<android.adservices.common.KeyedFrequencyCap> CREATOR;
+ }
+
+ public static final class KeyedFrequencyCap.Builder {
+ ctor public KeyedFrequencyCap.Builder(int, int, @NonNull java.time.Duration);
+ method @NonNull public android.adservices.common.KeyedFrequencyCap build();
+ method @NonNull public android.adservices.common.KeyedFrequencyCap.Builder setAdCounterKey(int);
+ method @NonNull public android.adservices.common.KeyedFrequencyCap.Builder setInterval(@NonNull java.time.Duration);
+ method @NonNull public android.adservices.common.KeyedFrequencyCap.Builder setMaxCount(int);
+ }
+
}
package android.adservices.customaudience {
diff --git a/adservices/framework/java/android/adservices/adselection/AdSelectionManager.java b/adservices/framework/java/android/adservices/adselection/AdSelectionManager.java
index b3bf329..4935f6c 100644
--- a/adservices/framework/java/android/adservices/adselection/AdSelectionManager.java
+++ b/adservices/framework/java/android/adservices/adselection/AdSelectionManager.java
@@ -591,10 +591,7 @@
* <p>In all other failure cases, the {@code outcomeReceiver} will return an empty {@link
* Object}. Note that to protect user privacy, internal errors will not be sent back via an
* exception.
- *
- * @hide
*/
- // TODO(b/221876775): Unhide for frequency cap API review
@RequiresPermission(ACCESS_ADSERVICES_CUSTOM_AUDIENCE)
public void updateAdCounterHistogram(
@NonNull UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest,
diff --git a/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramInput.java b/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramInput.java
index dd79125..1e46859 100644
--- a/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramInput.java
+++ b/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramInput.java
@@ -36,7 +36,8 @@
* Input object wrapping the required arguments needed to update an ad counter histogram.
*
* <p>The ad counter histograms, which are historical logs of events which are associated with an ad
- * counter key and an ad event type, are used to inform frequency cap filtering in FLEDGE.
+ * counter key and an ad event type, are used to inform frequency cap filtering when using the
+ * Protected Audience APIs.
*
* @hide
*/
@@ -86,11 +87,11 @@
/**
* Gets the ad selection ID with which the rendered ad's events are associated.
*
- * <p>The ad must have been selected from FLEDGE ad selection in the last 24 hours, and the ad
- * selection call must have been initiated from the same app as the current calling app. Event
- * histograms for all ad counter keys associated with the ad specified by the ad selection ID
- * will be updated for the ad event type from {@link #getAdEventType()}, to be used in FLEDGE
- * frequency cap filtering.
+ * <p>The ad must have been selected from Protected Audience ad selection in the last 24 hours,
+ * and the ad selection call must have been initiated from the same app as the current calling
+ * app. Event histograms for all ad counter keys associated with the ad specified by the ad
+ * selection ID will be updated for the ad event type from {@link #getAdEventType()}, to be used
+ * in Protected Audience frequency cap filtering.
*/
public long getAdSelectionId() {
return mAdSelectionId;
@@ -125,8 +126,8 @@
/**
* Gets the caller app's package name.
*
- * <p>The package name must match the caller package name for the FLEDGE ad selection
- * represented by the ID returned by {@link #getAdSelectionId()}.
+ * <p>The package name must match the caller package name for the Protected Audience ad
+ * selection represented by the ID returned by {@link #getAdSelectionId()}.
*/
@NonNull
public String getCallerPackageName() {
@@ -209,7 +210,7 @@
}
/**
- * Gets the ad selection ID with which the rendered ad's events are associated.
+ * Sets the ad selection ID with which the rendered ad's events are associated.
*
* <p>See {@link #getAdSelectionId()} for more information.
*/
diff --git a/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramRequest.java b/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramRequest.java
index 6c3c210..fd3b82f 100644
--- a/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramRequest.java
+++ b/adservices/framework/java/android/adservices/adselection/UpdateAdCounterHistogramRequest.java
@@ -34,11 +34,9 @@
* Request object wrapping the required arguments needed to update an ad counter histogram.
*
* <p>The ad counter histograms, which are historical logs of events which are associated with an ad
- * counter key and an ad event type, are used to inform frequency cap filtering in FLEDGE.
- *
- * @hide
+ * counter key and an ad event type, are used to inform frequency cap filtering when using the
+ * Protected Audience APIs.
*/
-// TODO(b/221876775): Unhide for frequency cap API review
public class UpdateAdCounterHistogramRequest {
/** @hide */
public static final String UNSET_AD_EVENT_TYPE_MESSAGE = "Ad event type must be set";
@@ -67,11 +65,11 @@
*
* <p>For more information about the ad selection ID, see {@link AdSelectionOutcome}.
*
- * <p>The ad must have been selected from FLEDGE ad selection in the last 24 hours, and the ad
- * selection call must have been initiated from the same app as the current calling app. Event
- * histograms for all ad counter keys associated with the ad specified by the ad selection ID
- * will be updated for the ad event type from {@link #getAdEventType()}, to be used in FLEDGE
- * frequency cap filtering.
+ * <p>The ad must have been selected from Protected Audience ad selection in the last 24 hours,
+ * and the ad selection call must have been initiated from the same app as the current calling
+ * app. Event histograms for all ad counter keys associated with the ad specified by the ad
+ * selection ID will be updated for the ad event type from {@link #getAdEventType()}, to be used
+ * in Protected Audience frequency cap filtering.
*/
public long getAdSelectionId() {
return mAdSelectionId;
@@ -156,7 +154,7 @@
}
/**
- * Gets the ad selection ID with which the rendered ad's events are associated.
+ * Sets the ad selection ID with which the rendered ad's events are associated.
*
* <p>See {@link #getAdSelectionId()} for more information.
*/
diff --git a/adservices/framework/java/android/adservices/common/AdData.java b/adservices/framework/java/android/adservices/common/AdData.java
index 1b300e1..445de96 100644
--- a/adservices/framework/java/android/adservices/common/AdData.java
+++ b/adservices/framework/java/android/adservices/common/AdData.java
@@ -124,10 +124,7 @@
*
* <p>Note that these keys can be overwritten along with the ads and other bidding data for a
* custom audience during the custom audience's daily update.
- *
- * @hide
*/
- // TODO(b/221876775): Unhide for frequency cap API review
@NonNull
public Set<Integer> getAdCounterKeys() {
return mAdCounterKeys;
@@ -138,10 +135,7 @@
*
* <p>The filters, if met or exceeded, exclude the associated ad from participating in ad
* selection. They are optional and if {@code null} specify that no filters apply to this ad.
- *
- * @hide
*/
- // TODO(b/221876775): Unhide for app install/frequency cap API review
@Nullable
public AdFilters getAdFilters() {
return mAdFilters;
@@ -234,10 +228,7 @@
* Sets the set of keys used in counting events.
*
* <p>See {@link #getAdCounterKeys()} for more information.
- *
- * @hide
*/
- // TODO(b/221876775): Unhide for frequency cap API review
@NonNull
public AdData.Builder setAdCounterKeys(@NonNull Set<Integer> adCounterKeys) {
Objects.requireNonNull(adCounterKeys);
@@ -251,10 +242,7 @@
* Sets all {@link AdFilters} associated with the ad.
*
* <p>See {@link #getAdFilters()} for more information.
- *
- * @hide
*/
- // TODO(b/221876775): Unhide for app install/frequency cap API review
@NonNull
public AdData.Builder setAdFilters(@Nullable AdFilters adFilters) {
mAdFilters = adFilters;
diff --git a/adservices/framework/java/android/adservices/common/AdFilters.java b/adservices/framework/java/android/adservices/common/AdFilters.java
index 72eb816..e87653a 100644
--- a/adservices/framework/java/android/adservices/common/AdFilters.java
+++ b/adservices/framework/java/android/adservices/common/AdFilters.java
@@ -35,10 +35,7 @@
* <p>If any of the filters in an {@link AdFilters} instance are not satisfied, the associated ad
* will not be eligible for ad selection. Filters are optional ad parameters and are not required as
* part of {@link AdData}.
- *
- * @hide
*/
-// TODO(b/221876775): Unhide for frequency cap API review
public final class AdFilters implements Parcelable {
/** @hide */
@VisibleForTesting public static final String FREQUENCY_CAP_FIELD_NAME = "frequency_cap";
@@ -87,8 +84,6 @@
* the ad.
*
* <p>If {@code null}, there are no frequency cap filters which apply to the ad.
- *
- * @hide
*/
@Nullable
public FrequencyCapFilters getFrequencyCapFilters() {
@@ -224,8 +219,6 @@
*
* <p>If set to {@code null} or not set, no frequency cap filters will be associated with
* the ad.
- *
- * @hide
*/
@NonNull
public Builder setFrequencyCapFilters(@Nullable FrequencyCapFilters frequencyCapFilters) {
diff --git a/adservices/framework/java/android/adservices/common/FrequencyCapFilters.java b/adservices/framework/java/android/adservices/common/FrequencyCapFilters.java
index da18b66..f4792c6 100644
--- a/adservices/framework/java/android/adservices/common/FrequencyCapFilters.java
+++ b/adservices/framework/java/android/adservices/common/FrequencyCapFilters.java
@@ -17,6 +17,7 @@
package android.adservices.common;
import android.adservices.adselection.ReportImpressionRequest;
+import android.adservices.adselection.UpdateAdCounterHistogramRequest;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.os.OutcomeReceiver;
@@ -42,14 +43,11 @@
* <p>Frequency caps filters combine an event type with a list of {@link KeyedFrequencyCap} objects
* to define a collection of ad filters. If any of these frequency caps are exceeded for a given ad,
* the ad will be removed from the group of ads submitted to a buyer adtech's bidding function.
- *
- * @hide
*/
-// TODO(b/221876775): Unhide for frequency cap API review
public final class FrequencyCapFilters implements Parcelable {
/**
* Event types which are used to update ad counter histograms, which inform frequency cap
- * filtering in FLEDGE.
+ * filtering in Protected Audience.
*
* @hide
*/
@@ -69,8 +67,8 @@
public static final int AD_EVENT_TYPE_INVALID = -1;
/**
- * The WIN ad event type is automatically populated within the FLEDGE service for any winning ad
- * which is returned from FLEDGE ad selection.
+ * The WIN ad event type is automatically populated within the Protected Audience service for
+ * any winning ad which is returned from Protected Audience ad selection.
*
* <p>It should not be used to manually update an ad counter histogram.
*/
@@ -138,6 +136,10 @@
* <p>These frequency caps apply to events for ads that were selected as winners in ad
* selection. Winning ads are used to automatically increment the associated counter keys on the
* win event type.
+ *
+ * <p>Note that the {@link #AD_EVENT_TYPE_WIN} event type cannot be updated manually using the
+ * {@link android.adservices.adselection.AdSelectionManager#updateAdCounterHistogram(
+ * UpdateAdCounterHistogramRequest, Executor, OutcomeReceiver)} API.
*/
@NonNull
public List<KeyedFrequencyCap> getKeyedFrequencyCapsForWinEvents() {
@@ -149,9 +151,14 @@
* #AD_EVENT_TYPE_IMPRESSION} event type.
*
* <p>These frequency caps apply to events which correlate to an impression as interpreted by an
- * adtech. Note that events are not automatically counted when calling {@link
+ * adtech.
+ *
+ * <p>Note that events are not automatically counted when calling {@link
* android.adservices.adselection.AdSelectionManager#reportImpression(ReportImpressionRequest,
- * Executor, OutcomeReceiver)}.
+ * Executor, OutcomeReceiver)}. Instead, the {@link #AD_EVENT_TYPE_IMPRESSION} event type must
+ * be updated using the {@link
+ * android.adservices.adselection.AdSelectionManager#updateAdCounterHistogram(
+ * UpdateAdCounterHistogramRequest, Executor, OutcomeReceiver)} API.
*/
@NonNull
public List<KeyedFrequencyCap> getKeyedFrequencyCapsForImpressionEvents() {
@@ -163,7 +170,10 @@
* #AD_EVENT_TYPE_VIEW} event type.
*
* <p>These frequency caps apply to events which correlate to a view as interpreted by an
- * adtech.
+ * adtech. View events are counted when the {@link
+ * android.adservices.adselection.AdSelectionManager#updateAdCounterHistogram(
+ * UpdateAdCounterHistogramRequest, Executor, OutcomeReceiver)} API is invoked with the {@link
+ * #AD_EVENT_TYPE_VIEW} event type.
*/
@NonNull
public List<KeyedFrequencyCap> getKeyedFrequencyCapsForViewEvents() {
@@ -175,7 +185,10 @@
* #AD_EVENT_TYPE_CLICK} event type.
*
* <p>These frequency caps apply to events which correlate to a click as interpreted by an
- * adtech.
+ * adtech. Click events are counted when the {@link
+ * android.adservices.adselection.AdSelectionManager#updateAdCounterHistogram(
+ * UpdateAdCounterHistogramRequest, Executor, OutcomeReceiver)} API is invoked with the {@link
+ * #AD_EVENT_TYPE_CLICK} event type.
*/
@NonNull
public List<KeyedFrequencyCap> getKeyedFrequencyCapsForClickEvents() {
diff --git a/adservices/framework/java/android/adservices/common/KeyedFrequencyCap.java b/adservices/framework/java/android/adservices/common/KeyedFrequencyCap.java
index cbac585..6b15cda 100644
--- a/adservices/framework/java/android/adservices/common/KeyedFrequencyCap.java
+++ b/adservices/framework/java/android/adservices/common/KeyedFrequencyCap.java
@@ -34,10 +34,7 @@
*
* <p>Frequency caps define the maximum rate an event can occur within a given time interval. If the
* frequency cap is exceeded, the associated ad will be filtered out of ad selection.
- *
- * @hide
*/
-// TODO(b/221876775): Unhide for frequency cap API review
public final class KeyedFrequencyCap implements Parcelable {
/** @hide */
@VisibleForTesting public static final String AD_COUNTER_KEY_FIELD_NAME = "ad_counter_key";
