# StackAdapt Ads

## Getting Started

To connect the StackAdapt Ads integration, follow these steps:

1. **Sign In:** A StasckAdapt 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 `StackAdapt Ads`.                    |
| `campaign_id`         | The unique ID of the campaign.                                        |
| `campaign_group_id`   | The unique ID of the campaign group.                                  |
| `campaign_name`       | The name of the campaign.                                             |
| `campaign_group_name` | The name of the campaign 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 `stackadapt`.                      |
| `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 `apiKey` to ensure it is 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 delivery data using the `adsDelivery` query and campaign-level data using `campaignDelivery`.
   * Additional campaign insights are retrieved through the `campaignInsight` query.
3. **Analytics and Data Processing**:
   * Analytics data is merged with ad data to create a unified structure.
   * UTM parameters, 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.
   * Extracted URLs are parsed to gather UTM parameters, enhancing tracking precision.
5. **Data Insertion**:
   * Formatted data is stored in the metadata system using `insertToMetadata`.
   * The account’s `lastPulledDate` is updated to avoid duplicate data processing.

## How Impressions are Tracked

The following fields are tracked as part of the impressions tracking process:

**Action Properties**

| **Field**          | **Description**                                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `actionName`       | The name of the action, for this integration it will be `StackAdapt Ads Impressions Changed` or `StackAdapt Ads Ad Engagements Changed` |
| `actionDate`       | The date when the impression action was recorded.                                                                                       |
| `actionProperties` | Additional properties related to the action, including metrics.                                                                         |

**Company Properties**

| **Field**          | **Description**                                           |
| ------------------ | --------------------------------------------------------- |
| `company_name`     | The domain name of the company.                           |
| `company_domain`   | The domain associated with the company.                   |
| `company_industry` | The industry classification of the company, if available. |
| `company_id`       | A unique identifier for the company.                      |

**Shared Properties**

| **Field**                | **Description**                                                                  |
| ------------------------ | -------------------------------------------------------------------------------- |
| `company_id`             | Made from concatenating `stackadapt__`and the `b2bDomain` found from the results |
| `stackadapt__company_id` | Same as above                                                                    |

#### Notes and Caveats

* **Token Handling**:
  * The integration uses `apiKey` to authenticate all requests to the StackAdapt Ads API.
* **Data Splitting**:
  * Date ranges are processed in increments of up to 1 month to manage large datasets effectively.
* **Retry Logic**:
  * Failed API requests are retried up to 3 times with exponential backoff, starting at 10 seconds.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hockeystack.com/integrations/ad-platforms/stackadapt-ads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.