TikTok Ads
TikTok Ads отдаёт рекламную статистику на уровне отдельных объявлений. Отчёт вы собираете сами из измерений и метрик: расход и стоимостные метрики, показы и клики, конверсии и результаты, просмотры видео по глубине досмотра, платные события вовлечения и статистика Instant Experience. Renta выгружает этот отчёт в ваше хранилище данных.
Второй тип отчёта, Account metadata, загружает профиль каждого подключённого рекламного аккаунта: название, статус, баланс, валюту, часовой пояс и контактные данные.
Аутентификация
Renta использует OAuth для аутентификации в TikTok Ads. Вы будете перенаправлены в TikTok for Business, чтобы предоставить Renta ограниченный доступ к рекламным аккаунтам.
Подключение источника TikTok Ads
- Перейдите в раздел Connections > Catalog в левом меню.
- Откройте категорию Advertising и нажмите карточку TikTok Ads.
Нажмите Log in to your Tiktok Ads account. Вы будете перенаправлены в TikTok for Business для предоставления доступа.
TikTok for Business показывает разрешения, которые запрашивает Renta: Ad Account Management, Reporting, Pixel Management и TikTok Accounts. Нажмите Confirm. TikTok может дополнительно попросить подтвердить личность кодом, отправленным на email вашего аккаунта TikTok. После этого вы вернётесь в Renta.
Завершите настройку:
- Source name.
Укажите название источника данных. Оно используется только в интерфейсе Renta. - Access granted.
Убедитесь, что аккаунт подключён успешно.
Нажмите Save, чтобы завершить.
Новый источник появится в списке Sources со статусом Active. Теперь его можно использовать в пайплайнах.
Создание пайплайна TikTok Ads
После подключения источника создайте пайплайн, чтобы синхронизировать данные TikTok Ads с вашим назначением.
В левом меню нажмите New pipeline. На шаге Source выберите TikTok Ads в списке Already connected и нажмите Next step.
Выберите созданное ранее подключение TikTok Ads и нажмите Next step.
На шаге Destination выберите ваше назначение (например, Google BigQuery) и нажмите Next step.
Выберите подключение назначения, в которое нужно загружать данные, и нажмите Next step.
Настройка пайплайна
На финальном шаге выберите, какие данные TikTok Ads выгружать и как Renta будет их загружать.
Настройка отчёта
Укажите рекламные аккаунты, из которых нужны данные.
- Ad accounts.
Выберите один или несколько аккаунтов TikTok Ads, из которых выгружать данные. Список показывает рекламные аккаунты, доступные авторизов анному пользователю TikTok for Business. Renta загружает строки всех выбранных аккаунтов в одну таблицу назначения. - Report Types.
Выберите, что выгружает пайплайн.
| Тип отчёта | Описание |
|---|---|
| Statistics report | Рекламная статистика на уровне объявлений, которую вы собираете из измерений и метрик. Это тип отчёта по умолчанию. |
| Account metadata | Профиль каждого выбранного рекламного аккаунта: название, статус, баланс, валюта, часовой пояс и контактные данные. |
Параметры
Выберите поля TikTok Ads, которые попадут в таблицу назначения. Выбранные здесь параметры определяют схему таблицы.
| Название | Имя в API | Описание |
|---|---|---|
Advertiser ID text | advertiser_id | Group by Advertiser account ID |
Campaign ID text | campaign_id | Group by Campaign ID |
Ad group ID text | adgroup_id | Group by Ad group ID |
Ad ID text | ad_id | Group by Ad ID |
Date date | stat_time_day | Group by day |
Name text | advertiser_name | Group by Advertiser account name |
Campaign name text | campaign_name | Group by Campaign name |
Objective text | objective_type | Group by Advertising objective |
Split Test Status text | split_test | Group by Split test status |
Campaign Budget text | campaign_budget | Group by Campaign budget |
iOS dedicated campaign text | campaign_dedicate_type | Group by Campaign type. iOS14 Dedicated Campaign or regular campaign. |
App promotion type text | app_promotion_type | Group by App promotion type. Enum values: APP_INSTALL, APP_RETARGETING. |
Ad Group Name text | adgroup_name | Group by Ad group name |
Placements Types text | placement_type | Group by Placement type |
Promotion Type text | promotion_type | Group by Promotion type. It can be app, website, or others. |
On/Off text | opt_status | Group by Automated creative optimization status |
Website URL text | adgroup_download_url | Group by Download URL/Website URL |
Profile Image text | profile_image | Group by Profile image |
Catalog Sales Audience text | dpa_target_audience_type | Group by Target audience type for DPA |
Ad Group Budget text | budget | Group by Ad group budget |
Optimization Goal text | smart_target | Group by Optimization goal |
| Название | Имя в API | Описание |
|---|---|---|
Cost float | spend | Sum of your total ad spend. |
CPC (Destination) float | cpc | Average cost of each click to a specified destination. |
CPM float | cpm | Average amount you spent per 1,000 impressions. |
Impression int | impressions | Number of times your ads were shown. |
Gross Impressions (Includes Invalid Impressions) int | gross_impressions | Number of times your ads were shown, including invalid impressions. |
Clicks (Destination) int | clicks | Number of clicks from your ads to a specified destination. |
CTR (Destination) float | ctr | Percentage of impressions that resulted in a destination click out of all impressions. |
Reach int | reach | Number of unique users who saw your ads at least once. |
Cost per 1,000 People Reached float | cost_per_1000_reached | Average cost to reach 1,000 unique users. |
Frequency float | frequency | The average number of times each user saw your ad over a given time period. |
Conversions int | conversion | Number of times your ad resulted in the optimization event you selected. |
CPA float | cost_per_conversion | Average amount spent on a conversion. |
CVR (Impressions) float | conversion_rate_v2 | Percentage of results you received out of all impressions on your ads. |
Real-time Conversions int | real_time_conversion | Number of times your ad resulted in the optimization event you selected. |
Real-time CPA float | real_time_cost_per_conversion | Average amount spent on a conversion. |
Real-time CVR (Impressions) float | real_time_conversion_rate_v2 | Percentage of conversions you received out of all impressions on your ads. |
Results int | result | Number of times your ad resulted in an intended outcome based on your campaign objective and optimization goal. |
Cost Per Results float | cost_per_result | Average cost per each result from your ads. |
Results Rate float | result_rate | Percentage of results that happened out of all impressions on your ads. |
Real-time Results int | real_time_result | Number of times your ad resulted in an intended outcome based on your campaign objective and optimization goal. |
Real-time Cost Per Results float | real_time_cost_per_result | Average cost per each result from your ads. |
Real-time Results Rate float | real_time_result_rate | Percentage of results that happened out of all impressions on your ads. |
Secondary Goal Result text | secondary_goal_result | Number of times your ad resulted in an intended outcome based on the secondary goal you selected. |
Cost per Secondary Goal Result text | cost_per_secondary_goal_result | Average cost per each secondary goal result from your ads. |
Secondary Goal Result Rate (%) text | secondary_goal_result_rate | Percentage of secondary goal results that happened out of all impressions on your ads. |
Video views int | video_play_actions | Number of times your video started to play. For each video impression, plays are counted separately and replays are excluded. |
2-Second Video Views int | video_watched_2s | Number of times your video was played for at least 2 seconds. For each video impression, plays are counted separately and replays are excluded. |
6-Second Video Views int | video_watched_6s | Number of times your video was played for at least 6 seconds. For each video impression, plays are counted separately and replays are excluded. |
6-second views (Focused view) int | engaged_view | Number of times your video was played for at least 6 seconds, played in full if it is less than 6 seconds, or received at least 1 engagement within the first 6 seconds. |
15-second views (Focused view) int | engaged_view_15s | Number of times your video was played for at least 15 seconds, played in full if it is less than 15 seconds, or received at least 1 engagement within the first 15 seconds. |
Video Views at 25% int | video_views_p25 | Number of times your video was played at least 25% of its length. For each impression, views are counted separately and replays are excluded. |
Video Views at 50% int | video_views_p50 | Number of times your video was played at least 50% of its length. For each impression, views are counted separately and replays are excluded. |
Video Views at 75% int | video_views_p75 | Number of times your video was played at least 75% of its length. For each impression, views are counted separately and replays are excluded. |
Video Views at 100% int | video_views_p100 | Number of times your video was played 100% of its length. For each impression, views are counted separately and replays are excluded. |
Average Watch Time per Video View float | average_video_play | Average time your video was played per single video view, including any time spent replaying the video. |
Average Watch Time per Person float | average_video_play_per_user | Average time your video was played per user, including any time spent replaying the video. |
Clicks (All) int | engagements | Number of clicks from your ads. This includes clicks that lead to destination as well as those for social and interaction purposes. |
CTR (All) int | engagement_rate | Percentage of impressions that resulted in a click out of all impressions. |
Paid Followers int | follows | Number of follows to the associated profile during the ad impression. |
Paid Likes int | likes | Number of times your ad was liked during the ad impression. |
Paid Comments int | comments | Number of comments sent on your ad during the ad impression. |
Paid Shares int | shares | Number of shares of your ad during the ad impression. |
Paid Profile Visits int | profile_visits | Number of visits to the associated profile during the ad impression. |
Paid Profile Visit Rate float | profile_visits_rate | Percentage of profile visits from ads out of all impressions on your ads. |
Clicks on Music Disc int | clicks_on_music_disc | Number of clicks on the sound associated with your ad during the ad impression. |
Duet Clicks int | duet_clicks | Number of clicks on the "Duet" button. |
Stitch Clicks int | stitch_clicks | Number of clicks on the "Stitch" button. |
Sound Usage Clicks int | sound_usage_clicks | Number of clicks on the "Use sound" button. |
Anchor Clicks int | anchor_clicks | Number of clicks on ad anchors. |
Anchor Clicks Rate int | anchor_click_rate | Percentage of anchor clicks out of all impressions on your ads. |
Clicks on hashtag challenge int | clicks_on_hashtag_challenge | Number of clicks on the hashtag challenge associated with your ad during the ad impression. |
Instant Experience Average View Time float | ix_page_duration_avg | Average time your Instant Experience was shown. |
Instant Experience Average View Percentage float | ix_page_viewrate_avg | Average percentage of content on your Instant Experience that was viewed. |
Instant Experience Video Component Views int | ix_video_views | Number of times your Instant Experience video was played. Replays are excluded. |
Instant Experience Video Component Views at 25% int | ix_video_views_p25 | Number of times your Instant Experience video was played at least 25% of its length. Replays are excluded. |
Instant Experience Video Component Views at 50% int | ix_video_views_p50 | Number of times your Instant Experience video was played at least 50% of its length. Replays are excluded. |
Instant Experience Video Component Views at 75% int | ix_video_views_p75 | Number of times your Instant Experience video was played at least 75% of its length. Replays are excluded. |
Instant Experience Video Component Views at 100% int | ix_video_views_p100 | Number of times your Instant Experience video was played 100% of its length. Replays are excluded. |
Instant Experience Video Component Views int | ix_average_video_play | Average time your instant experience video was played in a single video view, including any time spent replaying the video. |
Playlist page visits int | tt_playlist_visit | The number of playlist page visits the paid ad drove during the campaign. |
Playlist page visit rate float | tt_playlist_visit_rate | The rate of playlist page visits per impression the paid ad drove during the campaign. |
| Название | Имя в API | Описание |
|---|---|---|
Address text | address | Address of the advertiser |
Advertiser Account Type text | advertiser_account_type | Type of advertiser account (e.g., AUCTION) |
Advertiser ID text | advertiser_id | Group by Advertiser account ID |
Balance float | balance | Account balance |
Brand text | brand | Brand name if provided |
Cellphone Number text | cellphone_number | Contact cellphone number |
Company text | company | Name of the company |
Contacter text | contacter | Contact person for the account |
Country text | country | Country code (ISO format) |
Create Time datetime | create_time | Account creation timestamp (UNIX) |
Currency text | currency | Default currency of the account |
Description text | description | Description or website URL |
Display Timezone text | display_timezone | Display timezone for the account |
Email text | email | Email address associated with the account |
Industry text | industry | Industry code of the advertiser |
Language text | language | Preferred language setting |
License City text | license_city | City where business license is registered |
License Number text | license_no | Business license number |
License Province text | license_province | Province where business license is registered |
License URL text | license_url | URL to the business license |
Account Name text | name | Display name of the advertiser account |
Owner BC ID text | owner_bc_id | Business center ID of the account owner |
Promotion Area text | promotion_area | Promotion area setting |
Promotion Center City text | promotion_center_city | Promotion center city |
Promotion Center Province text | promotion_center_province | Promotion center province |
Rejection Reason text | rejection_reason | Reason for account rejection, if any |
Role text | role | Role of the advertiser account (e.g., ROLE_CHILD_ADVERTISER) |
Status text | status | Current status of the advertiser account |
Telephone Number text | telephone_number | Landline telephone number |
Timezone text | timezone | Timezone in GMT format |
На вкладке Dimensions отметьте поля, описывающие объявление за каждой строкой: Date, идентификатор и название рекламного аккаунта, идентификатор, название, бюджет и цель кампании, идентификатор, название и бюджет группы объявлений, идентификатор объявления, тип плейсмента, тип продвижения и цель оптимизации.
На вкладке Metrics отметьте показатели для выгрузки: расход, CPC, CPM и CPA, показы и клики, охват и частоту, конверсии и результаты вместе с их real-time вариантами, просмотры видео по глубине досмотра, платных подписчиков, лайки, комментарии и репосты, визиты в профиль, клики по музыкальному диску, кнопкам Duet и Stitch, статистику Instant Experience и визиты в плейлисты.
Какие бы измерения вы ни выбрали, статистика остаётся на уровне отдельных объявлений. Поля вроде названия кампании или группы объявлений описывают объекты, к которым объявление относится.
Для отчёта Account metadata пикер содержит только измерения: название и статус аккаунта, баланс и валюту, часовой пояс, страну, компанию и контактные данные, а также атрибуты бизнес-лицензии. В таблицу назначения попадает одна строка на каждый выбранный рекламный аккаунт.
Название таблицы
Назовите пайплайн и таблицу назначения.
- Integration name.
Название пайплайна. Используется только в интерфейсе Renta. - Table name.
Название таблицы назначения. Можно оставить автоматически сгенерированное название или задать своё.
Диапазон дат
Задайте исторический период загрузки.
- Date start.
Первая дата периода выгрузки. - Date end.
Последняя дата периода выгрузки. Оставьте Today, чтобы собирать новые данные при каждом запуске.
TikTok Ads строит каждый отчёт асинхронно. Renta создаёт задачу на отчёт, ждёт, пока TikTok её выполнит, и скачивает результат. Запросы разбиваются на окна до 30 дней на каждый рекламный аккаунт, поэтому широкий исторический диапазон загружается дольше, чем несколько дней.
Период перезаписи
Период перезаписи определяет, сколько последних дней Renta перезагружает при каждом запуске.
При каждом запуске Renta заново запрашивает отчёт начиная с даты последнего успешного запуска минус период перезаписи. Затронутые дни удаляются из таблицы назначения и вставляются заново, более старые данные не меняются. Варианты: от Without overwrite data до Overwrite all data. По умолчанию выбран Last 3 days.
Расписание
Выберите, как часто запускается пайплайн.
| Тип расписания | Описание |
|---|---|
| Manual | Пайплайн запускается только вручную через интерфейс или по API. |
| Daily | Пайплайн запускается раз в день в указанное время обновления. |
| Interval | Пайплайн запускается через заданные интервалы времени. |
| Cron Expression | Пайплайн запускается по расписанию, заданному cron-выражением. |
Для расписания Daily укажите Update time (точное время запуска), затем нажмите Create pipeline.
Новый пайплайн появится в разделе Pipelines на вкладке ETL, где можно отслеживать запуски, прогресс и название таблицы назначения.
Стратегия синхронизации
Стратегия синхронизации зависит от типа отчёта и от того, включено ли в отчёт измерение Date.
| Стратегия | Поддерживаемые типы отчётов | Описание |
|---|---|---|
| Инкрементальное обновление | Statistics report (с выбранным измерением Date) | Каждая строка соответствует одному дню, таблица назначения партиционируется по колонке stat_time_day. При каждом запуске Renta перезагружает окно от последнего успешного запуска минус период перезаписи до конца диапазона дат: эти дневные партиции удаляются и вставляются заново, более старые партиции не меняются. |
| Полная перезагрузка | Statistics report (без измерения Date) | В таблице нет колонки даты для партиционирования, поэтому Renta запрашивает весь настроенный диапазон дат и заменяет данные при каждом запуске. |
| Полная перезагрузка | Account metadata | В отчёте нет колонки даты, поэтому Renta при каждом запуске перезагружает текущее состояние каждого выбранного рекламного аккаунта. |
Ready to get started?
Build your data pipeline today or get a personalized demo. Start free!
Need help?
Get expert support to ensure your project succeeds. We're here to help!
Feature requests?
Help shape our product! Share your ideas for new features and integrations.