Page Summary
-
The protocol defines how to upload user data, including identifiers and user list memberships, to Google.
-
Different types of user identifiers are supported, such as Google User IDs, various advertising IDs (iOS, Android, Roku, Amazon, XBOX/Microsoft), generic device IDs, and partner-provided IDs.
-
User data operations include adding or deleting users from lists, and optionally indicating user opt-out status.
-
Requests must include a
process_consent=Trueparameter to indicate the proper legal basis for sharing user data. -
The response indicates the success or failure of operations, provides details on errors for individual user operations, and can include notifications about user IDs.
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 ; }
