동영상 캠페인

동영상 캠페인을 사용하면 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 Ads 스크립트: Google Ads 스크립트를 사용하여 동영상 캠페인을 관리할 수 있습니다. 이를 통해 Google Ads 인터페이스 내에서 자동 관리가 가능합니다.
• 디맨드젠 캠페인: YouTube를 비롯한 Google 서비스 전반에 동영상 광고를 게재하는 것이 목표인 경우 Google Ads API에서 디맨드젠 캠페인의 생성과 관리가 모두 지원됩니다.

실적 데이터 가져오기

campaign.advertising_channel_type = 'VIDEO'를 필터링하여 GoogleAdsService.SearchStream를 사용하는 동영상 캠페인, 광고 그룹, 기준의 실적 데이터를 가져올 수 있습니다.

참고: TrueView 조회 측정항목에는 metrics.video_trueview_views, metrics.video_trueview_view_rate, metrics.trueview_average_cpv를 사용하세요. v25부터는 segments.ad_sub_format_type(segments.ad_format_type와 함께)를 선택하여 건너뛸 수 없는 인스트림 광고를 길이별로 분류하고 동영상 소셜 참여도 측정항목(metrics.youtube_comments, metrics.youtube_likes, metrics.youtube_shares)을 분류할 수도 있습니다.

광고그룹 실적

다음 쿼리는 ad_group 리소스에서 TrueView 동영상 조회수 및 사분위수 완료율을 포함한 동영상 캠페인 및 광고 그룹 측정항목을 검색합니다.

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

캠페인 도달범위 및 게재빈도 보고

동영상 캠페인의 경우 campaign 리소스에서 순 사용자 도달범위 측정항목을 쿼리하여 특정 노출 빈도로 광고가 게재된 순 사용자 수를 측정할 수 있습니다.

다음 순 사용자 측정항목은 게재빈도 버킷 전반의 잠재고객 도달범위를 측정합니다.

• metrics.unique_users: 선택한 기간 (최대 92일) 내에 광고를 한 번 이상 본 순 사용자 수입니다. 행 간에 집계할 수 없습니다.
• metrics.unique_users_two_plus~metrics.unique_users_ten_plus: 최대 31일의 기간 동안 광고를 2~10회 이상 본 순 사용자 수입니다(metrics.unique_users_six_plus~metrics.unique_users_nine_plus는 v26 이상에서 2회 이상~10회 이상 세트를 완료함).
• metrics.average_impression_frequency_per_user: 요청된 기간 (최대 92일) 동안 순 사용자가 광고를 본 평균 횟수입니다. 행 간에 집계할 수 없으며 컴패니언 _info 필드가 없습니다.

v26 이상에서 각 도달범위 측정항목에는 ReachMetricInfo: metrics.unique_users_info 및 metrics.unique_users_two_plus_info~metrics.unique_users_ten_plus_info 유형의 도우미 메타데이터 필드가 있습니다.

Google Ads Query Language (GAQL)에서 컴패니언 도달범위 필드는 SELECT 절에서 직접 선택한 MESSAGE 측정항목입니다 (예: metrics.unique_users_info). GAQL에서 중첩된 메시지 필드를 선택하면 UNRECOGNIZED_FIELD로 인해 실패하므로 SELECT 절에 .reach_metric_states를 추가하지 마세요. 대신 metrics.unique_users_info를 선택하면 ReachMetricState 유형의 반복된 enum 필드 reach_metric_states가 포함된 ReachMetricInfo 메시지가 반환됩니다. 이 메시지는 측정항목이 표시되지 않았는지 또는 완료되었는지를 설명합니다.

도달범위 측정항목이 표시되지 않거나 보관 기간(PRIVACY_SUPPRESSION, QUALITY_SUPPRESSION 또는 DATE_RANGE_BEYOND_RETENTION)을 벗어날 때마다 Metrics의 optional int64 필드가 설정되지 않습니다 (필드 존재 여부가 확인되지 않으면 0로 평가됨). 반면 LOW_QUALITY는 여전히 숫자 측정항목을 채웁니다.

ReachMetricState enum 값은 도달범위 데이터의 상태를 나타냅니다.

• COMPLETE: 도달범위 측정항목이 개인 정보 보호, 품질 또는 기타 제한으로 인해 비표시 설정되지 않고 완료되었습니다.
• PRIVACY_SUPPRESSION: 사용자 개인 정보 보호를 위해 도달범위 데이터가 표시되지 않습니다(예: 잠재고객 규모가 k-익명성 기준을 충족하지 않는 경우).
• 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 필드는 filterable: false 및 sortable: false가 있는 MESSAGE 측정항목이므로 WHERE 또는 ORDER BY 절에서 사용할 수 없습니다. 보고서에서 제외된 도달범위 측정항목을 처리하는 방법에 대한 자세한 내용은 도달범위 측정항목 제외 및 0 값을 참조하세요.