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.adselection; 18 19 import static android.adservices.adselection.AdSelectionOutcome.UNSET_AD_SELECTION_ID; 20 import static android.adservices.adselection.AdSelectionOutcome.UNSET_AD_SELECTION_ID_MESSAGE; 21 22 import android.annotation.IntDef; 23 import android.annotation.NonNull; 24 25 import com.android.internal.util.Preconditions; 26 27 import java.lang.annotation.Retention; 28 import java.lang.annotation.RetentionPolicy; 29 import java.util.Objects; 30 31 /** 32 * Request object wrapping the required arguments needed to report an interaction. 33 * 34 * @hide 35 */ 36 // TODO(b/261812140): Unhide for report interaction API review 37 public class ReportInteractionRequest { 38 public static final int FLAG_REPORTING_DESTINATION_SELLER = 1 << 0; 39 public static final int FLAG_REPORTING_DESTINATION_BUYER = 1 << 1; 40 private static final int UNSET_REPORTING_DESTINATIONS = 0; 41 private static final String UNSET_REPORTING_DESTINATIONS_MESSAGE = 42 "Reporting destinations bitfield not set."; 43 44 private final long mAdSelectionId; 45 @NonNull private final String mInteractionKey; 46 @NonNull private final String mInteractionData; 47 @ReportingDestination private final int mReportingDestinations; // buyer, seller, or both 48 ReportInteractionRequest( long adSelectionId, @NonNull String interactionKey, @NonNull String interactionData, @ReportingDestination int reportingDestinations)49 public ReportInteractionRequest( 50 long adSelectionId, 51 @NonNull String interactionKey, 52 @NonNull String interactionData, 53 @ReportingDestination int reportingDestinations) { 54 Objects.requireNonNull(interactionKey); 55 Objects.requireNonNull(interactionData); 56 57 Preconditions.checkArgument( 58 adSelectionId != UNSET_AD_SELECTION_ID, UNSET_AD_SELECTION_ID_MESSAGE); 59 Preconditions.checkArgument( 60 reportingDestinations != UNSET_REPORTING_DESTINATIONS, 61 UNSET_REPORTING_DESTINATIONS_MESSAGE); 62 63 this.mAdSelectionId = adSelectionId; 64 this.mInteractionKey = interactionKey; 65 this.mInteractionData = interactionData; 66 this.mReportingDestinations = reportingDestinations; 67 } 68 69 /** Returns the adSelectionId, the primary identifier of an ad selection process. */ getAdSelectionId()70 public long getAdSelectionId() { 71 return mAdSelectionId; 72 } 73 74 /** 75 * Returns the interaction key, the type of interaction to be reported. 76 * 77 * <p>This will be used to fetch the {@code interactionReportingUri} associated with the {@code 78 * interactionKey} registered in {@code registerAdBeacon} after ad selection. 79 */ 80 @NonNull getInteractionKey()81 public String getInteractionKey() { 82 return mInteractionKey; 83 } 84 85 /** 86 * Returns the interaction data. 87 * 88 * <p>After ad selection, this data is generated by the caller, and will be attached in a POST 89 * request to the {@code interactionReportingUri} registered in {@code registerAdBeacon}. 90 */ 91 @NonNull getInteractionData()92 public String getInteractionData() { 93 return mInteractionData; 94 } 95 96 /** 97 * Returns the bitfield of reporting destinations to report to (buyer, seller, or both). 98 * 99 * <p>To create this bitfield, place an {@code |} bitwise operator between each {@code 100 * reportingDestination} to be reported to. For example to only report to buyer, set the 101 * reportingDestinations field to {@link #FLAG_REPORTING_DESTINATION_BUYER} To only report to 102 * seller, set the reportingDestinations field to {@link #FLAG_REPORTING_DESTINATION_SELLER} To 103 * report to both buyers and sellers, set the reportingDestinations field to {@link 104 * #FLAG_REPORTING_DESTINATION_BUYER} | {@link #FLAG_REPORTING_DESTINATION_SELLER} 105 */ 106 @ReportingDestination getReportingDestinations()107 public int getReportingDestinations() { 108 return mReportingDestinations; 109 } 110 111 /** @hide */ 112 @IntDef( 113 flag = true, 114 prefix = {"FLAG_REPORTING_DESTINATION"}, 115 value = {FLAG_REPORTING_DESTINATION_SELLER, FLAG_REPORTING_DESTINATION_BUYER}) 116 @Retention(RetentionPolicy.SOURCE) 117 public @interface ReportingDestination {} 118 } 119