Importer dans des listes d'utilisateurs

Vous pouvez utiliser l'outil d'importation groupée décrit ci-dessous pour importer différents ID d'annonces vers des listes d'utilisateurs Google pour le ciblage. Vous pouvez également importer des listes d'utilisateurs comme celles associées aux accords de programmatique garanti.

Importation groupée

Remarque : La mise en correspondance des cookies doit être activée pour que vous puissiez utiliser l'outil d'importation groupée, même si la mise en correspondance des cookies n'est pas utilisée.

Les listes d'utilisateurs Google peuvent être utilisées pour le ciblage, et Authorized Buyers permet aux acheteurs de mettre à jour ces listes d'utilisateurs via des requêtes HTTPS POST. Ils doivent indiquer les ID des annonces, les listes d'utilisateurs et le type de mise à jour (ajout ou suppression). La taille maximale d'une telle requête est de 100 Ko, et son URL est la suivante:

https://cm.g.doubleclick.net/upload?nid=GoogleNetworkId

GoogleNetworkId est un ID Authorized Buyers qui peut être récupéré via le champ cookieMatchingNid de la ressource "Accounts" de l'API pour les acheteurs.

Pour la charge utile de la requête POST HTTPS, les acheteurs fournissent un tampon de protocole encodé, qui décrit les listes ou les cookies à modifier.

Authorized Buyers permet d'importer les identifiants suivants sur les serveurs Google:

• ID utilisateur Google
• IDFA iOS
• Identifiant publicitaire Android
• ID Roku
• ID Amazon Fire TV
• ID Xbox/Microsoft

comme indiqué par les champs enum et message ci-dessous dans le fichier cookie-bulk-upload-proto.txt.

Tampon de protocole d'importation groupée de cookies

Afficher le protocole

// Copyright 2023 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];
}

// 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;

  // 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;
}

Exemple: Ajouter des IDFA à la liste d'utilisateurs

Pour ajouter des IDFA à une liste d'utilisateurs avec l'ID 123, créez le tampon de protocole UpdateUsersDataRequest suivant:

UpdateUsersDataRequest {
  ops {
    user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
  ops {
    user_id: "3024D65F-EBBD-11FF-23AB-823FC255913A"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
  ops {
    user_id: "4024D65F-EBBD-11FF-23AB-823FC255913A"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
  ops {
    user_id: "5024D65F-EBBD-11FF-23AB-823FC255913A"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
}

Envoyez ensuite une requête HTTPS POST avec le tampon de protocole UpdateUsersDataRequest comme charge utile à Authorized Buyers. Si la requête aboutit, vous obtiendrez la réponse suivante:

UpdateUsersDataResponse {
  status = NO_ERROR
}

Si la demande n'aboutit pas, vous obtiendrez la réponse suivante:

UpdateUsersDataRequest {
  ops {
    user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
  ops {
    user_id: "INVALID_FORMAT"
    user_list_id: 123
    time_added_to_user_list: 2132132132
  }
}

Si le premier user_id est valide, mais que le second n'est pas valide, vous obtiendrez une réponse semblable à celle-ci:

UpdateUsersDataResponse {
{
  status: PARTIAL_SUCCESS
  errors: {
    user_id     : "INVALID_FORMAT"
    error_code  : BAD_COOKIE
    time_added_to_user_list: 2132132132
  }
}