Provided lists

Provided lists allow you augment Campaign Manager's custom segment building capabilities to match your business needs and incorporate offline data from your ad campaigns into your online audience targeting. You can make use of signals in Data Transfer files by downloading match tables, then filtering and selecting the individual cookies of users to whom you’re interested in retargeting. When you upload your audience list files using Google Cloud Storage, the cookies you’ve selected are associated with a particular audience list, which you can then use for retargeting ads. Learn more about how audience lists work

As a reminder, when you use audience lists, you must comply with all applicable contractual and policy restrictions, including prohibitions on the passing of personally identifiable information and on the collection and targeting of certain kinds of user characteristics (learn about audience privacy policies). Please also see our COPPA guidelines if you’ll be placing ads or working with sites directed at children. 

Use cases

You can build complex lists using your own custom data combined with information from Data Transfer files. Some examples are:

  • Cross-selling and upselling: Build audience lists based upon specific custom Floodlight variables (such as a premium hotel room booking) and use display ads to upsell new product ranges and promotions. You can use custom Floodlight variables from your activity Data Transfer files across multiple activities to select the appropriate cookies to add to a list.
  • Subscriber vs. non-subscriber: Build audience lists based off of logged in users or subscriber information joined in CRM systems. You can use an anonymized event ID that is passed into either ad tags or Floodlight tags, then match that data with your offline CRM or site Analytics data to select the appropriate cookies to add to the list.
Benefits of provided lists

Here are some of the benefits of uploading cookies to your audience lists using Google Cloud Storage.

  • Google Cloud Storage allows for fast uploads and uses HTTPS, which is secure by default.

  • There are three different methods you can use for uploading files: through the UI, the command line, or the API.

  • You can upload as many lists as you want per day.

  • Files may include multiple lists, rather than being limited to one file per list.

Upload your audience lists

Prerequisites

You must do the following in order to use provided lists:

  • Be a current user of Campaign Manager.

  • Contact your account manager and have your account enabled for Data Transfer.

  • Set up a Google Group to manage user access to data on Google Cloud Storage (Learn more). Administration of this Group is entirely your responsibility. You can use the same Google Group that you created for Data Transfer. See Access your Data Transfer files for instructions.

Upload your lists

  1. File a request with your Platform Solutions Consultant. We will create two buckets in Google Cloud Storage for organizing your data and provide you with the name of each. The first bucket is where you will upload data; the second is for downloading the resulting log files and is read-only. Learn more about buckets

  2. Make sure that you have a destination audience list to which the cookies will be uploaded. You can create a new list or use an existing one. See Create and edit audiences

  3. Upload the data to your allocated Google Cloud Storage bucket. See “File formatting” below for guidelines on file names, headers, and overall formatting.

  4. There are three different upload methods you can use; it doesn’t matter which one you select, as long as all of your data is uploaded to the allocated bucket. We encourage you to choose the solution which is most compatible with your infrastructure. Both the gsutil and API access options allow you to use automated systems to access your Data Transfer files.

    • Access the Cloud Storage UI through your browser. The URL will look like the following: http://storage.cloud.google.com/bucket_name

    • Use gsutil, a Python-based command line tool.

    • Use the Google Cloud Storage REST API.

  5. Our system scans the buckets and processes new data approximately every hour. Any files that you have uploaded are moved from the upload bucket to the log file bucket, and a log file is created with the same name and a new extension.

  6. Validate that your upload was successful and view other processing details by checking the log file bucket. If processing was successful, the new cookies will be added to the audience list and be eligible for retargeting.

    • If a list was uploaded successfully, its log file will have a .success extension.

    • If the upload was unsuccessful, the log file will have a .fail extension.

File formatting

To upload an audience list file successfully, the file name, header, and contents must meet certain criteria.

File names

The file name must contain the following information, which is used to process the file.

accountid_floodlightConfigurationid_yyyymmdd_uploadnumber.dat

Where:

  • accountid is your Campaign Manager account ID.
  • floodlightConfigurationid should reference the advertiser who owns the list.
  • yyyymmdd is the date on which the file is being uploaded.
  • uploadnumber is a unique number you must provide to differentiate individual uploads on a given day. This can be any number and does not have to be sequential, nor is the order of this value taken into account when processing the files.
  • .dat is the file extension. ZIP format (compressed files) is not currently supported.

File headers

Use the file header to establish the data format for the rest of the file. Each subsequent row must contain the same data types that you specify in the header, in the same order. All file headers must be lowercase as shown below. The following data types and keywords are supported:

  • cookie_encrypted: An alphanumeric value.
  • cookie_decimal: (Optional)Any numeral. 

  • list_id: The audience list ID where the cookie should be added.
  • timestamp: (Optional) Seconds since the beginning of the epoch.
  • delete: (Optional) Use to delete a cookie from the list. You can enter a value of 1 to represent “true” (delete) or 0 to represent “false” (do not delete). An empty string also represents a “false” value.
Every file header must include list_id and either cookie_encrypted or cookie_decimal. All other columns in the file are typically optional.

File content

The file contents consist of everything after the header. Audience list files must meet the following criteria; otherwise, they will not be processed successfully.

  • Files should follow the CSV format. In each row, the number of columns should be exactly the same as the number of columns/keywords in the header, and the values must be in the same order. If a column is missing, use a comma to indicate that column.

  • Lists may not contain duplicate cookies.

  • Each file can contain data for multiple lists, as long as they are all owned by the same advertiser. Ensure that your files contain valid list IDs.

  • The size of each list shouldn’t be more than 50 million cookies at a time. We recommend uploading multiple small files at a time, as opposed to one or two large files.

  • The rest of the values can come from your Data Transfer files and can appear in any order, as long as they match the values and ordering you set in the header.

  • You can use either the WIN or UNIX style for line breaks, but all files should use the same style.

The following is an example of a file that has been correctly formatted. The file should process successfully.

Successful upload

Header:

cookie_encrypted,list_id

File contents:

22a569d88c010015,56432
22a569d88c010017,56432
22a569d88c01001a,56433

The following is an example of an incorrectly formatted file that will not be processed successfully.

Unsuccessful upload

Header:

cookie_encrypted,list_id,timestamp

File contents:

22a569d88c010015,1234,1111
22a569d88c010017,1234,
22a569d88c01001a,1234

Note that the last line is invalid because the trailing comma is missing.

Was this helpful?
How can we improve it?