X Ads: Setup guide
On this page
This guide explains how to collect data from Twitter Ads.
Introduction
For a list of the fields that you can collect from Twitter Ads, see Twitter Ads.
You can retrieve information for cards created through Twitter Ads API or ads.twitter.com. You cannot retrieve information for cards created through the Twitter user interface.
Limitations
Collecting data from Twitter Ads comes with the following limitations:
-
Some API endpoints are limited to a maximum date range of 90 days per request. To fetch longer periods of historical data, split your fetch into multiple 30-day date windows.
Prerequisites
Before you start collecting data from Twitter Ads, perform all of the following actions:
-
Ensure that the Twitter user who sets up the authorization has one of the following roles:
-
Ad Manager
-
Account Administrator
-
Creating a datastream to collect data from Twitter Ads
The basics of creating a datastream to collect data from any data source are explained in our guide to Collecting data in Adverity. This guide contains information about the specific steps to create a datastream to fetch data from Twitter Ads.
Configuration: Choose the data you want to collect from Twitter Ads
To choose what data to collect and customize the Twitter Ads datastream configuration, follow these steps:
-
(Optional) Rename your datastream.
-
In Accounts, select the accounts for which to collect data. You can choose to include or exclude specific items, or select all items.
-
In Report type, select the type of data to collect from Twitter Ads. The fields you need to configure in the following steps differ according to the report type you select.
-
In Level, select the type of data to collect from Twitter Ads. The configuration options below may change depending on the selected level.
-
In Metadata type, select the type of the metadata that you want to collect.
-
In Date filter, select the field that you want to use to define the fetch date range.
-
In Accounts, select the accounts to include in the report.
-
In Metrics and Dimensions, change the list of fields that you want to see in your data extract.
-
In Placement, select the ad placement type. If you do not select any items in a drop-down list, Adverity collects data for all items in the drop-down list.
-
In Granularity, select the time unit in which you want to retrieve your data.
-
Select the Include mentions and replies checkbox to collect data for mentions and replies to your tweets.
-
In Campaigns, select the campaigns for which to collect data. If you do not select any items in a drop-down list, Adverity collects data for all items in the drop-down list.
-
Select the Include inactive campaigns checkbox to include campaigns older than 90 days.
-
Select the Include empty rows checkbox to include the rows for which all metrics are zero.
-
In Segmentation, select how to segment your data.
-
Select the Media screenshots enabled checkbox to capture media screenshots.
-
In Age, select the age buckets for which to collect data.
Troubleshooting
I see a timezone error message when fetching data from Twitter Ads
The Expect time to be midnight in the account's local timezone for day granularity error message appears because you are trying to fetch data for a date range over 90 days.
To resolve this issue, fetch data for a date range shorter than 90 days.
My ad name has not been updated in the data I have collected from Twitter Ads
If you have updated the name of an ad in the Twitter Ads UI but the new name does not appear in the data collected from Twitter Ads, follow these steps to update the name:
-
Synchronize the metadata for the authorization you are using to collect the data.
-
Delete any cached tweets.
-
Wait until the update queue is empty, which means the metadata has been synchronized.
-
Fetch your data again to check that the name has been updated.
I cannot collect card data from Twitter Ads
The Twitter user who authorizes Adverity to access Twitter Ads must have an Ad Manager or Account Administrator role in order to fetch the card_name and website_card_url fields:
To collect data about these card fields, follow these steps:
-
Update the permissions of the Twitter user who used their credentials to grant the authorization to one of the following roles:
-
Ad Manager
-
Account Administrator
-
-
Update the authorization to Twitter Ads. For more information, see Updating an authorization.
-
Contact your Adverity Customer Success manager. Our Engineering Team needs to manually sync all tweet data (including card data) within the Adverity platform.
-
Collect data from Twitter Ads using the updated authorization. If these fields are still not present in your data extract, contact the Adverity Support team.
Tips and best practices
Configuring screenshot capture for Twitter Ads
To access the Twitter Ads configuration page and enable screenshot capture, follow these steps:
-
Go to the Datastreams page.
-
Open the Twitter Ads datastream by clicking on its name.
-
In the top navigation panel, click Settings.
-
In the General section of the page, fill in the following fields:
- Media Screenshots enabled
To take screenshots of your ads, select this checkbox and make sure Dimensions contains the field tweet_id.
The screenshots are saved in the same storage as the Twitter Ads data extracts.
Previewing an image
To preview an image, collect the following dimensions:
-
entities_expanded_urlsfor external links -
media_urlfor native/uploaded objects
What’s next?
-
Apply Data Mapping to your collected data to harmonize data collected from different sources in Adverity.
-
Transform your data to meet your needs by creating and applying transformations to your datastream.
-
Load your data into a warehouse to continue working with your data in Adverity.
-
Load your data into an external destination of your choice.
Advanced Twitter Ads tips
For advanced configuration and best practices, see Advanced Twitter Ads tips.