UCP 에이전트 성능 분석 (알파)

Merchant Reports API를 사용하면 Google 검색의 AI 모드 및 Gemini를 비롯한 Google 서비스 전반에서 범용 상거래 프로토콜 (UCP) 결제 및 전환 실적 측정항목을 프로그래매틱 방식으로 가져올 수 있습니다. 이러한 보고서는 판매자 센터 UCP 분석 대시보드에서 제공되는 것과 동일한 실적 통계를 제공하여 전환 유입경로, 완료된 주문, 장바구니 전송, 상품 수준 참여도를 모니터링하는 데 도움이 됩니다.

Reporting 하위 API는 UCP 실적을 분석하기 위한 두 가지 뷰를 제공합니다.

  • UcpAgenticPerformanceView(ucp_agentic_performance_view): 날짜 및 고객 국가별로 분류된 계정 수준 전환 유입경로, 주문, 취소, 장바구니 전송 측정항목을 제공합니다.
  • UcpAgenticProductPerformanceView(ucp_agentic_product_performance_view): 날짜 및 고객 국가별로 분류된 상품 수준(offer_id) 구매 버튼 클릭 측정항목을 제공합니다.

시작하기 전에

UCP 성능 뷰를 쿼리하기 전에 다음 요구사항을 충족하는지 확인하세요.

  • v1alpha 엔드포인트 사용: MCQL 쿼리를 v1alpha accounts.reports.search 메서드로 전송합니다. 보고서 요청 실행에 관한 자세한 내용은 Merchant Reports API 시작하기를 참고하세요.
  • 지원되는 계정 유형: ucp_agentic_performance_view 및 ucp_agentic_product_performance_view 모두 리프 계정 (독립형 계정 및 개별 하위 계정)과 고급 계정(멀티 클라이언트 계정 또는 애그리게이터 계정)을 지원합니다. 자세한 내용과 예시는 고급 계정 수준에서 쿼리를 참조하세요.
  • 필수 날짜 필터: 두 뷰의 모든 쿼리의 WHERE 절에서 date에 조건을 지정해야 합니다.

계정 수준 UCP 실적 분석

ucp_agentic_performance_view를 사용하여 구매 버튼 클릭, 계정 연결부터 구매 완료, 장바구니 전송에 이르기까지 전체 UCP 전환 유입경로를 추적합니다.

통화 및 가격 측정항목

ucp_agentic_performance_view는 실적 보고서와 동일한 방식으로 통화 및 Price 측정항목을 처리합니다.

  • Price 측정항목: 다음 측정항목은 amount_micros 값과 currency_code를 모두 포함하는 Price 객체를 반환합니다.
    • purchase_value
    • average_order_value
    • average_purchase_product_value
    • average_cart_value
    • average_cart_product_value
  • 가격 외 측정항목: 다음 측정항목에는 연결된 통화가 없습니다.
    • buy_button_clicks
    • accounts_linked
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. 전체 유입경로 및 개수 측정항목 (통화와 무관): 통화와 무관하게 집계 개수를 가져오려면 가격이 아닌 측정항목만 선택합니다.
  2. 구매 및 장바구니 금액 측정항목 (통화별): Price 측정항목을 해당 주문 및 장바구니 수와 함께 선택하여 통화별 수익 및 금액을 분석합니다.

쿼리 1: 전체 유입경로 측정항목 검색 (통화와 무관)

다음 쿼리를 사용하여 통화와 관계없이 전체 전환 유입경로, 주문 수, 장바구니 전송 측정항목을 가져옵니다 (Price 값 측정항목은 포함되지 않음).

SELECT
  date,
  account_id,
  customer_country_code,
  buy_button_clicks,
  accounts_linked,
  account_linking_rate,
  purchase_count,
  cancellations,
  average_purchase_product_count,
  cart_transfers,
  average_cart_product_count
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'

응답은 각 고객 국가의 집계된 유입경로 측정항목을 반환합니다.

{
  "results": [
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "accountId": "123456789",
        "customerCountryCode": "US",
        "buyButtonClicks": "420",
        "accountsLinked": "85",
        "accountLinkingRate": 0.68,
        "purchaseCount": "64",
        "cancellations": "3",
        "averagePurchaseProductCount": 1.75,
        "cartTransfers": "52",
        "averageCartProductCount": 2.1
      }
    }
  ]
}

쿼리 2: 구매 및 장바구니 금액 측정항목 가져오기 (통화별)

다음 쿼리를 사용하여 통화별로 분류된 구매 금액, 평균 주문 금액, 장바구니 이전 금액을 가져옵니다.

SELECT
  date,
  account_id,
  customer_country_code,
  purchase_count,
  purchase_value,
  average_order_value,
  average_purchase_product_count,
  average_purchase_product_value,
  average_cart_value,
  average_cart_product_value
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20' AND purchase_count > 0

응답은 구매 또는 장바구니 금액 측정항목에 있는 각 통화에 대해 별도의 행을 반환합니다.

