Видеокампании

Видеокампании позволяют показывать видеорекламу на YouTube, а также на сайтах и в приложениях партнерских видеоресурсов Google.

Ограничения API

Google Ads API в основном поддерживает получение данных и создание отчетов по существующим видеокампаниям, группам объявлений, объявлениям и критериям. Видеокампании нельзя создавать или изменять с помощью Google Ads API, за исключением следующих случаев:

• Изменяемость VideoResponsiveAdInfo. Начиная с версии v24 объекты VideoResponsiveAdInfo являются изменяемыми (в более ранних версиях они неизменяемые). При создании или изменении VideoResponsiveAdInfo необходимо заполнить поля videos, business_name и logo_images.
• Соответствие требованиям бренда. С v24 года campaign.video_brand_safety_suitability на уровне кампании больше не поддерживается. Запросите информацию о безопасности бренда на уровне аккаунта с помощью customer.video_brand_safety_suitability.
• Эксперименты с видеокампаниями. С v24 года experiment.video_experiment можно использовать для настройки экспериментов YOUTUBE_CUSTOM с видеокампаниями.

Альтернативные варианты управления кампаниями

Если вам нужно создавать видеокампании или управлять ими программно, воспользуйтесь одним из следующих вариантов:

• Скрипты Google Рекламы. Вы можете управлять видеокампаниями с помощью скриптов Google Рекламы. Это позволяет автоматизировать управление в интерфейсе Google Рекламы.
• Кампании для создания спроса. Если вы хотите показывать видеообъявления в сервисах Google, включая YouTube, то можете создавать кампании для создания спроса и управлять ими с помощью Google Ads API.

Получение данных об эффективности

Чтобы получить данные об эффективности видеокампаний, групп объявлений и критериев, используйте GoogleAdsService.SearchStream с фильтром campaign.advertising_channel_type = 'VIDEO'.

Примечание. Для показателей просмотров TrueView используйте metrics.video_trueview_views, metrics.video_trueview_view_rate и metrics.trueview_average_cpv. С v25 вы также можете выбрать segments.ad_sub_format_type (вместе с segments.ad_format_type), чтобы сегментировать объявления In-Stream без возможности пропуска по продолжительности, а также по показателям взаимодействия с видео в социальных сетях (metrics.youtube_comments, metrics.youtube_likes и metrics.youtube_shares).

Эффективность групп объявлений

Следующий запрос извлекает показатели видеокампании и группы объявлений, включая просмотры видео TrueView и долю просмотров до конца по квартилям, из ресурса ad_group:

SELECT
  campaign.id,
  campaign.name,
  campaign.advertising_channel_type,
  ad_group.id,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.video_trueview_views,
  metrics.video_quartile_p100_rate
FROM ad_group
WHERE campaign.advertising_channel_type = 'VIDEO'

Отчеты о местах размещения видео и критериях

Поскольку ad_group_criterion не поддерживает показатели и сегменты напрямую, используйте ресурсы представлений критериев, например managed_placement_view, чтобы получать показатели эффективности для целевых видео YouTube, каналов YouTube или других управляемых мест размещения.

SELECT
  campaign.id,
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.type,
  ad_group_criterion.youtube_video.video_id,
  ad_group_criterion.youtube_channel.channel_id,
  metrics.impressions,
  metrics.video_trueview_views
FROM managed_placement_view
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND ad_group_criterion.type IN ('YOUTUBE_VIDEO', 'YOUTUBE_CHANNEL')
  AND segments.date DURING LAST_30_DAYS

Отчеты об охвате и частоте показов в кампаниях

Для видеокампаний можно запрашивать показатели Unique Reach в ресурсе campaign, чтобы узнать, сколько уникальных пользователей видели вашу рекламу с определенной частотой показов.

Охват аудитории по группам частоты показов можно оценивать с помощью следующих показателей:

