Twitter Ads

Getting Started

To connect the Twitter Ads integration, follow these steps:

1. Sign In: A Twitter login window will appear, sign in and proceed to the next step of granting permissions

2. Grant Permissions: Review the requested permissions, such as access to your ad accounts and campaigns. Click Allow to grant the necessary permissions.

3. Confirmation: After granting permissions, you'll be redirected back to HockeyStack

What Data Gets Tracked as Metadata

The following fields are tracked and stored during the integration process:

Field	Description
account_id_hashed	A hashed version of the account ID for secure storage.
type	The type of tracked data, such as paid-ads.
date	The date of the ad activity, formatted as YYYY-MM-DD.
id	A unique identifier for each data row, generated as an MD5 hash.
metadata	A JSON object containing detailed metadata about the campaign and ad.
account_id	The original account ID associated with the ad.
network	The advertising network, such as Twitter Ads.
campaign_id	The unique ID of the campaign.
adgroup_id	The unique ID of the ad group.
ad_id	The unique ID of the ad.
campaign_name	The name of the campaign.
adgroup_name	The name of the ad group.
ad_name	The name of the ad.
utm_source	The source of the traffic, such as twitter.
utm_campaign	The campaign name, URL-encoded if necessary.
utm_medium	The medium of the traffic, such as paid.
utm_content	Content-specific identifier for the campaign.
impressions	The total number of impressions for the ad.
clicks	The total number of clicks for the ad.
cost	The total cost of the ad campaign in the specified currency.
currency	The currency in which the ad costs are measured (e.g., USD).

High-Level Integration Flow

1. Validation:

   • We validate the accessToken and tokenSecret to ensure they are associated with an advertiser account.

   • The start of the integration process is logged for debugging and tracking purposes.

2. Ad Data Retrieval:

   • We fetch ad data using getPromotedTweets, getPromotedAccounts, and getMediaCreatives.

   • Campaigns and line items are retrieved using getCampaigns and getLineItems for comprehensive data tracking.

3. Analytics Jobs:

   • Analytics jobs are created for ad placements (e.g., ALL_ON_TWITTER and PUBLISHER_NETWORK) via startAnalyticsJob.

   • Completed analytics jobs are processed using readAsyncJobResult to gather metrics.

4. Data Formatting:

   • Analytics and ad data are formatted using formatData to create a unified structure.

   • UTM parameters, impressions, clicks, and cost metrics are included in the formatted data.

5. Data Insertion:

   • Formatted data is stored in the metadata system using insertToMetadata.

   • The account’s last processed date is updated to prevent redundant data processing.

Notes and Caveats

• Token Handling:

  • The integration uses accessToken and tokenSecret to authenticate requests.

• Data Splitting:

  • Date ranges are split into 60-day increments to manage large datasets efficiently.