Aller au contenu principal

Référence du connecteur TikTok Ads

info

Bêta

Cette fonctionnalité est en version bêta.

Cet article fournit des informations de référence pour le connecteur TikTok Ads, y compris les tables, dimensions et métriques prises en charge.

Tables sources prises en charge​

Le connecteur TikTok Ads prend en charge les tables sources suivantes :

Pour les tables à portée annonceur, définissez source_schema sur l'ID d'annonceur TikTok. Pour business_center, définissez source_schema sur default.

Tables prenant en charge les mises à jour incrémentielles​

Les tables de rapport suivantes prennent en charge l’ingestion incrémentielle :

  • campaign_report_daily
  • campaign_report_hourly
  • adgroup_report_daily
  • adgroup_report_hourly
  • ad_report_daily
  • ad_report_hourly
  • campaign_age_gender_report
  • campaign_country_report
  • campaign_language_report
  • campaign_platform_report
  • ad_age_gender_report
  • ad_country_report
  • ad_language_report
  • ad_platform_report
  • custom_report lorsque query_lifetime est false

Tables qui prennent en charge uniquement les mises à jour par batch (non incrémentielles)​

Les tables suivantes sont actualisées à chaque mise à jour du pipeline :

  • campaign
  • ad_group
  • ad
  • business_center
  • campaign_report_lifetime
  • adgroup_report_lifetime
  • ad_report_lifetime
  • custom_report lorsque query_lifetime est true

Rapports prédéfinis​

Les rapports prédéfinis sont des query de rapport préconfigurées avec des dimensions et des métriques fixes pour les besoins de reporting courants.

Rapport (source_table)

Dimensions

Niveau de données

Type de rapport

campaign_report_daily

campaign_id, stat_time_day

AUCTION_CAMPAIGN

BASIC

campaign_report_hourly

campaign_id, stat_time_hour

AUCTION_CAMPAIGN

BASIC

campaign_report_lifetime

campaign_id

AUCTION_CAMPAIGN

BASIC

adgroup_report_daily

adgroup_id, stat_time_day

AUCTION_ADGROUP

BASIC

adgroup_report_hourly

adgroup_id, stat_time_hour

AUCTION_ADGROUP

BASIC

adgroup_report_lifetime

adgroup_id

AUCTION_ADGROUP

BASIC

ad_report_daily

ad_id, stat_time_day

AUCTION_AD

BASIC

ad_report_hourly

ad_id, stat_time_hour

AUCTION_AD

BASIC

ad_report_lifetime

ad_id

AUCTION_AD

BASIC

campaign_age_gender_report

campaign_id, stat_time_day, age, gender

AUCTION_CAMPAIGN

AUDIENCE

campaign_country_report

campaign_id, stat_time_day, country_code

AUCTION_CAMPAIGN

AUDIENCE

campaign_language_report

campaign_id, stat_time_day, language

AUCTION_CAMPAIGN

AUDIENCE

campaign_platform_report

campaign_id, stat_time_day, platform

AUCTION_CAMPAIGN

AUDIENCE

ad_age_gender_report

ad_id, stat_time_day, age, gender

AUCTION_AD

AUDIENCE

ad_country_report

ad_id, stat_time_day, country_code

AUCTION_AD

AUDIENCE

ad_language_report

ad_id, stat_time_day, language

AUCTION_AD

AUDIENCE

ad_platform_report

ad_id, stat_time_day, platform

AUCTION_AD

AUDIENCE

Rapport (source_table)

Dimensions

Niveau de données

Type de rapport

campaign_report_daily

campaign_id, stat_time_day

AUCTION_CAMPAIGN

BASIC

campaign_report_hourly

campaign_id, stat_time_hour

AUCTION_CAMPAIGN

BASIC

campaign_report_lifetime

campaign_id

AUCTION_CAMPAIGN

BASIC

adgroup_report_daily

adgroup_id, stat_time_day

AUCTION_ADGROUP

BASIC

adgroup_report_hourly

adgroup_id, stat_time_hour

AUCTION_ADGROUP

BASIC

adgroup_report_lifetime

adgroup_id

AUCTION_ADGROUP

BASIC

