# Reddit Ads

## Getting Started

To connect the Reddit Ads integration, follow these steps:

1. **Sign In:** A Reddit 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

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 `Reddit Ads`.                        |
| `campaign_id`       | The unique ID of the campaign.                                        |
| `campaign_name`     | The name of the campaign.                                             |
| `adgroup_id`        | The unique ID of the ad group.                                        |
| `adgroup_name`      | The name of the ad group.                                             |
| `ad_id`             | The unique ID of the ad.                                              |
| `ad_name`           | The name of the ad.                                                   |
| `utm_source`        | The source of the traffic, such as `reddit`.                          |
| `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.                         |
| `utm_term`          | The keyword associated with the campaign, if applicable.              |
| `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 `clientId` and `clientSecret` 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 including campaign and ad group details from the Reddit Ads API.
   * Campaign-level analytics are retrieved to ensure comprehensive data tracking.
3. **Analytics and Data Processing**:
   * Analytics data is merged with ad data to create a unified structure.
   * Impressions, clicks, and cost metrics are extracted and formatted.
4. **Data Formatting**:
   * The `formatData` function processes the raw data into a structured format, ensuring consistency in metadata.
5. **Data Insertion**:
   * Formatted data is stored in the metadata system using `insertToMetadata`.
   * The account’s `lastPulledDate` is updated to avoid duplicate data processing.

## Notes and Caveats

* **Token Handling**:
  * The integration uses `clientId` and `clientSecret` to authenticate all requests to the Reddit Ads API.
* **Data Splitting**:
  * Date ranges are processed in increments of up to 30 days to manage large datasets effectively.
* **Retry Logic**:
  * Failed API requests are retried up to 3 times with exponential backoff, starting at 5 seconds.