Skip to content

Commit acb65ca

Browse files
jabahamondesgewenyu99
jabahamondes
and
gewenyu99
authored
docs: add marketing analytics column definitions and platform mappings (#14147)
* docs: add marketing analytics column definitions and platform mappings * Introduced a new document detailing column definitions for marketing analytics, including metrics and their calculations. * Updated the marketing analytics overview to link to the new column definitions. * Enhanced the navigation menu to include links to the marketing analytics overview and the new column definitions page. * Fixing typos * Update contents/docs/web-analytics/marketing-analytics-schema.mdx Co-authored-by: Vincent (Wen Yu) Ge <[email protected]> * docs: enhance marketing analytics schema with tabbed interface * Added a tabbed interface for advertising platforms (Google Ads, Meta Ads, LinkedIn Ads, Microsoft Ads, TikTok Ads, Reddit Ads) to improve navigation and organization of column definitions. * Included examples of conversion types for better clarity on PostHog and reported conversions. * Updated the document structure to accommodate the new tab components. * fix: resolve merge conflict --------- Co-authored-by: Vincent (Wen Yu) Ge <[email protected]>
1 parent 6aebfc8 commit acb65ca

File tree

4 files changed

+221
-1
lines changed

4 files changed

+221
-1
lines changed

‎contents/docs/cdp/sources/_snippets/source-meta-ads.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Additional reports will be added based on user feedback we receive via our [in-a
1515
- Your account ID from the [ads manager](https://adsmanager.facebook.com/) > Menu > Campaigns > Right next to the title you will see a dropdown > get the ID from the account or check the url `https://adsmanager.facebook.com/adsmanager/manage/campaigns?act=ID_HERE`
1616

1717
<ProductScreenshot
18-
imageLight = "https://res.cloudinary.com/dmukukwp6/image/upload/w_500,c_limit,q_auto,f_auto/Screenshot_2025_09_30_at_2_14_45_PM_ecce1881cf.png"
18+
imageLight = "https://res.cloudinary.com/dmukukwp6/image/upload/w_500,c_limit,q_auto,f_auto/Screenshot_2025_09_30_at_2_14_45_PM_ecce1881cf.png"
1919
classes="rounded"
2020
alt="Meta account ID"
2121
/>

‎contents/docs/web-analytics/marketing-analytics-schema.mdx‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
title: Marketing analytics column definitions
3+
sidebar: Docs
4+
showTitle: true
5+
availability:
6+
free: full
7+
selfServe: full
8+
enterprise: full
9+
---
10+
11+
import { Tab } from 'components/Tab'
12+
13+
This page documents the column definitions used in [marketing analytics](/docs/web-analytics/marketing-analytics), including how each metric is calculated and where the data comes from for each advertising platform.
14+
15+
## Understanding "Reported" vs PostHog conversions
16+
17+
Marketing analytics displays two types of conversion data:
18+
19+
1. **Reported conversions** - Conversion data reported directly by the ad platform (Google, Meta, LinkedIn, etc.). These use the platform's own tracking pixel and attribution model.
20+
21+
2. **PostHog conversion goals** - Conversions you define in PostHog using events, actions, or data warehouse tables. These use PostHog's events and your custom attribution rules.
22+
23+
**Examples:**
24+
25+
| Type | Example conversions |
26+
|------|---------------------|
27+
| PostHog conversion goal | Any event you track: `user signed up`, `completed checkout`, `subscribed to newsletter`, `started trial`, `upgraded plan` |
28+
| Reported (ad platform) | It can track the same! Any conversion you defined. They key difference is the source of truth. |
29+
30+
**Why does this matter?**
31+
32+
- Reported conversions may differ from PostHog conversions due to different attribution windows, tracking methods, and data freshness
33+
- Ad platforms count conversions based on their own pixel data and attribution models (e.g., 7-day click, 1-day view)
34+
- PostHog conversion goals give you flexibility to define exactly what counts as a conversion and how it's attributed
35+
- Use reported metrics to reconcile with your ad platform dashboards; use PostHog goals for custom attribution
36+
37+
## Standard columns
38+
39+
These columns are available for all platforms in the marketing analytics dashboard.
40+
41+
### Display columns
42+
43+
| Column | Description |
44+
|--------|-------------|
45+
| `Campaign` | Campaign name from the advertising platform. Matched against `utm_campaign` in your conversion events if matching field is `Campaign name`. |
46+
| `Source` | Ad platform identifier (e.g., `google`, `meta`, `linkedin`). Matched against `utm_source` in your conversion events. |
47+
| `ID` | Platform-specific campaign identifier. Matched against `utm_campaign` in your conversion events if matching field is `Campaign ID`. |
48+
49+
### Base metrics
50+
51+
| Column | Description | Higher is... |
52+
|--------|-------------|--------------|
53+
| `Impressions` | Number of times ads were displayed | Better |
54+
| `Clicks` | Number of clicks on ads | Better |
55+
| `Cost` | Total ad spend in your [base currency](/docs/web-analytics/marketing-analytics#base-currency) | Worse |
56+
| `Reported Conversion` | Number of conversions reported by the ad platform | Better |
57+
| `Reported Conversion Value` | Monetary value of conversions reported by the ad platform | Better |
58+
59+
### Calculated metrics
60+
61+
| Column | Formula | Description | Higher is... |
62+
|--------|---------|-------------|--------------|
63+
| `CPC` | `Cost / Clicks` | Cost per click - average cost for each ad click | Worse |
64+
| `CTR` | `(Clicks / Impressions) × 100` | Click-through rate - percentage of impressions that resulted in clicks | Better |
65+
| `Reported ROAS` | `Reported Conversion Value / Cost` | Return on ad spend - revenue generated per dollar spent (as reported by the platform) | Better |
66+
67+
> **Note:** All calculated metrics are rounded to 2 decimal places. Division by zero returns null.
68+
69+
## Platform field mappings
70+
71+
Each advertising platform provides data using different field names. PostHog normalizes these into the standard columns above.
72+
73+
<Tab.Group tabs={['Google Ads', 'Meta Ads', 'LinkedIn Ads', 'Microsoft Ads', 'TikTok Ads', 'Reddit Ads']}>
74+
<Tab.List>
75+
<Tab>Google Ads</Tab>
76+
<Tab>Meta Ads</Tab>
77+
<Tab>LinkedIn Ads</Tab>
78+
<Tab>Microsoft Ads</Tab>
79+
<Tab>TikTok Ads</Tab>
80+
<Tab>Reddit Ads</Tab>
81+
</Tab.List>
82+
<Tab.Panels>
83+
<Tab.Panel>
84+
85+
| PostHog Column | Google Ads Field | Notes | Platform Docs |
86+
|----------------|------------------|-------|---------------|
87+
| `Campaign` | `campaign.name` | Human-readable campaign name | |
88+
| `ID` | `campaign.id` | Unique campaign identifier | |
89+
| `Impressions` | `metrics_impressions` | | [Google Ads API - Metrics](https://developers.google.com/google-ads/api/fields/v21/metrics#metrics.impressions) |
90+
| `Clicks` | `metrics_clicks` | | [Google Ads API - Metrics](https://developers.google.com/google-ads/api/fields/v21/metrics#metrics.clicks) |
91+
| `Cost` | `metrics_cost_micros` | Divided by 1,000,000 (stored in micros). Converted from `customer_currency_code` or USD. | [Google Ads API - Metrics](https://developers.google.com/google-ads/api/fields/v21/metrics#metrics.cost_micros) |
92+
| `Reported Conversion` | `metrics_conversions` | Platform-tracked conversions | [Conversion Reporting](https://developers.google.com/google-ads/api/docs/conversions/reporting). [Google Ads API - Metrics](https://developers.google.com/google-ads/api/fields/v21/metrics#metrics.conversions) |
93+
| `Reported Conversion Value` | `metrics_conversions_value` | Monetary value of conversions | [Google Ads API - Metrics](https://developers.google.com/google-ads/api/fields/v21/metrics#metrics.conversions_value) |
94+
| Date field | `segments_date` | Used for date range filtering | |
95+
96+
**Required tables:** `campaign` and `campaign_stats`
97+
98+
</Tab.Panel>
99+
<Tab.Panel>
100+
101+
| PostHog Column | Meta Ads Field | Notes | Platform Docs |
102+
|----------------|----------------|-------|---------------|
103+
| `Campaign` | `name` | Campaign name from campaigns table | |
104+
| `ID` | `id` | Campaign ID | |
105+
| `Impressions` | `impressions` | | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/) |
106+
| `Clicks` | `clicks` | | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/) |
107+
| `Cost` | `spend` | Converted from `account_currency` if available | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/) |
108+
| `Reported Conversion` | `actions` array | Extracted by filtering for `purchase` and `omni_purchase` action types, summing `value` field | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/), [Ads action stats](https://developers.facebook.com/docs/marketing-api/reference/ads-action-stats/) |
109+
| `Reported Conversion Value` | `action_values` array | Extracted by filtering for `purchase` and `omni_purchase` action types, summing `value` field | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/), [Ads action stats](https://developers.facebook.com/docs/marketing-api/reference/ads-action-stats/) |
110+
| Date field | `date_stop` | End date of reporting period | [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/) |
111+
112+
**Required tables:** `campaigns` and `campaign_stats`
113+
114+
**Special handling:** Meta stores conversions in JSON arrays. PostHog extracts purchase-related conversions using:
115+
```sql
116+
arraySum(x -> JSONExtractFloat(x, 'value'),
117+
arrayFilter(x -> JSONExtractString(x, 'action_type') IN ('purchase', 'omni_purchase'),
118+
JSONExtractArrayRaw(actions)))
119+
```
120+
121+
</Tab.Panel>
122+
<Tab.Panel>
123+
124+
| PostHog Column | LinkedIn Ads Field | Notes | Platform Docs |
125+
|----------------|-------------------|-------|---------------|
126+
| `Campaign` | `name` | Campaign name | |
127+
| `ID` | `id` | Campaign ID | |
128+
| `Impressions` | `impressions` | | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
129+
| `Clicks` | `clicks` | | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
130+
| `Cost` | `cost_in_usd` | Already in USD, converted to base currency if different | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
131+
| `Reported Conversion` | `external_website_conversions` | Website conversions tracked by LinkedIn | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
132+
| `Reported Conversion Value` | `conversion_value_in_local_currency` | Returns 0 if field not available | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
133+
| Date field | `date_start` | Start date of reporting period | [LinkedIn Marketing API - Reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting) |
134+
135+
**Required tables:** `campaigns` and `campaign_stats`
136+
137+
</Tab.Panel>
138+
<Tab.Panel>
139+
140+
| PostHog Column | Bing Ads Field | Notes | Platform Docs |
141+
|----------------|----------------|-------|---------------|
142+
| `Campaign` | `name` | Campaign name | |
143+
| `ID` | `id` | Campaign ID | |
144+
| `Impressions` | `impressions` | | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
145+
| `Clicks` | `clicks` | | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
146+
| `Cost` | `spend` | Converted from `currency_code` if available | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
147+
| `Reported Conversion` | `conversions` | | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
148+
| `Reported Conversion Value` | `revenue` | | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
149+
| Date field | `time_period` | Reporting time period | [Microsoft Advertising API - Reports](https://learn.microsoft.com/en-us/advertising/guides/report-attributes-performance-statistics?view=bingads-13) |
150+
151+
**Required tables:** `campaigns` and `campaign_performance_report`
152+
153+
</Tab.Panel>
154+
<Tab.Panel>
155+
156+
| PostHog Column | TikTok Ads Field | Notes | Platform Docs |
157+
|----------------|-----------------|-------|---------------|
158+
| `Campaign` | `campaign_name` | Campaign name | [Basic reports doc](https://business-api.tiktok.com/portal/docs?id=1740662135093314) |
159+
| `ID` | `campaign_id` | Campaign ID | [Basic reports doc](https://business-api.tiktok.com/portal/docs?id=1740662135093314) |
160+
| `Impressions` | `impressions` | | [All TikTok Metrics](https://docs.supermetrics.com/docs/tiktok-ads-fields#field-basic-impressions) |
161+
| `Clicks` | `clicks` | | [All TikTok Metrics](https://docs.supermetrics.com/docs/tiktok-ads-fields#field-basic-clicks) |
162+
| `Cost` | `spend` | Converted from `currency` if available | [Basic reports doc](https://business-api.tiktok.com/portal/docs?id=1740662135093314) |
163+
| `Reported Conversion` | `conversion` | | [Basic reports doc](https://business-api.tiktok.com/portal/docs?id=1740662135093314) |
164+
| `Reported Conversion Value` | `total_complete_payment_rate` | Returns 0 if field not available | [All TikTok Metrics](https://docs.supermetrics.com/docs/tiktok-ads-fields#field-page-event-totalcompletepaymentrate) |
165+
| Date field | `stat_time_day` | Daily stat timestamp | |
166+
167+
**Required tables:** `campaigns` and `campaign_report`
168+
169+
</Tab.Panel>
170+
<Tab.Panel>
171+
172+
| PostHog Column | Reddit Ads Field | Notes | Platform Docs |
173+
|----------------|-----------------|-------|---------------|
174+
| `Campaign` | `name` | Campaign name | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
175+
| `ID` | `id` | Campaign ID | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
176+
| `Impressions` | `impressions` | | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
177+
| `Clicks` | `clicks` | | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
178+
| `Cost` | `spend` | **Divided by 1,000,000** (stored in micros). Converted from `currency` if available. | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
179+
| `Reported Conversion` | `key_conversion_total_count` | Total key conversions | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
180+
| `Reported Conversion Value` | `conversion_purchase_total_value` + `conversion_signup_total_value` | Sum of purchase and signup values | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
181+
| Date field | `date` | Reporting date | [Reddit Ads API](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad%20Group) |
182+
183+
**General notes:** The Reddit API docs are not very specific on the fields, so we've linked to the ad group docs where there are examples of the fields.
184+
185+
**Required tables:** `campaigns` and `campaign_report`
186+
187+
</Tab.Panel>
188+
</Tab.Panels>
189+
</Tab.Group>
190+
191+
## Currency handling
192+
193+
PostHog converts all costs to your [base currency](/docs/web-analytics/marketing-analytics#base-currency) for consistent reporting across platforms.
194+
195+
| Platform | Source Currency Field | Default Assumption |
196+
|----------|----------------------|-------------------|
197+
| Google Ads | `customer_currency_code` | USD |
198+
| Meta Ads | `account_currency` | Base currency |
199+
| LinkedIn Ads | Always USD (`cost_in_usd`) | USD |
200+
| Bing Ads | `currency_code` | Base currency |
201+
| TikTok Ads | `currency` | Base currency |
202+
| Reddit Ads | `currency` | Base currency |
203+
204+
## Related documentation
205+
206+
- [Marketing analytics overview](/docs/web-analytics/marketing-analytics)
207+
- [Setting up conversion goals](/docs/web-analytics/marketing-analytics#conversion-goals)
208+
- [Data source configuration](/docs/web-analytics/marketing-analytics#data-source-configuration)

‎contents/docs/web-analytics/marketing-analytics.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ import { ProductScreenshot } from 'components/ProductScreenshot'
1414
1515
**Marketing analytics** enables you to track marketing campaigns, costs, and performance from multiple advertising platforms in your [marketing analytics dashboard](https://app.posthog.com/web/marketing).
1616

17+
> For detailed column definitions, formulas, and platform field mappings, see [Column definitions](/docs/web-analytics/marketing-analytics-schema).
18+
1719
## Marketing dashboard
1820

1921
The marketing dashboard contains multiple pre-built insights that help you understand your campaigns and costs.

‎src/navs/index.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3343,6 +3343,16 @@ export const docsMenu = {
33433343
title: 'Beta',
33443344
className: 'uppercase !bg-blue/10 !text-blue !dark:text-white !dark:bg-blue/50',
33453345
},
3346+
children: [
3347+
{
3348+
name: 'Overview',
3349+
url: '/docs/web-analytics/marketing-analytics',
3350+
},
3351+
{
3352+
name: 'Column definitions',
3353+
url: '/docs/web-analytics/marketing-analytics-schema',
3354+
},
3355+
],
33463356
},
33473357
{
33483358
name: 'FAQ',

0 commit comments

Comments
 (0)