ad_report_daily

ad_id, stat_time_day

AUCTION_AD

BASIC

ad_report_hourly

ad_id, stat_time_hour

AUCTION_AD

BASIC

ad_report_lifetime

ad_id

AUCTION_AD

BASIC

campaign_age_gender_report

campaign_id, stat_time_day, age, gender

AUCTION_CAMPAIGN

AUDIENCE

campaign_country_report

campaign_id, stat_time_day, country_code

AUCTION_CAMPAIGN

AUDIENCE

campaign_language_report

campaign_id, stat_time_day, language

AUCTION_CAMPAIGN

AUDIENCE

campaign_platform_report

campaign_id, stat_time_day, platform

AUCTION_CAMPAIGN

AUDIENCE

ad_age_gender_report

ad_id, stat_time_day, age, gender

AUCTION_AD

AUDIENCE

ad_country_report

ad_id, stat_time_day, country_code

AUCTION_AD

AUDIENCE

ad_language_report

ad_id, stat_time_day, language

AUCTION_AD

AUDIENCE

ad_platform_report

ad_id, stat_time_day, platform

AUCTION_AD

AUDIENCE

Groupes de métriques​

Les métriques renvoyées pour chaque rapport prédéfini dépendent de son type de rapport.

Les rapports BASIC renvoient les métriques suivantes :

Groupe

Métriques

Performances de base

spend, impressions, clicks, cpc, cpm, ctr, reach, cost_per_1000_reached, frequency

Lecture vidéo

video_play_actions, video_watched_2s, video_watched_6s, video_views_p25, video_views_p50, video_views_p75, video_views_p100, average_video_play, average_video_play_per_user

Engagement

likes, comments, shares, follows, profile_visits, profile_visits_rate

attribution

conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, total_complete_payment_rate

Événements dans l'application

app_install, cost_per_app_install, registration, cost_per_registration, purchase, cost_per_purchase, app_event_add_to_cart, cost_per_app_event_add_to_cart, checkout, cost_per_checkout

Événements de page

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

Événements TikTok Shop

product_details_page_browse, initiate_checkout, live_views, live_product_clicks

SKAdNetwork (SKAN)

skan_conversion, skan_cost_per_conversion, skan_app_install, skan_cost_per_app_install, skan_purchase, skan_cost_per_purchase, skan_registration, skan_cost_per_registration

Groupe

Métriques

Performances de base

spend, impressions, clicks, cpc, cpm, ctr, reach, cost_per_1000_reached, frequency

Lecture vidéo

video_play_actions, video_watched_2s, video_watched_6s, video_views_p25, video_views_p50, video_views_p75, video_views_p100, average_video_play, average_video_play_per_user

Engagement

likes, comments, shares, follows, profile_visits, profile_visits_rate

attribution

conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, total_complete_payment_rate

Événements dans l'application

app_install, cost_per_app_install, registration, cost_per_registration, purchase, cost_per_purchase, app_event_add_to_cart, cost_per_app_event_add_to_cart, checkout, cost_per_checkout

Événements de page

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

Événements TikTok Shop

product_details_page_browse, initiate_checkout, live_views, live_product_clicks

SKAdNetwork (SKAN)

skan_conversion, skan_cost_per_conversion, skan_app_install, skan_cost_per_app_install, skan_purchase, skan_cost_per_purchase, skan_registration, skan_cost_per_registration

Les métriques SKAdNetwork (SKAN) sont renvoyées pour les rapports BASIC quotidiens et à vie, mais pas pour les rapports horaires.

Les rapports AUDIENCE renvoient les métriques suivantes :

Groupe

Métriques

Performances de base

spend, impressions, clicks, cpm, cpc, ctr, conversion, cost_per_conversion, conversion_rate, conversion_rate_v2, frequency, reach, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, real_time_conversion_rate_v2, result, result_rate, cost_per_result, real_time_result, real_time_cost_per_result, real_time_result_rate

Événements de page

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Groupe

Métriques

Performances de base

spend, impressions, clicks, cpm, cpc, ctr, conversion, cost_per_conversion, conversion_rate, conversion_rate_v2, frequency, reach, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, real_time_conversion_rate_v2, result, result_rate, cost_per_result, real_time_result, real_time_cost_per_result, real_time_result_rate

