1 /*
2  * Copyright (C) 2022 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.adservices.common.AdTechIdentifier;
21 import android.annotation.FlaggedApi;
22 import android.annotation.NonNull;
23 import android.annotation.Nullable;
24 import android.os.OutcomeReceiver;
25 
26 import com.android.adservices.flags.Flags;
27 
28 import java.util.Objects;
29 import java.util.concurrent.Executor;
30 
31 /**
32  * This POJO represents the {@link
33  * TestCustomAudienceManager#overrideCustomAudienceRemoteInfo(AddCustomAudienceOverrideRequest,
34  * Executor, OutcomeReceiver)} request.
35  *
36  * <p>It contains fields {@code buyer} and {@code name} which will serve as the identifier for the
37  * override fields, {@code biddingLogicJs} and {@code trustedBiddingSignals}, which are used during
38  * ad selection instead of querying external servers.
39  */
40 public class AddCustomAudienceOverrideRequest {
41     @NonNull private final AdTechIdentifier mBuyer;
42     @NonNull private final String mName;
43     @NonNull private final String mBiddingLogicJs;
44     private final long mBiddingLogicJsVersion;
45     @NonNull private final AdSelectionSignals mTrustedBiddingSignals;
46 
AddCustomAudienceOverrideRequest( @onNull AdTechIdentifier buyer, @NonNull String name, @NonNull String biddingLogicJs, @NonNull AdSelectionSignals trustedBiddingSignals)47     public AddCustomAudienceOverrideRequest(
48             @NonNull AdTechIdentifier buyer,
49             @NonNull String name,
50             @NonNull String biddingLogicJs,
51             @NonNull AdSelectionSignals trustedBiddingSignals) {
52         this(buyer, name, biddingLogicJs, 0L, trustedBiddingSignals);
53     }
54 
AddCustomAudienceOverrideRequest( @onNull AdTechIdentifier buyer, @NonNull String name, @NonNull String biddingLogicJs, long biddingLogicJsVersion, @NonNull AdSelectionSignals trustedBiddingSignals)55     private AddCustomAudienceOverrideRequest(
56             @NonNull AdTechIdentifier buyer,
57             @NonNull String name,
58             @NonNull String biddingLogicJs,
59             long biddingLogicJsVersion,
60             @NonNull AdSelectionSignals trustedBiddingSignals) {
61         mBuyer = buyer;
62         mName = name;
63         mBiddingLogicJs = biddingLogicJs;
64         mBiddingLogicJsVersion = biddingLogicJsVersion;
65         mTrustedBiddingSignals = trustedBiddingSignals;
66     }
67 
68     /** @return an {@link AdTechIdentifier} representing the buyer */
69     @NonNull
getBuyer()70     public AdTechIdentifier getBuyer() {
71         return mBuyer;
72     }
73 
74     /** @return name of the custom audience being overridden */
75     @NonNull
getName()76     public String getName() {
77         return mName;
78     }
79 
80     /** @return the override JavaScript result that should be served during ad selection */
81     @NonNull
getBiddingLogicJs()82     public String getBiddingLogicJs() {
83         return mBiddingLogicJs;
84     }
85 
86     /**
87      * Returns the value to return as version for JavaScript bidding logic.
88      *
89      * <p>Default to be {@code 0L}, which will fall back to use default version(V1 or V2).
90      */
91     @FlaggedApi(Flags.FLAG_FLEDGE_AD_SELECTION_FILTERING_ENABLED)
getBiddingLogicJsVersion()92     public long getBiddingLogicJsVersion() {
93         return mBiddingLogicJsVersion;
94     }
95 
96     /** @return the override trusted bidding signals that should be served during ad selection */
97     @NonNull
getTrustedBiddingSignals()98     public AdSelectionSignals getTrustedBiddingSignals() {
99         return mTrustedBiddingSignals;
100     }
101 
102     /** Builder for {@link AddCustomAudienceOverrideRequest} objects. */
103     public static final class Builder {
104         @Nullable private AdTechIdentifier mBuyer;
105         @Nullable private String mName;
106         @Nullable private String mBiddingLogicJs;
107         private long mBiddingLogicJsVersion;
108         @Nullable private AdSelectionSignals mTrustedBiddingSignals;
109 
Builder()110         public Builder() {}
111 
112         /** Sets the buyer {@link AdTechIdentifier} for the custom audience. */
113         @NonNull
setBuyer(@onNull AdTechIdentifier buyer)114         public AddCustomAudienceOverrideRequest.Builder setBuyer(@NonNull AdTechIdentifier buyer) {
115             Objects.requireNonNull(buyer);
116 
117             this.mBuyer = buyer;
118             return this;
119         }
120 
121         /** Sets the name for the custom audience to be overridden. */
122         @NonNull
setName(@onNull String name)123         public AddCustomAudienceOverrideRequest.Builder setName(@NonNull String name) {
124             Objects.requireNonNull(name);
125 
126             this.mName = name;
127             return this;
128         }
129 
130         /** Sets the trusted bidding signals to be served during ad selection. */
131         @NonNull
setTrustedBiddingSignals( @onNull AdSelectionSignals trustedBiddingSignals)132         public AddCustomAudienceOverrideRequest.Builder setTrustedBiddingSignals(
133                 @NonNull AdSelectionSignals trustedBiddingSignals) {
134             Objects.requireNonNull(trustedBiddingSignals);
135 
136             this.mTrustedBiddingSignals = trustedBiddingSignals;
137             return this;
138         }
139 
140         /** Sets the bidding logic JavaScript that should be served during ad selection. */
141         @NonNull
setBiddingLogicJs( @onNull String biddingLogicJs)142         public AddCustomAudienceOverrideRequest.Builder setBiddingLogicJs(
143                 @NonNull String biddingLogicJs) {
144             Objects.requireNonNull(biddingLogicJs);
145 
146             this.mBiddingLogicJs = biddingLogicJs;
147             return this;
148         }
149 
150         /**
151          * Sets the bidding logic JavaScript version.
152          *
153          * <p>Default to be {@code 0L}, which will fall back to use default version(V1 or V2).
154          */
155         @FlaggedApi(Flags.FLAG_FLEDGE_AD_SELECTION_FILTERING_ENABLED)
156         @NonNull
setBiddingLogicJsVersion( long biddingLogicJsVersion)157         public AddCustomAudienceOverrideRequest.Builder setBiddingLogicJsVersion(
158                 long biddingLogicJsVersion) {
159             this.mBiddingLogicJsVersion = biddingLogicJsVersion;
160             return this;
161         }
162 
163         /** Builds a {@link AddCustomAudienceOverrideRequest} instance. */
164         @NonNull
build()165         public AddCustomAudienceOverrideRequest build() {
166             Objects.requireNonNull(mBuyer);
167             Objects.requireNonNull(mName);
168             Objects.requireNonNull(mBiddingLogicJs);
169             Objects.requireNonNull(mTrustedBiddingSignals);
170 
171             return new AddCustomAudienceOverrideRequest(
172                     mBuyer, mName, mBiddingLogicJs, mBiddingLogicJsVersion, mTrustedBiddingSignals);
173         }
174     }
175 }
176