Twitter Ads integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Analytic API | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ |
The Twitter Ads Analytic API is an aggregated data API provided by Twitter. It offers both synchronous and asynchronous data APIs. Because the asynchronous data API is better than the synchronous one in both analysis capabilities and data time range, the AE system supports ingesting data from the asynchronous data API.
Integration process
The process for ingesting Twitter Ads data is as follows:
-
On the Twitter platform, you need to:
- Get a Twitter Developer account, create an APP, and get the API Key and API Token
- Apply for access to the Ads API
- Create the Access Token and Access Secret of the ad account (if you created an Access Token and Access Secret before applying for the Ads API, you need to regenerate them)
-
Log in to the AE backend, go to the Third-party Integration module, add a Twitter Ads integration, and create an integration plan
-
Check whether the AE system receives the data successfully, and build reports
1. Preparation before integration
1.1 Apply for a Twitter developer account and create an APP
To call the Twitter API to get Twitter Ads data, you first need to apply for a Twitter developer account. Developer account applications are reviewed by Twitter.
After the application is approved, create an APP and write down its API Key and API Token for calling the Ads API later.
1.2 Apply for access to the Ads API
After you have a Twitter developer account and have created the APP, contact Twitter staff to enable Ads API access for your developer account. The application may take several days.
1.3 Get the Access Token and Access Secret
After Ads API access is enabled, you need to get the Access Token and Access Secret. Go back to the developer platform, click the app that has been granted Ads API access, open the Keys and tokens tab, and click the Generate button in the Access Token and Secret section to create the Access Token and Access Secret. Keep the account's Access Token and Access Secret safe. You will need them to call the Ads API later.
1.4 Summary
You need to get the following information from Twitter:
- The API Key and API Key Secret of the Twitter app
- The Access Token and Access Secret of the ad account
- The Account ID of the ad account
2. Plan configuration
After you finish preparing on the Twitter Ads platform, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of the Twitter Ads Analytic API. Follow this section to create the plan:
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information and enter the information you got from the Twitter Ads platform in the pop-up
In Account ID List, enter the IDs of the Twitter ad accounts whose data you want to pull. Separate multiple ad account IDs with ","
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull Twitter Ads Analytic API data on a schedule. You can choose to pull data for a period of time at a specific time every day or every hour. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Event Data Configuration
After you turn on the Event Data Configuration switch, all data sent back is written to the event table. We recommend that you enable event data ingestion.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable; string type. |
| source | time_granularity | Time granularity of data pulling. Options:
|
| metrics | Metric fields of the corresponding API; list type; customizable | |
| transfer | double_columns | Metrics in the data. List type. These fields are ingested as numeric values when the data is received, and the other fields are ingested as strings (or time) |
- Grouping dimensions
Twitter Ads refers to each level of ad dimension, such as Campaign and Ad Group, as an "Entity". When you call the Analytic API, only one analysis dimension is allowed. To get as much ad dimension information as possible, the AE system uses the finest granularity, PROMOTED_TWEET, as the analysis entity when pulling data, and gets information about higher-level entities, such as Campaign ID and Line Item ID, through the entity association API. The following table shows all dimension fields and their meanings:
| Dimension name | Description |
|---|---|
| account_id | Ad account ID |
| campaign_id | Campaign ID |
| campaign_name | Campaign name |
| line_item_id | Line Item ID（Ad set ID） |
| line_item_name | Line Item Name (Ad set name) |
| promoted_tweet_id | Tweet ID |
| placement | Placement |
| entity_id | Entity ID |
| currency | Currency |
- Metric fields
The Analytic API provides multiple metric groups to choose from, and each metric group covers multiple metric fields. You can customize the metric groups to pull. The following table shows the common metrics of each metric group. For information on all metrics, see the official Twitter documentation. To adjust them, add the metric group names to source.metrics and the metric field names to transfer.double_columns
| Metric group | Metric field | Description | Default |
|---|---|---|---|
ENGAGEMENT | engagements | Total engagements (including organic impressions, retweets, replies, shares, likes, and other actions) | Yes |
| impressions | Organic impressions (excluding paid promotion) | Yes | |
| retweets | Retweets | Yes | |
| replies | Replies | Yes | |
| likes | Likes | Yes | |
| follows | Follows | Yes | |
| card_engagements | Total card engagements | Yes | |
| clicks | Clicks | Yes | |
| app_clicks | App installs or app opens after clicks | Yes | |
| url_clicks | Clicks on tweet links or website cards | Yes | |
| qualified_impressions | Fully displayed impressions | Yes | |
| carousel_swipes | Swipes on carousel images or videos | Yes | |
| BILLING | billed_engagements | Billed engagements | Yes |
| billed_charge_local_micro | Total billed amount (multiplied by 1000000) | Yes | |
VIDEO | video_total_views | Video plays | Yes |
| video_views_25 | Video views at 25% progress | Yes | |
| video_views_50 | Video views at 50% progress | Yes | |
| video_views_75 | Video views at 75% progress | Yes | |
| video_views_100 | Video completions | Yes | |
| video_cta_clicks | Call-to-action clicks | Yes | |
| video_content_starts | Video content starts | Yes | |
| video_3s100pct_views | Video completions (watched for at least 3 seconds) | Yes | |
| video_6s_views | 6-second video views | Yes | |
| video_15s_views | Video views of 15 seconds or 95% progress | Yes | |
| MEDIA | media_views | Media views (including autoplay and click-to-play) | Yes |
| media_engagements | Media engagements | Yes | |
| WEB_CONVERSION | conversion_* | Conversions from conversion events of type PURCHASE, SIGN_UP, SITE_VISIT, DOWNLOAD, or CUSTOM that are followed by a payment | |
| MOBILE_CONVERSION | mobile_conversion_* | ||
| LIFE_TIME_VALUE_MOBILE_CONVERSION | mobile_conversion_lifetime_value_* |
2.5 Event ingestion rules
- The day field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
- The default event name of the data is -- twitter_ads_data
- Metric fields are ingested as numeric values, and other fields are ingested as strings
2.6 Standardized fields
The AE system standardizes some fields in Twitter Ads Analytic API data:
| Field | Standardized field | Description |
|---|---|---|
| account_id | te_ads_object.ad_account_id | Ad account ID |
| campaign_name | te_ads_object.campaign_name | Campaign name |
| campaign_id | te_ads_object.campaign_id | Campaign ID |
| line_item_name | te_ads_object.ad_group_name | Ad group name |
| line_item_id | te_ads_object.ad_group_id | Ad group ID |
| promoted_tweet_id | te_ads_object.ad_id | Ad ID |
| placement | te_ads_object.placement | Ad placement |
| currency | te_ads_object.currency | Currency of the cost or revenue |
| impressions | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| billed_charge_local_micro (divided by 1000000) | te_ads_object.cost | User acquisition cost |