Writing Job Results into Twitter Tailored Audience

This article explains how to write job results directly to your Twitter Tailored Audience.

Table of Contents

Prerequisites

  • Basic knowledge of Treasure Data, including the toolbelt.
  • A Twitter Ads Account or an account with Ads Manager role.
  • Authorized Treasure Data Twitter app access to own Twitter Ads Account

Step 1: Create a new connection

Please visit Treasure Data Connections, search and select Twitter Tailored Audience.



The dialog below will open.



Please select an existing OAuth connection for Twitter, or click the link under OAuth connection to create a new one.



Create a new OAuth connection

Please login to your Twitter account in browser (if you haven’t logged in before) and grant access:



Or grant access to Treasure Data app when you are already logged in.



You will be redirected back to Treasure Data Connections. Please repeat the first step (Create a new connection) and choose your new OAuth connection.



You can give a name to your newly created connection and save it for later use



Step 2: Configure to output results to Twitter Tailored Audience connection

Check to Output results at top of your query editor and select your Twitter Tailored Audience connection as follows:

There are several parameters to fill out:

  • Twitter Ad Account ID (required): This is your Twitter Ad Account ID. See appendix C for getting account id.
  • Tailored Audience Name (required): Name of Tailored Audience list to create.
    • Important note: If you have many Tailored Audience lists with similar name as this input, the latest one will override. We recommend to give your Tailored Audience list a unique name.
  • Audience type (require): Type of entry in the list. It is one of email, id, device id or handle
  • Retry limit (optional, default 6): Number of retries before it gives up.
  • Initial intervals in milliseconds between retries (optional, default 10000): Interval to retry if a recoverable error happens (in millisecond).
  • Maximum intervals in milliseconds between retries (optional, default to 32000) : Maximum time in milliseconds between retrying attempts.

Here is a sample configuration:

Step 3: Write the Query to populate a tailored audience list

For the initial release, we are supporting create new Tailored Audience list

On Treasure Data console, run the following query with Output results into a connection of Twitter Tailored Audience (see Appendix A for more details of column naming):

SELECT email FROM (
  VALUES ('demo1@example.com'),
         ('demo2@example.com'),
         ('demo3@example.com')
)  tbl (email)

The above query will not match any real users, it’s solely for demo purpose only. Also, it requires no source table (for the ease of testing out this feature), but you still need to choose your database, so pick “sample_datasets” or any other arbitrary table.

The query should complete in a few seconds. After that, check the Twitter Audience Manager for your new list:

Notes that Twitter will take up to 24 hours to validate your newly created list. Hence the list will have status as “Processing”.

Status will become “Ready” (or error if the list is not valid) within the next 6 to 8 hours.

Appendix A: Tailored Audience data

Output result needs to follow Twitter Tailored List data specification here. We are currently supporting single column, single type

  • TWITTER_ID: Twitter user IDs
  • DEVICE_ID: IDFA, AdID or Android ID of Twitter users
  • EMAIL: Email addresses
  • TWITTER_HANDLE: Twitter users name aka. Screen names

Appendix B: Data Normalization

Keep it in mind that our result output normalizes your values automatically to follow Twitter’s normalizing rules, see here.

All values, uploaded to Twitter for matching, need to be normalized with the normalizing rules of Twitter. The values will just miss chances to match if they are not normalized. If you need to normalize by yourselves, apply your own normalization beforehand.

The conversion below is actually applied per type in our result output for normalization.

  • Email Addresses : Lowercase, remove leading and trailing spaces; ex: support@twitter.com
  • Twitter User Name : No @, lowercased and leading and trailing spaces trimmed; ex: jack
  • Twitter User IDs : Standard integer; ex: 143567
  • Device IDs : Lower-cased with dashes (IDFA), original format on device, not capitalized with dashes (AdID) and original format on device, not capitalized without dashes or spaces (Android ID); ex: 4b61639e-47cc-4056-a16a-c8217e02946 and af3802a465767e36

Appendix C: Twitter Ads Account info

An access to Ads Account is the pre-requisite to create the Tailored Audience List. The account ID can be retrieved from the Account Settings Page


Last modified: Jul 24 2017 17:13:50 UTC

If this article is incorrect or outdated, or omits critical information, let us know. For all other issues, access our support channels.