1 // Copyright 2018 Google LLC.
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
18 package google.ads.googleads.v0.common;
20 import "google/ads/googleads/v0/enums/customer_match_upload_key_type.proto";
21 import "google/ads/googleads/v0/enums/user_list_combined_rule_operator.proto";
22 import "google/ads/googleads/v0/enums/user_list_crm_data_source_type.proto";
23 import "google/ads/googleads/v0/enums/user_list_date_rule_item_operator.proto";
24 import "google/ads/googleads/v0/enums/user_list_logical_rule_operator.proto";
25 import "google/ads/googleads/v0/enums/user_list_number_rule_item_operator.proto";
26 import "google/ads/googleads/v0/enums/user_list_prepopulation_status.proto";
27 import "google/ads/googleads/v0/enums/user_list_rule_type.proto";
28 import "google/ads/googleads/v0/enums/user_list_string_rule_item_operator.proto";
29 import "google/protobuf/wrappers.proto";
31 option csharp_namespace = "Google.Ads.GoogleAds.V0.Common";
32 option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v0/common;common";
33 option java_multiple_files = true;
34 option java_outer_classname = "UserListsProto";
35 option java_package = "com.google.ads.googleads.v0.common";
36 option objc_class_prefix = "GAA";
37 option php_namespace = "Google\\Ads\\GoogleAds\\V0\\Common";
38 option ruby_package = "Google::Ads::GoogleAds::V0::Common";
40 // Proto file describing user list types.
42 // SimilarUserList is a list of users which are similar to users from another
43 // UserList. These lists are read-only and automatically created by Google.
44 message SimilarUserListInfo {
45 // Seed UserList from which this list is derived.
46 google.protobuf.StringValue seed_user_list = 1;
49 // UserList of CRM users provided by the advertiser.
50 message CrmBasedUserListInfo {
51 // A string that uniquely identifies a mobile application from which the data
52 // was collected to the Google Ads API.
53 // For iOS, the ID string is the 9 digit string that appears at the end of an
54 // App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is
55 // http://itunes.apple.com/us/app/flood-it!-2/id476943146).
56 // For Android, the ID string is the application's package name
57 // (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link
58 // https://play.google.com/store/apps/details?id=com.labpixies.colordrips).
59 // Required when creating CrmBasedUserList for uploading mobile advertising
61 google.protobuf.StringValue app_id = 1;
63 // Matching key type of the list.
64 // Mixed data types are not allowed on the same list.
65 // This field is required for an ADD operation.
66 google.ads.googleads.v0.enums.CustomerMatchUploadKeyTypeEnum
67 .CustomerMatchUploadKeyType upload_key_type = 2;
69 // Data source of the list. Default value is FIRST_PARTY.
70 // Only whitelisted customers can create third party sourced crm lists.
71 google.ads.googleads.v0.enums.UserListCrmDataSourceTypeEnum
72 .UserListCrmDataSourceType data_source_type = 3;
75 // A client defined rule based on custom parameters sent by web sites or
76 // uploaded by the advertiser.
77 message UserListRuleInfo {
78 // Rule type is used to determine how to group rule items.
80 // The default is OR of ANDs (disjunctive normal form).
81 // That is, rule items will be ANDed together within rule item groups and the
82 // groups themselves will be ORed together.
84 // Currently AND of ORs (conjunctive normal form) is only supported for
85 // ExpressionRuleUserList.
86 google.ads.googleads.v0.enums.UserListRuleTypeEnum.UserListRuleType
89 // List of rule item groups that defines this rule.
90 // Rule item groups are grouped together based on rule_type.
91 repeated UserListRuleItemGroupInfo rule_item_groups = 2;
94 // A group of rule items.
95 message UserListRuleItemGroupInfo {
96 // Rule items that will be grouped together based on rule_type.
97 repeated UserListRuleItemInfo rule_items = 1;
100 // An atomic rule fragment.
101 message UserListRuleItemInfo {
102 // Rule variable name. It should match the corresponding key name fired
104 // A name must begin with US-ascii letters or underscore or UTF8 code that is
105 // greater than 127 and consist of US-ascii letters or digits or underscore or
106 // UTF8 code that is greater than 127.
107 // For websites, there are two built-in variable URL (name = 'url__') and
108 // referrer URL (name = 'ref_url__').
109 // This field must be populated when creating a new rule item.
110 google.protobuf.StringValue name = 1;
112 // An atomic rule fragment.
114 // An atomic rule fragment composed of a number operation.
115 UserListNumberRuleItemInfo number_rule_item = 2;
117 // An atomic rule fragment composed of a string operation.
118 UserListStringRuleItemInfo string_rule_item = 3;
120 // An atomic rule fragment composed of a date operation.
121 UserListDateRuleItemInfo date_rule_item = 4;
125 // A rule item composed of date operation.
126 message UserListDateRuleItemInfo {
127 // Date comparison operator.
128 // This field is required and must be populated when creating new date
130 google.ads.googleads.v0.enums.UserListDateRuleItemOperatorEnum
131 .UserListDateRuleItemOperator
134 // String representing date value to be compared with the rule variable.
135 // Supported date format is YYYY-MM-DD.
136 // Times are reported in the customer's time zone.
137 google.protobuf.StringValue value = 2;
139 // The relative date value of the right hand side denoted by number of days
140 // offset from now. The value field will override this field when both are
142 google.protobuf.Int64Value offset_in_days = 3;
145 // A rule item composed of number operation.
146 message UserListNumberRuleItemInfo {
147 // Number comparison operator.
148 // This field is required and must be populated when creating a new number
150 google.ads.googleads.v0.enums.UserListNumberRuleItemOperatorEnum
151 .UserListNumberRuleItemOperator
154 // Number value to be compared with the variable.
155 // This field is required and must be populated when creating a new number
157 google.protobuf.DoubleValue value = 2;
160 // A rule item fragment composed of date operation.
161 message UserListStringRuleItemInfo {
162 // String comparison operator.
163 // This field is required and must be populated when creating a new string
165 google.ads.googleads.v0.enums.UserListStringRuleItemOperatorEnum
166 .UserListStringRuleItemOperator
169 // The right hand side of the string rule item. For URLs or referrer URLs,
170 // the value can not contain illegal URL chars such as newlines, quotes,
171 // tabs, or parentheses. This field is required and must be populated when
172 // creating a new string rule item.
173 google.protobuf.StringValue value = 2;
176 // User lists defined by combining two rules, left operand and right operand.
177 // There are two operators: AND where left operand and right operand have to be
178 // true; AND_NOT where left operand is true but right operand is false.
179 message CombinedRuleUserListInfo {
180 // Left operand of the combined rule.
181 // This field is required and must be populated when creating new combined
182 // rule based user list.
183 UserListRuleInfo left_operand = 1;
185 // Right operand of the combined rule.
186 // This field is required and must be populated when creating new combined
187 // rule based user list.
188 UserListRuleInfo right_operand = 2;
190 // Operator to connect the two operands.
192 // Required for creating a combined rule user list.
193 google.ads.googleads.v0.enums.UserListCombinedRuleOperatorEnum
194 .UserListCombinedRuleOperator rule_operator = 3;
197 // Visitors of a page during specific dates.
198 message DateSpecificRuleUserListInfo {
199 // Boolean rule that defines visitor of a page.
201 // Required for creating a date specific rule user list.
202 UserListRuleInfo rule = 1;
204 // Start date of users visit. If set to 2000-01-01, then the list includes all
205 // users before end_date. The date's format should be YYYY-MM-DD.
207 // Required for creating a data specific rule user list.
208 google.protobuf.StringValue start_date = 2;
210 // End date of users visit. If set to 2037-12-30, then the list includes all
211 // users after start_date. The date's format should be YYYY-MM-DD.
213 // Required for creating a data specific rule user list.
214 google.protobuf.StringValue end_date = 3;
217 // Visitors of a page. The page visit is defined by one boolean rule expression.
218 message ExpressionRuleUserListInfo {
219 // Boolean rule that defines this user list. The rule consists of a list of
220 // rule item groups and each rule item group consists of a list of rule items.
221 // All the rule item groups are ORed or ANDed together for evaluation based on
224 // Required for creating an expression rule user list.
225 UserListRuleInfo rule = 1;
228 // Representation of a userlist that is generated by a rule.
229 message RuleBasedUserListInfo {
230 // The status of pre-population. The field is default to NONE if not set which
231 // means the previous users will not be considered. If set to REQUESTED, past
232 // site visitors or app users who match the list definition will be included
233 // in the list (works on the Display Network only). This will only
234 // add past users from within the last 30 days, depending on the
235 // list's membership duration and the date when the remarketing tag is added.
236 // The status will be updated to FINISHED once request is processed, or FAILED
237 // if the request fails.
238 google.ads.googleads.v0.enums.UserListPrepopulationStatusEnum
239 .UserListPrepopulationStatus prepopulation_status = 1;
241 // Subtypes of rule based user lists.
242 oneof rule_based_user_list {
243 // User lists defined by combining two rules.
244 // There are two operators: AND, where the left and right operands have to
245 // be true; AND_NOT where left operand is true but right operand is false.
246 CombinedRuleUserListInfo combined_rule_user_list = 2;
248 // Visitors of a page during specific dates. The visiting periods are
249 // defined as follows:
250 // Between start_date (inclusive) and end_date (inclusive);
251 // Before end_date (exclusive) with start_date = 2000-01-01;
252 // After start_date (exclusive) with end_date = 2037-12-30.
253 DateSpecificRuleUserListInfo date_specific_rule_user_list = 3;
255 // Visitors of a page. The page visit is defined by one boolean rule
257 ExpressionRuleUserListInfo expression_rule_user_list = 4;
261 // Represents a user list that is a custom combination of user lists.
262 message LogicalUserListInfo {
263 // Logical list rules that define this user list. The rules are defined as a
264 // logical operator (ALL/ANY/NONE) and a list of user lists. All the rules are
265 // ANDed when they are evaluated.
267 // Required for creating a logical user list.
268 repeated UserListLogicalRuleInfo rules = 1;
271 // A user list logical rule. A rule has a logical operator (and/or/not) and a
272 // list of user lists as operands.
273 message UserListLogicalRuleInfo {
274 // The logical operator of the rule.
275 google.ads.googleads.v0.enums.UserListLogicalRuleOperatorEnum
276 .UserListLogicalRuleOperator
279 // The list of operands of the rule.
280 repeated LogicalUserListOperandInfo rule_operands = 2;
283 // Operand of logical user list that consists of a user list.
284 message LogicalUserListOperandInfo {
285 // Resource name of a user list as an operand.
286 google.protobuf.StringValue user_list = 1;
289 // User list targeting as a collection of conversions or remarketing actions.
290 message BasicUserListInfo {
291 // Actions associated with this user list.
292 repeated UserListActionInfo actions = 1;
295 // Represents an action type used for building remarketing user lists.
296 message UserListActionInfo {
297 // Subtypes of user list action.
298 oneof user_list_action {
299 // A conversion action that's not generated from remarketing.
300 google.protobuf.StringValue conversion_action = 1;
302 // A remarketing action.
303 google.protobuf.StringValue remarketing_action = 2;