View raw content Back to Reference page
// Protocol version: v.24
// Copyright 2024 Google Inc. All Rights Reserved.
// The type of identifier being uploaded.
enum UserIdType {
// A user identifier received through the cookie matching service.
GOOGLE_USER_ID = 0;
// iOS Advertising ID.
IDFA = 1;
// Android Advertising ID.
ANDROID_ADVERTISING_ID = 2;
// Roku ID.
RIDA = 5;
// Amazon Fire TV ID.
AFAI = 6;
// XBOX/Microsoft ID.
MSAI = 7;
// A "generic" category for any UUID formatted device provided ID.
// Allows partner uploads without needing to select a specific,
// pre-existing Device ID type.
GENERIC_DEVICE_ID = 9;
// Partner provided ID. User identifier in partner's namespace.
// If the partner has sent the partner user identifier during cookie matching,
// then Google will be able to store user list membership associated with
// the partner's user identifier.
// See cookie matching documentation:
// https://developers.google.com/authorized-buyers/rtb/cookie-guide
PARTNER_PROVIDED_ID = 4;
}
// Notification code.
enum NotificationCode {
// A cookie is considered inactive if Google has not seen any activity related
// to the cookie in several days.
INACTIVE_COOKIE = 0;
}
// Notification status code.
enum NotificationStatus {
// No need to send notifications for this request.
NO_NOTIFICATION = 0;
// Google decided to not send notifications, even though there were
// notifications to send.
NOTIFICATIONS_OMITTED = 1;
}
// Update data for a single user.
message UserDataOperation {
// User id. The type is determined by the user_id_type field.
//
// Must always be present. Specifies which user this operation applies to.
optional string user_id = 1 [default = ""];
// The type of the user id.
optional UserIdType user_id_type = 14 [default = GOOGLE_USER_ID];
// The id of the userlist. This can be retrieved from the AdX UI for AdX
// customers, the AdWords API for non-AdX customers, or through your Technical
// Account Manager.
optional int64 user_list_id = 4 [default = 0];
// Optional time (seconds since the epoch) when the user performed an action
// causing them to be added to the list. Using the default value of 0
// indicates that the current time on the server should be used.
optional int64 time_added_to_user_list = 5 [default = 0];
// Same as time_added_to_user_list but with finer grained time resolution, in
// microseconds. If both timestamps are specified,
// time_added_to_user_list_in_usec will be used.
optional int64 time_added_to_user_list_in_usec = 8 [default = 0];
// Set to true if the operation is a deletion.
optional bool delete = 6 [default = false];
// Set true if the user opted out from being targeted.
optional bool opt_out = 12 [default = false];
// An id indicating the data source which contributed this membership. The id
// is required to be in the range of 1 to 1000 and any ids greater than this
// will result in an error of type BAD_DATA_SOURCE_ID. These ids don't have
// any semantics for Google and may be used as labels for reporting purposes.
optional int32 data_source_id = 7 [default = 0];
}
// This protocol buffer is used to update user data. It is sent as the payload
// of an HTTPS POST request with the Content-Type header set to
// "application/octet-stream" (preferrably Content-Encoding: gzip).
message UpdateUsersDataRequest {
// Multiple operations over user attributes or user lists.
repeated UserDataOperation ops = 1;
// If true, request sending notifications about the given users in the
// response. Note that in some circumstances notifications may not be sent
// even if requested. In this case the notification_status field of the
// response will be set to NOTIFICATIONS_OMITTED.
optional bool send_notifications = 2 [default = false];
// Partners using the Bulk Upload API must indicate that they have the proper
// legal basis to share user data with Google for Bulk Upload purposes using
// the process_consent parameter. This requirement applies to all Bulk Upload
// requests.
//
// For user data that requires end-user consent as
// required by Google's EU User Consent Policy
// (see https://www.google.com/about/company/user-consent-policy/) or
// by other local laws, partners are required to obtain
// end-user consent and indicate gathered consent
// by setting process_consent=True.
//
// For user data which is not subject to end-user consent requirements,
// partners are required to indicate that consent is not
// required by setting process_consent=True.
//
// Requests without `process_consent=True` will be filtered.
optional bool process_consent = 3 [default = false];
}
// Response error codes.
enum ErrorCode {
NO_ERROR = 0;
// Some of the user data operations failed. See comments in the
// UpdateUserDataResponse
PARTIAL_SUCCESS = 1;
// Provided network_id cannot add data to attribute_id or non-HTTPS.
PERMISSION_DENIED = 2;
// Cannot parse payload.
BAD_DATA = 3;
// Cannot decode provided cookie.
BAD_COOKIE = 4;
// Invalid or closed user_list_id.
BAD_ATTRIBUTE_ID = 5;
// An invalid nid parameter was provided in the request.
BAD_NETWORK_ID = 7;
// Request payload size over allowed limit.
REQUEST_TOO_BIG = 8;
// No UserDataOperation messages in UpdateUsersDataRequest.
EMPTY_REQUEST = 9;
// The server could not process the request due to an internal error. Retrying
// the same request later is suggested.
INTERNAL_ERROR = 10;
// Bad data_source_id -- most likely out of range from [1, 1000].
BAD_DATA_SOURCE_ID = 11;
// The timestamp is a past/future time that is too far from current time.
BAD_TIMESTAMP = 12;
// Partners using the Bulk Upload API must indicate that they have the proper
// legal basis to share user data with Google for Bulk Upload purposes using
// the process_consent parameter. This requirement applies to all Bulk Upload
// requests.
//
// For user data that requires end-user consent as
// required by Google's EU User Consent Policy
// (see https://www.google.com/about/company/user-consent-policy/) or
// by other local laws, partners are required to obtain
// end-user consent and indicate gathered consent
// by setting process_consent=True.
//
// For user data which is not subject to end-user consent requirements,
// partners are required to indicate that consent is not
// required by setting process_consent=True.
//
// Requests where `process_consent` is missing will be filtered and
// return the following error:
MISSING_CONSENT_WILL_BE_DROPPED = 22;
// Requests where `process_consent` is set to `false` will be filtered and
// return the following error:
MISSING_CONSENT = 23;
// Missing internal mapping.
// If operation is PARTNER_PROVIDED_ID, then this error means our mapping
// table does not contain corresponding google user id. This mapping is
// recorded during Cookie Matching.
// For other operations, then it may be internal error.
UNKNOWN_ID = 21;
}
// Information about an error with an individual user operation.
message ErrorInfo {
// The user_list_id in the request which caused problems. This may be empty
// if the problem was with a particular user id.
optional int64 user_list_id = 2 [default = 0];
// The user_id which caused problems. This may be empty if other data was bad
// regardless of a cookie.
optional string user_id = 3 [default = ""];
// The type of the user ID.
optional UserIdType user_id_type = 7 [default = GOOGLE_USER_ID];
optional ErrorCode error_code = 4;
}
// Per user notification information.
message NotificationInfo {
// The user_id for which the notification applies. One of the user_ids sent
// in a UserDataOperation.
optional string user_id = 1 [default = ""];
optional NotificationCode notification_code = 2;
}
// Response to the UpdateUsersDataRequest. Sent in HTTP response to the
// original POST request, with the Content-Type header set to
// "application/octet-stream". The HTTP response status is either 200 (no
// errors) or 400, in which case the protocol buffer will provide error details.
message UpdateUsersDataResponse {
// When status == PARTIAL_SUCCESS, some (not all) of the operations failed and
// the "errors" field has details on the types and number of errors
// encountered. When status == NO_ERROR, all the data was imported
// successfully. When status > PARTIAL_SUCCESS no data was imported.
optional ErrorCode status = 1;
// Each operation that failed is reported as a separate error here when
// status == PARTIAL_SUCCESS.
repeated ErrorInfo errors = 2;
// Useful, non-error, information about the user ids in the request. Each
// NotificationInfo provides information about a single user id. Only sent if
// UpdateUsersDataRequest.send_notifications is set to true.
repeated NotificationInfo notifications = 3;
// Indicates why a notification has not been sent.
optional NotificationStatus notification_status = 4;
}