This document provides step-by-step instructions for integrating Twitter Ads data into Panoply. The following items will be covered:
Twitter Ads Data Integration
To integrate Twitter Ads data into Panoply using default selections, complete the following steps. For more advanced options, complete the following and refer to the subsequent sections for detailed information.
- Click Data Sources in the navigation menu.
- Click the Add Data Source button.
- In the Data Sources - Choose Source Type window, select Twitter Ads. Twitter Ads is listed under APIs.
- In the Data Sources – Twitter Ads screen, click Login with Twitter.
- After you log into Twitter, click Authorize app.
- Select the Date Range.
- Select the Collections to import.
- (Optional) To Customize the ingestion from your data source, review the advanced options.
- Click Collect.
The Data Sources – Twitter Ads window will go gray while the data integration is pending. A small green progress bar will appear below Twitter Ads once the integration has begun. Note that the Twitter Ads API may take as long as 60 minutes to retrieve the requested report(s). Also note that data may not exist for some requested reports.
A prompt will appear asking if you would like to set up the integration of another data source. Multiple data integrations can be set up without impacting the ingestion of the already scheduled or pending data integrations.
From the Data Sources main menu you can monitor the data ingestion status of the scheduled and pending data integrations. After the data ingestion is complete, you can clean or transform your data in the tables menu.
Advanced Options
Clicking Show next to Advanced will expand the Data Sources - Twitter Ads window to include Destination, Primary Key, Exclude, Parse String, and Truncate table.
Destination - Default is twitter_ads_{__collection}, where __collection is the table name from the schema for this data source.
Primary Key - Default is id, formatted as {__id}-{date}.
Data Schema
The destination tables for the Twitter Ads data source are based on these collections:
Metrics
Panoply also creates a table for each valid combination of collection and metric. The table name is formatted as {__collection-table-name}_{metric}. For example, if you are interested in the mobile conversion add to wishlists metric for the campaigns collection, you would look at the twitter_ads_campaigns_mobile_conversion_add_to_wishlists table.
This data source collects the full set of metric groups: engagement, billing, video, media, web_conversion, mobile_conversion, and life_time_value_mobile_conversion. For more information and a list of available metrics, see Metrics and Segmentation in the Twitter Ads API documentation.
Metadata
The following metadata columns are added to the destination tables:
__updatetime- When the record was last updated. Formatted as a datetime, such as 2018-09-26T01:26:14.695Z.__senttime- When the record was sent from the data source. Formatted as a datetime, such as 2018-09-26T01:26:14.695Z.
The following metadata columns are added only to the entity tables for each collection, such as the twitter_ads_campaigns table, but are not added to tables created from nested data, such as the twitter_ads_campaigns_conversion_purchases table:
__collection- The Twitter Ads collection. Possible values are:accounts,campaigns,funding_instruments,line_items,promoted_tweets, anduser_timeline.__id- Varies for each collection.
Accounts
This collection is accounts, so the default destination table is twitter_ads_accounts. You can connect subtables to this table by joining the subtables’ twitter_ads_accounts_id field on the twitter_ads_accounts table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is accounts. |
| __id | Text | Twitter account ID associated with this record. |
| date | Date | Date this data was collected in Twitter. |
| name | Text | Name associated with the Twitter account. |
Campaigns
This collection is campaigns, so the default destination table is twitter_ads_campaigns. You can connect subtables to this table by joining the subtables’ twitter_ads_campaigns_id field on the twitter_ads_campaigns table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is campaigns. |
| __id | Text | Original ID from Twitter. |
| date | Date | Date this data was collected in Twitter. |
| name | Text | Name for the campaign. |
Funding Instruments
This collection is funding_instruments, so the default destination table is twitter_ads_funding_instruments. You can connect subtables to this table by joining the subtables’ twitter_ads_funding_instruments_id field on the twitter_ads_funding_instruments table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is funding_instruments. |
| __id | Text | Funding instrument ID associated with this record. |
| date | Date | Date this data was collected in Twitter. |
| description | Text | Description of the payment method set up for this funding instrument. |
Line Items
This collection is line_items, so the default destination table is twitter_ads_line_items. You can connect subtables to this table by joining the subtables’ twitter_ads_line_items_id field on the twitter_ads_line_items table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is line_items. |
| __id | Text | Original ID from Twitter. |
| date | Date | Date this data was collected in Twitter. |
| name | Text | Name for the line item. |
Promoted Tweets
This collection is promoted_tweets, so the default destination table is twitter_ads_promoted_tweets. You can connect subtables to this table by joining the subtables’ twitter_ads_promoted_tweets_id field on the twitter_ads_promoted_tweets table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is promoted_tweets. |
| __id | Text | Identifier for the Twitter account. This specified account must be associated with the authenticated user. |
| date | Date | Date this data was collected in Twitter. |
| tweet_id | Text | Numerical ID of the promoted Tweet. |
User Timeline
This collection is user_timeline, so the default destination table is twitter_ads_user_timeline. Contains a collection of the most recent Tweets posted by the user. The timeline returned is the equivalent of the one seen as a user’s profile on Twitter. You can connect subtables to this table by joining the subtables’ twitter_ads_user_timeline_id field on the twitter_ads_user_timeline table’s id field.
| Column | Data Type | Description |
|---|---|---|
| id | Text | Primary key, formatted as {__id}-{date} |
| __collection | Text | This collection, which is user_timeline. |
| __id | Text | Original tweet ID from Twitter. |
| date | Date | Date this data was collected in Twitter. |
| created_at | Datetime | Date and time the tweet was created. |
| entities | Nested data | Hashtags, symbols, user mentions, and URLs related to this Tweet. |
| favorite_count | Number | Count of times the tweet has been favorited. |
| favorited | Boolean | Whether this tweet has been favorited. |
| is_quote_status | Boolean | Whether the tweet is a quote. |
| lang | Text | Language of the tweet. |
| possibly_sensitive | Boolean | Whether this tweet is marked as possibly sensitive. |
| retweet_count | Number | Count of times the tweet has been retweeted. |
| retweeted | Boolean | Whether this tweet has been retweeted. |
| source | Text | Origin of the tweet. |
| text | Text | Contents of the tweet. |
| truncated | Boolean | Whether the tweet was truncated due to length. |
| user | Nested data | Information about the user who posted this Tweet. |