:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(warehouse): import tiktok click-attributed web purchases (#121321)
Javier Bahamondes90da28f5b2d6
diff --git a/docs/published/handbook/engineering/data-warehouse.md b/docs/published/handbook/engineering/data-warehouse.mdindex 689250828c87..d0dd25924220 100644--- a/docs/published/handbook/engineering/data-warehouse.md+++ b/docs/published/handbook/engineering/data-warehouse.md@@ -352,6 +352,14 @@ The CTA fields describe app conversions and purchases attributed to clicks; theyThe optional `advertiser_report` table requests daily `spend` and `cash_spend` at advertiser level.Cash spend can arrive later than other performance metrics.+TikTok Ads API v2.0 adds the optional `campaign_website_attribution_report`, `ad_group_website_attribution_report`, and `ad_website_attribution_report` tables.+Select API v2.0 on the source and enable these tables to import `cta_complete_payment` (website purchases attributed to clicks) and `cta_complete_payment_value` (their purchase value).+Existing report, audience, entity, and creative tables continue using v1.3 under either source version.+The separate tables preserve the existing ad report IDs: in v2.0, `ad_id` identifies the ad asset group for Upgraded Smart+ campaigns rather than the legacy creative.+Do not join that ID directly to legacy creative IDs for those campaigns.+Existing v1.3 pins keep their table catalog until the source version changes; no automatic repin or historical backfill runs.+The new tables use the advertiser account time zone and the same date-window, incremental, and resume behavior as other TikTok reports.+Reddit Ads requests purchase click and view counts, sign-up click counts, average purchase value, fully viewable video impressions, and viewable video impressions in its campaign, ad group, ad, and breakdown reports.The conversion window still follows the account's attribution settings.diff --git a/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py b/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.pyindex dff22c4435f4..cc8b46e584f4 100644--- a/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py+++ b/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py@@ -321,3 +321,27 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {),},}+++for report_name, dimension in {+ "campaign_website_attribution_report": "campaign_id",+ "ad_group_website_attribution_report": "adgroup_id",+ "ad_website_attribution_report": "ad_id",+}.items():+ CANONICAL_DESCRIPTIONS[report_name] = {+ "description": "Daily website purchases and purchase value, including conversions attributed to ad clicks. Requires API v2.0.",+ "docs_url": "https://business-api.tiktok.com/portal/docs/run-a-synchronous-report/v2.0",+ "columns": {+ dimension: (+ "Ad ID from Reporting API v2.0. For Upgraded Smart+ campaigns, this identifies the ad asset group rather than the legacy creative."+ if dimension == "ad_id"+ else "ID of the campaign or ad group the metrics belong to."+ ),+ "stat_time_day": "Date the metrics are aggregated for in the advertiser account time zone.",+ "spend": "Total amount spent in the reporting period.",+ "complete_payment": "Number of website purchase events attributed to the ads.",+ "total_complete_payment_rate": "Total value of website purchase events attributed to the ads.",+ "cta_complete_payment": "Number of website purchase events attributed to clicks on the ads.",+ "cta_complete_payment_value": "Total value of website purchase events attributed to clicks on the ads.",+ },+ }diff --git a/products/warehouse_sources/sources/tiktok_ads/settings.py b/products/warehouse_sources/sources/tiktok_ads/settings.pyindex 99ae130f1b08..ba10ac6a50d4 100644--- a/products/warehouse_sources/sources/tiktok_ads/settings.py+++ b/products/warehouse_sources/sources/tiktok_ads/settings.py@@ -12,7 +12,9 @@ from products.warehouse_sources.sources.sdk import ()MAX_TIKTOK_DAYS_TO_QUERY = 29-BASE_URL = "https://business-api.tiktok.com/open_api/v1.3"+TIKTOK_API_VERSION_V13 = "v1.3"+TIKTOK_API_VERSION_V2 = "v2.0"+BASE_URL = f"https://business-api.tiktok.com/open_api/{TIKTOK_API_VERSION_V13}"MAX_TIKTOK_DAYS_FOR_REPORT_ENDPOINTS = 365METRICS_FIELDS = [@@ -573,3 +575,48 @@ TIKTOK_ADS_CONFIG: dict[str, EndpointConfig] = {AD_AUDIENCE_REPORT_METRICS_FIELDS,),}+++WEBSITE_ATTRIBUTION_REPORTS = {+ "campaign_website_attribution_report": "campaign_id",+ "ad_group_website_attribution_report": "adgroup_id",+ "ad_website_attribution_report": "ad_id",+}++for report_name, dimension in WEBSITE_ATTRIBUTION_REPORTS.items():+ TIKTOK_ADS_CONFIG[report_name] = EndpointConfig(+ resource={+ "name": report_name,+ "table_name": report_name,+ "primary_key": [dimension, "stat_time_day"],+ "endpoint": {+ "path": f"https://business-api.tiktok.com/open_api/{TIKTOK_API_VERSION_V2}/report/integrated/get/",+ "method": "GET",+ "params": {+ "advertiser_ids": json.dumps(["{advertiser_id}"]),+ "dimensions": json.dumps([dimension, "stat_time_day"]),+ "metrics": json.dumps(+ [+ "spend",+ "complete_payment",+ "total_complete_payment_rate",+ "cta_complete_payment",+ "cta_complete_payment_value",+ ]+ ),+ "page_size": 1000,+ "start_date": "{start_date}",+ "end_date": "{end_date}",+ "page": 1,+ },+ "data_selector": "data.list",+ },+ "table_format": "delta",+ },+ incremental_fields=[STAT_TIME_DAY_INCREMENTAL_FIELD],+ partition_keys=["stat_time_day"],+ partition_mode="datetime",+ partition_format="week",+ endpoint_type=EndpointType.REPORT,+ should_sync_default=False,+ )diff --git a/products/warehouse_sources/sources/tiktok_ads/source.py b/products/warehouse_sources/sources/tiktok_ads/source.pyindex a4b65fcd89b7..3ce539745859 100644--- a/products/warehouse_sources/sources/tiktok_ads/source.py+++ b/products/warehouse_sources/sources/tiktok_ads/source.py@@ -26,7 +26,12 @@ from products.warehouse_sources.sources.sdk import (detect,)from products.warehouse_sources.sources.tiktok_ads._config import TikTokAdsSourceConfig-from products.warehouse_sources.sources.tiktok_ads.settings import TIKTOK_ADS_CONFIG+from products.warehouse_sources.sources.tiktok_ads.settings import (+ TIKTOK_ADS_CONFIG,+ TIKTOK_API_VERSION_V2,+ TIKTOK_API_VERSION_V13,+ WEBSITE_ATTRIBUTION_REPORTS,+)from products.warehouse_sources.sources.tiktok_ads.tiktok_ads import TikTokAdsResumeConfig, tiktok_ads_sourcefrom products.warehouse_sources.sources.tiktok_ads.utils import (TIKTOK_APP_TOKEN_MISMATCH_MESSAGE,@@ -43,6 +48,10 @@ from products.warehouse_sources.sources.tiktok_ads.utils import (list_advertisers,)+WEBSITE_ATTRIBUTION_VERSION_ERROR = (+ "Website attribution reports require TikTok Ads API v2.0. Change the source API version to v2.0."+)+@SourceRegistry.registerclass TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConfig], OAuthMixin):@@ -65,9 +74,9 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConfswiftpm=("github.com/tiktok/tiktok-business-ios-sdk",),)- supported_versions = ("v1.3",)- default_version = "v1.3"- api_docs_url = "https://business-api.tiktok.com/portal/docs"+ supported_versions = (TIKTOK_API_VERSION_V13, TIKTOK_API_VERSION_V2)+ default_version = TIKTOK_API_VERSION_V2+ api_docs_url = "https://business-api.tiktok.com/portal/docs/api-reference/v2.0"lists_tables_without_credentials = True # static endpoint catalog — safe for public docs@@ -95,6 +104,7 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConf# prefix; retrying cannot recover, so fail the job fast. The raw message is kept as# the user-facing error since it names the specific advertiser and TikTok error code.TIKTOK_NON_RETRYABLE_ERROR_PREFIX: None,+ WEBSITE_ATTRIBUTION_VERSION_ERROR: None,# Integration row was deleted/disconnected while a scheduled job still references it.# Raised by OAuthMixin.get_oauth_integration as `ValueError("Integration not found: <id>")`;# the id is volatile, so match only the stable prefix. Retrying can't recreate the row —@@ -252,7 +262,8 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConfincremental_fields=endpoint_config.incremental_fields or [],should_sync_default=endpoint_config.should_sync_default,)- for endpoint_config in TIKTOK_ADS_CONFIG.values()+ for name, endpoint_config in TIKTOK_ADS_CONFIG.items()+ if name not in WEBSITE_ATTRIBUTION_REPORTS or self.resolve_api_version(api_version) == TIKTOK_API_VERSION_V2]if names is not None:names_set = set(names)@@ -268,6 +279,12 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConfresumable_source_manager: ResumableSourceManager[TikTokAdsResumeConfig],inputs: SourceInputs,) -> SourceResponse:+ if (+ inputs.schema_name in WEBSITE_ATTRIBUTION_REPORTS+ and self.resolve_api_version(inputs.api_version) != TIKTOK_API_VERSION_V2+ ):+ raise ValueError(WEBSITE_ATTRIBUTION_VERSION_ERROR)+integration = self.get_oauth_integration(config.tiktok_integration_id, inputs.team_id)if not integration.access_token:diff --git a/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py b/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.pyindex 78ae3353b2cb..309753d0aa15 100644--- a/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py+++ b/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py@@ -1,3 +1,4 @@+import jsonfrom datetime import datetime, timedeltafrom typing import Any@@ -407,3 +408,109 @@ class TestTikTokAdsTransientErrorRetry:assert isinstance(result.raised, ValueError)assert "non-retryable" in str(result.raised)assert len(result.requests) == 1+++ ("endpoint", "dimension"),+ [+ ("campaign_website_attribution_report", "campaign_id"),+ ("ad_group_website_attribution_report", "adgroup_id"),+ ("ad_website_attribution_report", "ad_id"),+ ],+)+def test_website_attribution_reports_paginate_and_flatten(endpoint: str, dimension: str) -> None:+ day = datetime.now().strftime("%Y-%m-%d")+ result = _drive(+ endpoint,+ [+ _page_response(+ 1,+ 2,+ [+ {+ "dimensions": {dimension: "101", "stat_time_day": day},+ "metrics": {"cta_complete_payment": "2", "cta_complete_payment_value": "48.25"},+ }+ ],+ ),+ _page_response(+ 2,+ 2,+ [+ {+ "dimensions": {dimension: "102", "stat_time_day": day},+ "metrics": {"cta_complete_payment": "0", "cta_complete_payment_value": "0.00"},+ }+ ],+ ),+ ],+ api_version="v2.0",+ incremental_field="stat_time_day",+ db_incremental_field_last_value=day,+ )+ assert result.raised is None+ assert result.rows == [+ {dimension: "101", "stat_time_day": day, "cta_complete_payment": "2", "cta_complete_payment_value": "48.25"},+ {dimension: "102", "stat_time_day": day, "cta_complete_payment": "0", "cta_complete_payment_value": "0.00"},+ ]+ assert result.params("page") == ["1", "2"]+ for request in result.requests:+ assert request.url.startswith("https://business-api.tiktok.com/open_api/v2.0/report/integrated/get/")+ advertiser_ids = request.param("advertiser_ids")+ dimensions = request.param("dimensions")+ metrics = request.param("metrics")+ assert advertiser_ids is not None and dimensions is not None and metrics is not None+ assert json.loads(advertiser_ids) == [ADVERTISER_ID]+ assert json.loads(dimensions) == [dimension, "stat_time_day"]+ assert {"cta_complete_payment", "cta_complete_payment_value"} <= set(json.loads(metrics))+ assert request.param("advertiser_id") is None+ assert request.param("report_type") is None+ assert request.param("data_level") is None+ start_date, end_date = request.param("start_date"), request.param("end_date")+ assert start_date is not None and end_date is not None+ assert start_date <= day <= end_date+ assert result.saved_states[0].page == 2+++def test_website_attribution_report_rejects_legacy_pin() -> None:+ result = _drive("campaign_website_attribution_report", [], api_version="v1.3")+ assert isinstance(result.raised, ValueError)+ assert "Change the source API version to v2.0" in str(result.raised)+ assert result.requests == []++[email protected]("api_version", ["v1.3", "v2.0"])+def test_legacy_ad_reports_keep_their_request_and_identifiers(api_version: str) -> None:+ day = datetime.now().strftime("%Y-%m-%d")+ result = _drive(+ "ad_report",+ [+ _page_response(+ 1, 1, [{"dimensions": {"ad_id": "legacy-creative", "stat_time_day": day}, "metrics": {"spend": "1.00"}}]+ )+ ],+ api_version=api_version,+ incremental_field="stat_time_day",+ db_incremental_field_last_value=day,+ )+ assert result.raised is None+ assert result.rows[0]["ad_id"] == "legacy-creative"+ request = result.requests[0]+ assert request.url.startswith("https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/")+ assert request.param("advertiser_id") == ADVERTISER_ID+ assert request.param("advertiser_ids") is None+ assert request.param("report_type") == "BASIC"+ assert request.param("data_level") == "AUCTION_AD"++[email protected](("api_version", "website_reports_available"), [("v1.3", False), ("v2.0", True)])+def test_source_discovery_honors_the_version_pin(api_version: str, website_reports_available: bool) -> None:+ schemas = TikTokAdsSource().get_schemas(+ TikTokAdsSourceConfig(advertiser_id=ADVERTISER_ID, tiktok_integration_id=1),+ team_id=1,+ api_version=api_version,+ names=["campaign_report", "campaign_website_attribution_report"],+ )+ names = {schema.name for schema in schemas}+ assert "campaign_report" in names+ assert ("campaign_website_attribution_report" in names) == website_reports_available