Pular para o conteúdo principal

Referência do conector de anúncios do TikTok

info

Beta

Esse recurso está em Beta.

Este artigo fornece informações de referência para o conector TikTok Ads, incluindo tabelas, dimensões e detalhes suportados.

Tabelas de origem suportadas​

O conector de anúncios do TikTok é compatível com as seguintes tabelas de origem:

Para tabelas com escopo de anunciante, defina source_schema como o ID de anunciante do TikTok. Para business_center, defina source_schema como default.

Tabelas que suportam atualizações incrementais​

As seguintes tabelas de relatório suportam ingestão incremental:

  • 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 quando query_lifetime é false

Tabelas que suportam apenas atualizações de lotes (não incrementais)​

As tabelas a seguir são atualizadas a cada atualização do pipeline:

  • campaign
  • ad_group
  • ad
  • business_center
  • campaign_report_lifetime
  • adgroup_report_lifetime
  • ad_report_lifetime
  • custom_report quando query_lifetime é true

Relatórios pré-criados​

Relatórios pré-definidos são queries de relatório pré-configuradas com dimensões e métricas fixas para necessidades comuns de relatório.

Relatório (source_table)

Dimensões

Nível de dados

Tipo de relatório

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

Relatório (source_table)

Dimensões

Nível de dados

Tipo de relatório

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

grupos de mer​

As métricas retornadas para cada relatório predefinido dependem do seu tipo de relatório.

Relatórios BASIC retornam as seguintes métricas:

Grupo

Métricas

Desempenho essencial

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

Reprodução de vídeo

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

Engajamento

likes, comments, shares, follows, profile_visits, profile_visits_rate

Atribuição

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

Eventos no aplicativo

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

Eventos da página

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

Eventos do 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

Grupo

Métricas

Desempenho essencial

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

Reprodução de vídeo

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

Engajamento

likes, comments, shares, follows, profile_visits, profile_visits_rate

Atribuição

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

Eventos no aplicativo

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

Eventos da página

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

Eventos do 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

As métricas do SKAdNetwork (SKAN) são retornadas para relatórios BASIC diários e vitalícios, mas não para relatórios por hora.

Relatórios de AUDIÊNCIA retornam as seguintes métricas:

Grupo

Métricas

Desempenho essencial

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

Eventos da página

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Grupo

Métricas

Desempenho essencial

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

Eventos da página

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Relatórios personalizados​

Além dos relatórios predefinidos, você pode criar relatórios personalizados definindo source_table como custom_report na especificação do seu pipeline e fornecendo custom_report_options em 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 campos​

campo

Descrição

dimensions

Lista de dimensões a serem incluídas (por exemplo, ["stat_time_day", "ad_id"]).

metrics

Lista de campos de métrica a serem retornados.

report_type

Tipo de relatório: BASIC ou AUDIENCE.

data_level

Nível de agregação: AUCTION_CAMPAIGN, AUCTION_ADGROUP ou AUCTION_AD.

query_lifetime

Se true, retorna totais acumulados sem intervalo de datas. default to false.

campo

Descrição

dimensions

Lista de dimensões a serem incluídas (por exemplo, ["stat_time_day", "ad_id"]).

metrics

Lista de campos de métrica a serem retornados.

report_type

Tipo de relatório: BASIC ou AUDIENCE.

data_level

Nível de agregação: AUCTION_CAMPAIGN, AUCTION_ADGROUP ou AUCTION_AD.

query_lifetime

Se true, retorna totais acumulados sem intervalo de datas. default to false.

Os relatórios personalizados têm os seguintes requisitos:

  • Defina destination_table quando source_table for custom_report. Relatórios personalizados não são retornados pela descoberta de tabelas e devem ser configurados explicitamente.
  • Forneça pelo menos um valor para dimensions e metrics.
  • Para um relatório não vitalício, inclua stat_time_day ou stat_time_hour em dimensions.
  • Um relatório personalizado vitalício é completamente atualizado a cada atualização do pipeline. Não configure sync_start_date ou lookback_window_days para um relatório vitalício.

Opções de data de relatório​

Você pode configurar as seguintes opções em connector_options.tiktok_ads_options para relatórios que não são de lifetime:

campo

Descrição

sync_start_date

A data inicial a ingerir, no formato YYYY-MM-DD. A data não pode ser no futuro. Essa opção afeta apenas a sincronização inicial. Se omitido, os relatórios diários e de público ingerem os últimos 730 dias e os relatórios por hora ingerem os últimos 365 dias.

lookback_window_days

O número de dias recentes a reler durante atualizações incrementais, de 7 a 365. O default é 7. A releitura desta janela captura atribuição atrasada e métricas atualizadas.

campo

Descrição

sync_start_date

A data inicial a ingerir, no formato YYYY-MM-DD. A data não pode ser no futuro. Essa opção afeta apenas a sincronização inicial. Se omitido, os relatórios diários e de público ingerem os últimos 730 dias e os relatórios por hora ingerem os últimos 365 dias.

lookback_window_days

O número de dias recentes a reler durante atualizações incrementais, de 7 a 365. O default é 7. A releitura desta janela captura atribuição atrasada e métricas atualizadas.

As datas dos relatórios usam o deslocamento GMT fixo da account do anunciante. O deslocamento do anunciante do TikTok não muda para o horário de verão, mesmo quando o fuso horário da account é representado por um nome de região.