{
  "results": [
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "accountId": "123456789",
        "customerCountryCode": "US",
        "purchaseCount": "64",
        "purchaseValue": {
          "amountMicros": "5120000000",
          "currencyCode": "USD"
        },
        "averageOrderValue": {
          "amountMicros": "80000000",
          "currencyCode": "USD"
        },
        "averagePurchaseProductCount": 1.75,
        "averagePurchaseProductValue": {
          "amountMicros": "45714285",
          "currencyCode": "USD"
        },
        "cartTransfers": "52",
        "averageCartValue": {
          "amountMicros": "94500000",
          "currencyCode": "USD"
        },
        "averageCartProductCount": 2.1,
        "averageCartProductValue": {
          "amountMicros": "45000000",
          "currencyCode": "USD"
        }
      }
    }
  ]
}

상품 수준 UCP 실적 분석

ucp_agentic_product_performance_view를 사용하여 Google 플랫폼에서 직접 구매 버튼 클릭이 발생하는 개별 제품을 확인합니다.

제품별 구매 버튼 클릭수 가져오기

다음 쿼리를 사용하여 특정 날짜의 상품 수준 구매 버튼 클릭수를 검색합니다.

SELECT
  date,
  account_id,
  customer_country_code,
  offer_id,
  title,
  buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date = '2026-09-20'

SELECT 절에서 date을 생략하여 BETWEEN를 사용하여 기간 동안의 클릭수를 집계할 수도 있습니다.

SELECT
  account_id,
  customer_country_code,
  offer_id,
  title,
  buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date BETWEEN '2026-09-01' AND '2026-09-20'
ORDER BY buy_button_clicks DESC

응답은 일치하는 각 제품에 대해 집계된 구매 버튼 클릭수를 반환합니다.

{
  "results": [
    {
      "ucpAgenticProductPerformanceView": {
        "accountId": "123456789",
        "customerCountryCode": "US",
        "offerId": "sku-10042",
        "title": "Lightweight Running Shoes - Blue / Size 10",
        "buyButtonClicks": "38"
      }
    }
  ]
}

고급 계정 수준에서 쿼리

accounts.reports.search 요청의 parent 매개변수에 고급 계정(멀티 클라이언트 계정 또는 애그리게이터 계정)을 지정하여 ucp_agentic_performance_view 및 ucp_agentic_product_performance_view를 모두 쿼리할 수 있습니다(예: accounts/{advanced_account_id}).

두 뷰 모두에서 account_id 열은 항상 리프 판매자 센터 계정 ID (고급 계정에서 쿼리할 때는 개별 하위 계정 ID, 단독 계정을 쿼리할 때는 단독 계정 ID)를 보유합니다. 고급 계정 수준에서 쿼리할 때 SELECT 절에 account_id를 포함하는지 여부에 따라 측정항목이 그룹화되는 방식이 결정됩니다.

  • account_id 생략 (고급 계정 수준에서 집계): account_id를 선택하지 않으면 응답은 고급 계정에 속한 모든 하위 계정의 측정항목을 집계합니다.
  • account_id 선택 (하위 계정별로 분류): account_id를 선택하면 응답이 리프 account_id별로 통계를 분류하여 고급 계정의 각 하위 계정에 대해 별도의 행을 반환합니다.

고급 계정에서 집계된 측정항목 가져오기

고급 계정 수준에서 롤업된 총 UCP 유입경로 측정항목을 검색하려면 고급 계정 ID를 parent 리소스로 사용하여 요청을 전송하고 SELECT 절에서 account_id를 생략합니다.

SELECT
  date,
  customer_country_code,
  buy_button_clicks,
  accounts_linked,
  account_linking_rate,
  purchase_count,
  cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'

응답은 고급 계정의 모든 하위 계정에서 날짜 및 고객 국가별로 집계된 단일 행을 반환합니다.

{
  "results": [
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "customerCountryCode": "US",
        "buyButtonClicks": "730",
        "accountsLinked": "140",
        "accountLinkingRate": 0.65,
        "purchaseCount": "110",
        "cancellations": "5"
      }
    }
  ]
}

하위 계정별로 분류된 측정항목 검색

고급 계정을 쿼리할 때 하위 계정별로 결과를 분류하려면 SELECT 절에 account_id를 포함합니다.

SELECT
  date,
  account_id,
  customer_country_code,
  buy_button_clicks,
  accounts_linked,
  account_linking_rate,
  purchase_count,
  cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'

account_id는 항상 리프 계정 ID를 보유하므로 응답은 고급 계정의 각 하위 계정에 대해 별도의 행을 반환합니다.

{
  "results": [
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "accountId": "123456789",
        "customerCountryCode": "US",
        "buyButtonClicks": "420",
        "accountsLinked": "85",
        "accountLinkingRate": 0.68,
        "purchaseCount": "64",
        "cancellations": "3"
      }
    },
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "accountId": "987654321",
        "customerCountryCode": "US",
        "buyButtonClicks": "310",
        "accountsLinked": "55",
        "accountLinkingRate": 0.61,
        "purchaseCount": "46",
        "cancellations": "2"
      }
    }
  ]
}
이전
Analyze YouTube Affiliate Performance (Alpha)
다음
Use Merchant Center Query Language