1 /* 2 * Copyright (C) 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.adservices.common; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.os.Parcel; 22 import android.os.Parcelable; 23 24 import com.android.adservices.AdServicesParcelableUtil; 25 import com.android.internal.annotations.VisibleForTesting; 26 27 import org.json.JSONException; 28 import org.json.JSONObject; 29 30 import java.util.Objects; 31 32 /** 33 * A container class for filters which are associated with an ad. 34 * 35 * <p>If any of the filters in an {@link AdFilters} instance are not satisfied, the associated ad 36 * will not be eligible for ad selection. Filters are optional ad parameters and are not required as 37 * part of {@link AdData}. 38 * 39 * @hide 40 */ 41 // TODO(b/221876775): Unhide for frequency cap API review 42 public final class AdFilters implements Parcelable { 43 /** @hide */ 44 @VisibleForTesting public static final String FREQUENCY_CAP_FIELD_NAME = "frequency_cap"; 45 /** @hide */ 46 @VisibleForTesting public static final String APP_INSTALL_FIELD_NAME = "app_install"; 47 /** @hide */ 48 @Nullable private final FrequencyCapFilters mFrequencyCapFilters; 49 50 @Nullable private final AppInstallFilters mAppInstallFilters; 51 52 @NonNull 53 public static final Creator<AdFilters> CREATOR = 54 new Creator<AdFilters>() { 55 @Override 56 public AdFilters createFromParcel(@NonNull Parcel in) { 57 Objects.requireNonNull(in); 58 return new AdFilters(in); 59 } 60 61 @Override 62 public AdFilters[] newArray(int size) { 63 return new AdFilters[size]; 64 } 65 }; 66 AdFilters(@onNull Builder builder)67 private AdFilters(@NonNull Builder builder) { 68 Objects.requireNonNull(builder); 69 70 mFrequencyCapFilters = builder.mFrequencyCapFilters; 71 mAppInstallFilters = builder.mAppInstallFilters; 72 } 73 AdFilters(@onNull Parcel in)74 private AdFilters(@NonNull Parcel in) { 75 Objects.requireNonNull(in); 76 77 mFrequencyCapFilters = 78 AdServicesParcelableUtil.readNullableFromParcel( 79 in, FrequencyCapFilters.CREATOR::createFromParcel); 80 mAppInstallFilters = 81 AdServicesParcelableUtil.readNullableFromParcel( 82 in, AppInstallFilters.CREATOR::createFromParcel); 83 } 84 85 /** 86 * Gets the {@link FrequencyCapFilters} instance that represents all frequency cap filters for 87 * the ad. 88 * 89 * <p>If {@code null}, there are no frequency cap filters which apply to the ad. 90 * 91 * @hide 92 */ 93 @Nullable getFrequencyCapFilters()94 public FrequencyCapFilters getFrequencyCapFilters() { 95 return mFrequencyCapFilters; 96 } 97 98 /** 99 * Gets the {@link AppInstallFilters} instance that represents all app install filters for the 100 * ad. 101 * 102 * <p>If {@code null}, there are no app install filters which apply to the ad. 103 * 104 * @hide 105 */ 106 @Nullable getAppInstallFilters()107 public AppInstallFilters getAppInstallFilters() { 108 return mAppInstallFilters; 109 } 110 111 /** 112 * @return The estimated size of this object, in bytes. 113 * @hide 114 */ getSizeInBytes()115 public int getSizeInBytes() { 116 int size = 0; 117 if (mFrequencyCapFilters != null) { 118 size += mFrequencyCapFilters.getSizeInBytes(); 119 } 120 if (mAppInstallFilters != null) { 121 size += mAppInstallFilters.getSizeInBytes(); 122 } 123 return size; 124 } 125 126 /** 127 * A JSON serializer. 128 * 129 * @return A JSON serialization of this object. 130 * @hide 131 */ toJson()132 public JSONObject toJson() throws JSONException { 133 JSONObject toReturn = new JSONObject(); 134 if (mFrequencyCapFilters != null) { 135 toReturn.put(FREQUENCY_CAP_FIELD_NAME, mFrequencyCapFilters.toJson()); 136 } 137 if (mAppInstallFilters != null) { 138 toReturn.put(APP_INSTALL_FIELD_NAME, mAppInstallFilters.toJson()); 139 } 140 return toReturn; 141 } 142 143 /** 144 * A JSON de-serializer. 145 * 146 * @param json A JSON representation of an {@link AdFilters} object as would be generated by 147 * {@link #toJson()}. 148 * @return An {@link AdFilters} object generated from the given JSON. 149 * @hide 150 */ fromJson(JSONObject json)151 public static AdFilters fromJson(JSONObject json) throws JSONException { 152 Builder builder = new Builder(); 153 if (json.has(FREQUENCY_CAP_FIELD_NAME)) { 154 builder.setFrequencyCapFilters( 155 FrequencyCapFilters.fromJson(json.getJSONObject(FREQUENCY_CAP_FIELD_NAME))); 156 } 157 if (json.has(APP_INSTALL_FIELD_NAME)) { 158 builder.setAppInstallFilters( 159 AppInstallFilters.fromJson(json.getJSONObject(APP_INSTALL_FIELD_NAME))); 160 } 161 return builder.build(); 162 } 163 164 @Override writeToParcel(@onNull Parcel dest, int flags)165 public void writeToParcel(@NonNull Parcel dest, int flags) { 166 Objects.requireNonNull(dest); 167 168 AdServicesParcelableUtil.writeNullableToParcel( 169 dest, 170 mFrequencyCapFilters, 171 (targetParcel, sourceFilters) -> sourceFilters.writeToParcel(targetParcel, flags)); 172 AdServicesParcelableUtil.writeNullableToParcel( 173 dest, 174 mAppInstallFilters, 175 (targetParcel, sourceFilters) -> sourceFilters.writeToParcel(targetParcel, flags)); 176 } 177 178 /** @hide */ 179 @Override describeContents()180 public int describeContents() { 181 return 0; 182 } 183 184 /** Checks whether the {@link AdFilters} objects represent the same set of filters. */ 185 @Override equals(Object o)186 public boolean equals(Object o) { 187 if (this == o) return true; 188 if (!(o instanceof AdFilters)) return false; 189 AdFilters adFilters = (AdFilters) o; 190 return Objects.equals(mFrequencyCapFilters, adFilters.mFrequencyCapFilters) 191 && Objects.equals(mAppInstallFilters, adFilters.mAppInstallFilters); 192 } 193 194 /** Returns the hash of the {@link AdFilters} object's data. */ 195 @Override hashCode()196 public int hashCode() { 197 return Objects.hash(mFrequencyCapFilters, mAppInstallFilters); 198 } 199 200 @Override toString()201 public String toString() { 202 return "AdFilters{" + generateFrequencyCapString() + generateAppInstallString() + "}"; 203 } 204 generateFrequencyCapString()205 private String generateFrequencyCapString() { 206 // TODO(b/221876775) Add fcap once it is unhidden 207 return ""; 208 } 209 generateAppInstallString()210 private String generateAppInstallString() { 211 // TODO(b/266837113) Add app install once it is unhidden 212 return ""; 213 } 214 215 /** Builder for creating {@link AdFilters} objects. */ 216 public static final class Builder { 217 @Nullable private FrequencyCapFilters mFrequencyCapFilters; 218 @Nullable private AppInstallFilters mAppInstallFilters; 219 Builder()220 public Builder() {} 221 222 /** 223 * Sets the {@link FrequencyCapFilters} which will apply to the ad. 224 * 225 * <p>If set to {@code null} or not set, no frequency cap filters will be associated with 226 * the ad. 227 * 228 * @hide 229 */ 230 @NonNull setFrequencyCapFilters(@ullable FrequencyCapFilters frequencyCapFilters)231 public Builder setFrequencyCapFilters(@Nullable FrequencyCapFilters frequencyCapFilters) { 232 mFrequencyCapFilters = frequencyCapFilters; 233 return this; 234 } 235 236 /** 237 * Sets the {@link AppInstallFilters} which will apply to the ad. 238 * 239 * <p>If set to {@code null} or not set, no app install filters will be associated with the 240 * ad. 241 * 242 * @hide 243 */ 244 @NonNull setAppInstallFilters(@ullable AppInstallFilters appInstallFilters)245 public Builder setAppInstallFilters(@Nullable AppInstallFilters appInstallFilters) { 246 mAppInstallFilters = appInstallFilters; 247 return this; 248 } 249 250 /** Builds and returns an {@link AdFilters} instance. */ 251 @NonNull build()252 public AdFilters build() { 253 return new AdFilters(this); 254 } 255 } 256 } 257