• metrics.unique_users – количество уникальных пользователей, которые видели ваше объявление хотя бы один раз за выбранный диапазон дат (до 92 дней). Его нельзя агрегировать по строкам.
• metrics.unique_users_two_plus–metrics.unique_users_ten_plus – количество уникальных пользователей, которые видели ваше объявление не менее 2–10 раз соответственно за период до 31 дня (в версии 26 и более поздних версиях в набор 2+ – 10+ входят также показатели metrics.unique_users_six_plus–metrics.unique_users_nine_plus).
• metrics.average_impression_frequency_per_user – среднее количество показов объявления уникальному пользователю за выбранный период (до 92 дней). Его нельзя агрегировать по строкам, и у него нет сопутствующего поля _info.

В версии 26 и более поздних у каждого показателя охвата есть сопутствующее поле метаданных типа ReachMetricInfo: metrics.unique_users_info и metrics.unique_users_two_plus_info–metrics.unique_users_ten_plus_info.

В языке запросов Google Рекламы (GAQL) поля сопутствующего охвата – это показатели MESSAGE, выбранные непосредственно в предложении SELECT (например, metrics.unique_users_info). Не добавляйте .reach_metric_states в предложение SELECT, поскольку выбор полей вложенных сообщений в GAQL приводит к ошибке UNRECOGNIZED_FIELD. Вместо этого при выборе metrics.unique_users_info возвращается сообщение ReachMetricInfo, содержащее повторяющееся поле перечисления reach_metric_states типа ReachMetricState, которое описывает, был ли показатель подавлен или завершен.

Если показатель охвата скрыт или находится за пределами окна хранения (PRIVACY_SUPPRESSION, QUALITY_SUPPRESSION или DATE_RANGE_BEYOND_RETENTION), его поле optional int64 в Metrics не задано (что соответствует 0, если наличие поля не проверяется), а LOW_QUALITY по-прежнему заполняет числовой показатель.

Значения перечисления ReachMetricState указывают на статус данных об охвате:

• COMPLETE – показатель охвата полный, без исключений, связанных с конфиденциальностью, качеством или другими ограничениями.
• PRIVACY_SUPPRESSION – данные об охвате недоступны, поскольку не достигнуты пороговые значения, связанные с требованиями конфиденциальности пользователя (например, слишком мало показов для определенной аудитории).
• QUALITY_SUPPRESSION: данные об охвате скрыты из-за проблем с качеством.
• LOW_QUALITY – показатель охвата рассчитан, но помечен как низкокачественный.
• DATE_RANGE_BEYOND_RETENTION: показатели охвата недоступны, поскольку выбранный диапазон дат превышает срок хранения данных (3 года).

Следующий запрос позволяет получить показатели охвата и их статусы подавления для видеокампании:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  segments.device,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.average_impression_frequency_per_user,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_three_plus,
  metrics.unique_users_three_plus_info,
  metrics.unique_users_four_plus,
  metrics.unique_users_four_plus_info,
  metrics.unique_users_five_plus,
  metrics.unique_users_five_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_seven_plus,
  metrics.unique_users_seven_plus_info,
  metrics.unique_users_eight_plus,
  metrics.unique_users_eight_plus_info,
  metrics.unique_users_nine_plus,
  metrics.unique_users_nine_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date BETWEEN '2026-01-01' AND '2026-01-31'

Примечание. Показатели охвата и частоты показов нельзя агрегировать по строкам. metrics.unique_users и metrics.average_impression_frequency_per_user поддерживают диапазоны дат до 92 дней и могут быть сегментированы по segments.date, segments.device, segments.adjusted_age_range и segments.adjusted_gender, а показатели группы частоты показов unique_users_*_plus (до 31 дня) и все сопутствующие поля metrics.unique_users*_info поддерживают только segments.date и segments.device. Кроме того, поля сопутствующих креативов metrics.unique_users*_info – это показатели MESSAGE с filterable: false и sortable: false, поэтому их нельзя использовать в операторах WHERE и ORDER BY. Подробнее о том, как работать с нулевыми значениями показателей охвата в отчетах…