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.customaudience; 18 19 import android.adservices.common.AdSelectionSignals; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.net.Uri; 23 24 import java.time.Instant; 25 import java.util.Objects; 26 27 /** 28 * The request object wrapping the required and optional parameters needed to fetch a {@link 29 * CustomAudience}. 30 * 31 * <p>{@code fetchUri} is the only required parameter. It represents the URI to fetch a custom 32 * audience from. {@code name}, {@code activationTime}, {@code expirationTime} and {@code 33 * userBiddingSignals} are optional parameters. They represent a partial custom audience which can 34 * be used by the caller to inform the choice of the custom audience the user should be added to. 35 * Any field set by the caller cannot be overridden by the custom audience fetched from the {@code 36 * fetchUri}. For more information about each field refer to {@link CustomAudience}. 37 */ 38 public final class FetchAndJoinCustomAudienceRequest { 39 @NonNull private final Uri mFetchUri; 40 @Nullable private final String mName; 41 @Nullable private final Instant mActivationTime; 42 @Nullable private final Instant mExpirationTime; 43 @Nullable private final AdSelectionSignals mUserBiddingSignals; 44 FetchAndJoinCustomAudienceRequest( @onNull FetchAndJoinCustomAudienceRequest.Builder builder)45 private FetchAndJoinCustomAudienceRequest( 46 @NonNull FetchAndJoinCustomAudienceRequest.Builder builder) { 47 Objects.requireNonNull(builder.mFetchUri); 48 49 mFetchUri = builder.mFetchUri; 50 mName = builder.mName; 51 mActivationTime = builder.mActivationTime; 52 mExpirationTime = builder.mExpirationTime; 53 mUserBiddingSignals = builder.mUserBiddingSignals; 54 } 55 56 /** 57 * @return the {@link Uri} from which the custom audience is to be fetched. 58 */ 59 @NonNull getFetchUri()60 public Uri getFetchUri() { 61 return mFetchUri; 62 } 63 64 /** 65 * Reference {@link CustomAudience#getName()} for details. 66 * 67 * @return the {@link String} name of the custom audience to join. 68 */ 69 @Nullable getName()70 public String getName() { 71 return mName; 72 } 73 74 /** 75 * Reference {@link CustomAudience#getActivationTime()} for details. 76 * 77 * @return the {@link Instant} by which joining the custom audience will be delayed. 78 */ 79 @Nullable getActivationTime()80 public Instant getActivationTime() { 81 return mActivationTime; 82 } 83 84 /** 85 * Reference {@link CustomAudience#getExpirationTime()} for details. 86 * 87 * @return the {@link Instant} by when the membership to the custom audience will expire. 88 */ 89 @Nullable getExpirationTime()90 public Instant getExpirationTime() { 91 return mExpirationTime; 92 } 93 94 /** 95 * Reference {@link CustomAudience#getUserBiddingSignals()} for details. 96 * 97 * @return the buyer signals to be consumed by the buyer-provided JavaScript when the custom 98 * audience participates in an ad selection. 99 */ 100 @Nullable getUserBiddingSignals()101 public AdSelectionSignals getUserBiddingSignals() { 102 return mUserBiddingSignals; 103 } 104 105 /** 106 * @return {@code true} only if two {@link FetchAndJoinCustomAudienceRequest} objects contain 107 * the same information. 108 */ 109 @Override equals(Object o)110 public boolean equals(Object o) { 111 if (this == o) return true; 112 if (!(o instanceof FetchAndJoinCustomAudienceRequest)) return false; 113 FetchAndJoinCustomAudienceRequest that = (FetchAndJoinCustomAudienceRequest) o; 114 return mFetchUri.equals(that.mFetchUri) 115 && Objects.equals(mName, that.mName) 116 && Objects.equals(mActivationTime, that.mActivationTime) 117 && Objects.equals(mExpirationTime, that.mExpirationTime) 118 && Objects.equals(mUserBiddingSignals, that.mUserBiddingSignals); 119 } 120 121 /** 122 * @return the hash of the {@link FetchAndJoinCustomAudienceRequest} object's data. 123 */ 124 @Override hashCode()125 public int hashCode() { 126 return Objects.hash( 127 mFetchUri, mName, mActivationTime, mExpirationTime, mUserBiddingSignals); 128 } 129 130 /** 131 * @return a human-readable representation of {@link FetchAndJoinCustomAudienceRequest}. 132 */ 133 @Override toString()134 public String toString() { 135 return "FetchAndJoinCustomAudienceRequest{" 136 + "fetchUri=" 137 + mFetchUri 138 + ", name=" 139 + mName 140 + ", activationTime=" 141 + mActivationTime 142 + ", expirationTime=" 143 + mExpirationTime 144 + ", userBiddingSignals=" 145 + mUserBiddingSignals 146 + '}'; 147 } 148 149 /** Builder for {@link FetchAndJoinCustomAudienceRequest} objects. */ 150 public static final class Builder { 151 @NonNull private Uri mFetchUri; 152 @Nullable private String mName; 153 @Nullable private Instant mActivationTime; 154 @Nullable private Instant mExpirationTime; 155 @Nullable private AdSelectionSignals mUserBiddingSignals; 156 157 /** 158 * Instantiates a {@link FetchAndJoinCustomAudienceRequest.Builder} with the {@link Uri} 159 * from which the custom audience is to be fetched. 160 */ Builder(@onNull Uri fetchUri)161 public Builder(@NonNull Uri fetchUri) { 162 Objects.requireNonNull(fetchUri); 163 this.mFetchUri = fetchUri; 164 } 165 166 /** 167 * Sets the {@link Uri} from which the custom audience is to be fetched. 168 * 169 * <p>See {@link #getFetchUri()} ()} for details. 170 */ 171 @NonNull setFetchUri(@onNull Uri fetchUri)172 public Builder setFetchUri(@NonNull Uri fetchUri) { 173 Objects.requireNonNull(fetchUri); 174 this.mFetchUri = fetchUri; 175 return this; 176 } 177 178 /** 179 * Sets the {@link String} name of the custom audience to join. 180 * 181 * <p>See {@link #getName()} for details. 182 */ 183 @NonNull setName(@ullable String name)184 public Builder setName(@Nullable String name) { 185 this.mName = name; 186 return this; 187 } 188 189 /** 190 * Sets the {@link Instant} by which joining the custom audience will be delayed. 191 * 192 * <p>See {@link #getActivationTime()} for details. 193 */ 194 @NonNull setActivationTime(@ullable Instant activationTime)195 public Builder setActivationTime(@Nullable Instant activationTime) { 196 this.mActivationTime = activationTime; 197 return this; 198 } 199 200 /** 201 * Sets the {@link Instant} by when the membership to the custom audience will expire. 202 * 203 * <p>See {@link #getExpirationTime()} for details. 204 */ 205 @NonNull setExpirationTime(@ullable Instant expirationTime)206 public Builder setExpirationTime(@Nullable Instant expirationTime) { 207 this.mExpirationTime = expirationTime; 208 return this; 209 } 210 211 /** 212 * Sets the buyer signals to be consumed by the buyer-provided JavaScript when the custom 213 * audience participates in an ad selection. 214 * 215 * <p>See {@link #getUserBiddingSignals()} for details. 216 */ 217 @NonNull setUserBiddingSignals(@ullable AdSelectionSignals userBiddingSignals)218 public Builder setUserBiddingSignals(@Nullable AdSelectionSignals userBiddingSignals) { 219 this.mUserBiddingSignals = userBiddingSignals; 220 return this; 221 } 222 223 /** 224 * Builds an instance of a {@link FetchAndJoinCustomAudienceRequest}. 225 * 226 * @throws NullPointerException if any non-null parameter is null. 227 */ 228 @NonNull build()229 public FetchAndJoinCustomAudienceRequest build() { 230 Objects.requireNonNull(mFetchUri); 231 return new FetchAndJoinCustomAudienceRequest(this); 232 } 233 } 234 } 235