# 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.