Événements de page

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Rapports personnalisés​

En plus des rapports prédéfinis, vous pouvez créer des rapports personnalisés en définissant source_table sur custom_report dans les spécifications de votre pipeline et en fournissant custom_report_options sous connector_options.tiktok_ads_options.

JSON
{
"table": {
"source_schema": "<your-ad-account-id>",
"source_table": "custom_report",
"destination_catalog": "<destination-catalog>",
"destination_schema": "<destination-schema>",
"destination_table": "<your-report-name>",
"connector_options": {
"tiktok_ads_options": {
"lookback_window_days": 7,
"sync_start_date": "<YYYY-MM-DD>",
"custom_report_options": {
"dimensions": ["stat_time_day", "ad_id"],
"metrics": ["spend", "impressions", "clicks"],
"report_type": "BASIC",
"data_level": "AUCTION_AD",
"query_lifetime": false
}
}
}
}
}

custom_report_options champs​

Champ

Description

dimensions

Liste des dimensions à inclure (par exemple, ["stat_time_day", "ad_id"]).

metrics

Liste des champs de métrique à renvoyer.

report_type

Type de rapport : BASIC ou AUDIENCE.

data_level

Niveau d’agrégation : AUCTION_CAMPAIGN, AUCTION_ADGROUP ou AUCTION_AD.

query_lifetime

Si true, renvoie les totaux à vie sans plage de dates. default à false.

Champ

Description

dimensions

Liste des dimensions à inclure (par exemple, ["stat_time_day", "ad_id"]).

metrics

Liste des champs de métrique à renvoyer.

report_type

Type de rapport : BASIC ou AUDIENCE.

data_level

Niveau d’agrégation : AUCTION_CAMPAIGN, AUCTION_ADGROUP ou AUCTION_AD.

query_lifetime

Si true, renvoie les totaux à vie sans plage de dates. default à false.

Les rapports personnalisés ont les exigences suivantes :

  • Définissez destination_table quand source_table est custom_report. Les rapports personnalisés ne sont pas renvoyés par la découverte de tables et doivent être configurés explicitement.
  • Fournissez au moins une valeur pour dimensions et metrics.
  • Pour un rapport qui n’est pas à vie, incluez stat_time_day ou stat_time_hour dans dimensions.
  • Un rapport personnalisé sur la durée de vie est entièrement actualisé à chaque mise à jour du pipeline. Ne configurez pas sync_start_date ou lookback_window_days pour un rapport sur la durée de vie.

Options de date du rapport​

Vous pouvez configurer les options suivantes sous connector_options.tiktok_ads_options pour les rapports sans durée de vie :

Champ

Description

sync_start_date

La date initiale à ingérer, au format YYYY-MM-DD. La date ne peut pas être postérieure à aujourd’hui. Cette option n'affecte que la synchronisation initiale. Si cette option est omise, les rapports quotidiens et les rapports d’audience ingèrent les 730 jours précédents, et les rapports horaires ingèrent les 365 jours précédents.

lookback_window_days

Le nombre de jours récents à relire pendant les mises à jour incrémentielles, de 7 à 365. La valeur default est 7. La relecture de cette fenêtre capture l’attribution différée et les mesures mises à jour.

Champ

Description

sync_start_date

La date initiale à ingérer, au format YYYY-MM-DD. La date ne peut pas être postérieure à aujourd’hui. Cette option n'affecte que la synchronisation initiale. Si cette option est omise, les rapports quotidiens et les rapports d’audience ingèrent les 730 jours précédents, et les rapports horaires ingèrent les 365 jours précédents.

lookback_window_days

Le nombre de jours récents à relire pendant les mises à jour incrémentielles, de 7 à 365. La valeur default est 7. La relecture de cette fenêtre capture l’attribution différée et les mesures mises à jour.

Les dates des rapports utilisent le décalage GMT fixe du compte annonceur. Le décalage de l'annonceur TikTok ne change pas pour l'heure d'été, même lorsque le fuseau horaire du compte est représenté par un nom de région.