Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

전환 관리

Google Ads에서 전환은 광고 상호작용 후 발생하는 가치 있는 사용자 액션(예: 제품 구매, 리드 양식 제출, 비즈니스에 전화 걸기, 오프라인 상점 방문)입니다. 전환 추적은 이러한 고객 상호작용을 측정하므로 캠페인 실적을 평가하고 자동 입찰을 최적화할 수 있습니다.

Google Ads API를 사용하면 프로그래매틱 방식으로 전환 액션을 구성하고, 오프라인 전환 이벤트를 가져오고, 기록된 전환을 개선하거나 조정하고, 액션을 입찰 및 라이프사이클 목표로 그룹화하고, 업로드 진단을 모니터링할 수 있습니다.

변환 워크플로 선택

다음 표를 사용하여 사용 사례에 맞는 ConversionActionType, API 서비스, 구현 가이드를 확인하세요.

작업	전환 액션 유형	API 서비스 또는 리소스	구현 가이드
계정 설정 확인 및 전환 액션 만들기	`UPLOAD_CLICKS`, `WEBPAGE`, `UPLOAD_CALLS`, `AD_CALL`, `WEBSITE_CALL`, `GOOGLE_PLAY_DOWNLOAD`, `GOOGLE_PLAY_IN_APP_PURCHASE`	`Customer` (`ConversionTrackingSetting`), `ConversionActionService`	시작하기 및 전환 액션 카테고리
오프라인 클릭 전환 또는 리드 확보용 향상된 전환 가져오기	`UPLOAD_CLICKS`	`ConversionUploadService.UploadClickConversions` (또는 새 통합의 경우 Data Manager API)	오프라인 클릭 전환 가져오기
온라인 전환 개선 (웹용 향상된 전환)	`WEBPAGE`	`ConversionAdjustmentUploadService.UploadConversionAdjustments` (`ENHANCEMENT`)	온라인 클릭 전환 가져오기
전화 통화 전환 가져오기	`UPLOAD_CALLS`	`ConversionUploadService.UploadCallConversions`	통화 전환 가져오기
매장 판매 거래 가져오기	`STORE_SALES`, `STORE_SALES_DIRECT_UPLOAD`	`OfflineUserDataJobService`(또는 Data Manager API)	매장 판매 전환 가져오기
기록된 전환 철회 또는 재조정	`UPLOAD_CLICKS`, `WEBPAGE`, `SALESFORCE` (지원 중단됨)	`ConversionAdjustmentUploadService.UploadConversionAdjustments` (`RETRACTION`, `RESTATEMENT`)	가져오기 후 전환 조정
전환에 맞춤 태그 메타데이터 연결	`UPLOAD_CLICKS`, `UPLOAD_CALLS`, `WEBPAGE`	`ConversionCustomVariableService`	맞춤 전환 변수
입찰 목표, 라이프사이클 목표, 가치 규칙 구성	계정, 캠페인, 라이프사이클 목표	`CustomerConversionGoalService`, `CampaignConversionGoalService`, `CustomConversionGoalService`, `ConversionGoalCampaignConfigService`, `GoalService`, `CampaignGoalConfigService`, `ConversionValueRuleService`	전환 목표, 라이프사이클 목표, 전환 가치 규칙
가져오기 상태 및 오류 진단 모니터링	`UPLOAD_CLICKS`, `WEBPAGE`, `UPLOAD_CALLS`	`offline_conversion_upload_client_summary`, `offline_conversion_upload_conversion_action_summary`	오프라인 데이터 진단 모니터링하기
전환 측정항목 쿼리 및 오류 문제 해결	모든 전환 유형	`GoogleAdsService.SearchStream` (`customer`, `campaign`, `conversion_action`)	전환 통계 가져오기 및 전환 가져오기 문제 해결

엔드 투 엔드 전환 수명 주기

Google Ads API의 완전한 전환 관리 통합은 다음 네 단계로 이루어집니다.

계정 설정 확인 및 전환 액션 만들기: Customer.conversion_tracking_setting를 쿼리하여 유효한 전환 계정(google_ads_conversion_customer)을 확인하고, 전환 추적이 활성 상태인지 확인하고, 사용자 동의를 구성하고, 타겟 ConversionActionType 및 ConversionActionCategory를 사용하여 ConversionAction를 만듭니다.
전환 이벤트 가져오기: partial_failure가 true로 설정된 ConversionUploadService를 사용하여 오프라인 클릭 또는 통화 전환을 스트리밍하거나, ConversionAdjustmentUploadService를 사용하여 ENHANCEMENT 조정으로 웹사이트 전환을 보완하거나, OfflineUserDataJobService를 사용하여 매장 판매를 일괄 업로드합니다.
전환 조정 및 최적화: ConversionAdjustmentUploadService를 사용하여 기록된 전환을 철회하거나 재조정하고, ConversionCustomVariable 메타데이터를 연결하고, 전환 가치 규칙을 적용하고, 액션을 전환 목표 및 라이프사이클 목표로 구성하여 입찰 최적화를 제어합니다.
진단 모니터링 및 실적 보고: offline_conversion_upload_client_summary 및 offline_conversion_upload_conversion_action_summary를 쿼리하여 업로드 처리 상태 및 부분 실패 알림을 검사합니다. customer 또는 campaign 리소스(선택적으로 segments.conversion_action로 분류됨)를 쿼리하여 metrics.conversions 및 metrics.all_conversions 측정항목을 비교하거나 conversion_action 리소스를 쿼리하여 metrics.all_conversions 및 마지막 전환 타임스탬프를 검사합니다.

빠른 시작: 설정 확인, 작업 만들기, 상태 확인

다음 예는 전환 추적을 초기화하고 모니터링하는 데 필요한 가장 일반적인 세 가지 쿼리와 변형을 보여줍니다.

1. GAQL로 전환 추적 설정 확인

ConversionAction를 만들거나 이벤트를 업로드하기 전에 GoogleAdsService.SearchStream를 사용하여 customer 리소스를 쿼리하여 전환을 관리하는 계정 (google_ads_conversion_customer), 고객 데이터 약관에 동의했는지 여부, 계정 수준 향상된 전환이 사용 설정되어 있는지 여부(EnhancedConversionsConfig)를 확인합니다.

SELECT
  customer.conversion_tracking_setting.conversion_tracking_id,
  customer.conversion_tracking_setting.conversion_tracking_status,
  customer.conversion_tracking_setting.cross_account_conversion_tracking_id,
  customer.conversion_tracking_setting.google_ads_conversion_customer,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enablement_setting,
  customer.conversion_tracking_setting.effective_enablement_setting
FROM customer

google_ads_conversion_customer에서 반환된 customers/{customer_id} 리소스 이름에서 {customer_id}를 추출하고 해당 고객 ID에 대해 모든 후속 ConversionActionService 및 ConversionUploadService 요청을 실행합니다. 전체 설정 및 교차 계정 계층 구조 세부정보는 시작하기를 참조하세요.

2. 전환 액션 만들기

ConversionActionService.MutateConversionActions를 사용하여 ConversionAction를 만듭니다. 다음 예에서는 커스텀 가치 및 전환 확인 기간 설정으로 UPLOAD_CLICKS 전환 액션을 만듭니다.

자바

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {

  // Creates a ConversionAction.
  ConversionAction conversionAction =
      ConversionAction.newBuilder()
          // Note that conversion action names must be unique. If a conversion action already
          // exists with the specified conversion_action_name the create operation will fail with
          // a ConversionActionError.DUPLICATE_NAME error.
          .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime())
          .setCategory(ConversionActionCategory.DEFAULT)
          .setType(ConversionActionType.WEBPAGE)
          .setStatus(ConversionActionStatus.ENABLED)
          .setViewThroughLookbackWindowDays(15L)
          .setValueSettings(
              ValueSettings.newBuilder()
                  .setDefaultValue(23.41)
                  .setAlwaysUseDefaultValue(true)
                  .build())
          .build();

  // Creates the operation.
  ConversionActionOperation operation =
      ConversionActionOperation.newBuilder().setCreate(conversionAction).build();

  try (ConversionActionServiceClient conversionActionServiceClient =
      googleAdsClient.getLatestVersion().createConversionActionServiceClient()) {
    MutateConversionActionsResponse response =
        conversionActionServiceClient.mutateConversionActions(
            Long.toString(customerId), Collections.singletonList(operation));
    System.out.printf("Added %d conversion actions:%n", response.getResultsCount());
    for (MutateConversionActionResult result : response.getResultsList()) {
      System.out.printf(
          "New conversion action added with resource name: '%s'%n", result.getResourceName());
    }
  }
}AddConversionAction.java

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V26.ConversionActionService);

    // Note that conversion action names must be unique.
    // If a conversion action already exists with the specified name the create operation
    // will fail with a ConversionAction.DUPLICATE_NAME error.
    string ConversionActionName = "Earth to Mars Cruises Conversion #"
        + ExampleUtilities.GetRandomString();

    // Add a conversion action.
    ConversionAction conversionAction = new ConversionAction()
    {
        Name = ConversionActionName,
        Category = ConversionActionCategory.Default,
        Type = ConversionActionType.Webpage,
        Status = ConversionActionStatus.Enabled,
        ViewThroughLookbackWindowDays = 15,
        ValueSettings = new ConversionAction.Types.ValueSettings()
        {
            DefaultValue = 23.41,
            AlwaysUseDefaultValue = true
        }
    };

    // Create the operation.
    ConversionActionOperation operation = new ConversionActionOperation()
    {
        Create = conversionAction
    };

    try
    {
        // Create the conversion action.
        MutateConversionActionsResponse response =
            conversionActionService.MutateConversionActions(customerId.ToString(),
                    new ConversionActionOperation[] { operation });

        // Display the results.
        foreach (MutateConversionActionResult newConversionAction in response.Results)
        {
            Console.WriteLine($"New conversion action with resource name = " +
                $"'{newConversionAction.ResourceName}' was added.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}AddConversionAction.cs

PHP

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
    {
        // Creates a conversion action.
        $conversionAction = new ConversionAction(
            [
            // Note that conversion action names must be unique.
            // If a conversion action already exists with the specified conversion_action_name
            // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error.
            'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
            'category' => ConversionActionCategory::PBDEFAULT,
            'type' => ConversionActionType::WEBPAGE,
            'status' => ConversionActionStatus::ENABLED,
            'view_through_lookback_window_days' => 15,
            'value_settings' => new ValueSettings(
                [
                'default_value' => 23.41,
                'always_use_default_value' => true
                ]
            )
            ]
        );

        // Creates a conversion action operation.
        $conversionActionOperation = new ConversionActionOperation();
        $conversionActionOperation->setCreate($conversionAction);

        // Issues a mutate request to add the conversion action.
        $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
        $response = $conversionActionServiceClient->mutateConversionActions(
            MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
        );

        printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);

        foreach ($response->getResults() as $addedConversionAction) {
            /**
 * @var ConversionAction $addedConversionAction
*/
            printf(
                "New conversion action added with resource name: '%s'%s",
                $addedConversionAction->getResourceName(),
                PHP_EOL
            );
        }
    }AddConversionAction.php

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

    # Create the operation.
    conversion_action_operation: ConversionActionOperation = client.get_type(
        "ConversionActionOperation"
    )

    # Create conversion action.
    conversion_action: ConversionAction = conversion_action_operation.create

    # Note that conversion action names must be unique. If a conversion action
    # already exists with the specified conversion_action_name, the create
    # operation will fail with a ConversionActionError.DUPLICATE_NAME error.
    conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}"
    conversion_action.type_ = (
        client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS
    )
    conversion_action.category = (
        client.enums.ConversionActionCategoryEnum.DEFAULT
    )
    conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED
    conversion_action.view_through_lookback_window_days = 15

    # Create a value settings object.
    value_settings: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        conversion_action_service.mutate_conversion_actions(
            customer_id=customer_id,
            operations=[conversion_action_operation],
        )
    )

    print(
        "Created conversion action "
        f'"{conversion_action_response.results[0].resource_name}".'
    )add_conversion_action.py

Ruby

def add_conversion_action(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new


  # Add a conversion action.
  conversion_action = client.resource.conversion_action do |ca|
    ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
    ca.type = :UPLOAD_CLICKS
    ca.category = :DEFAULT
    ca.status = :ENABLED
    ca.view_through_lookback_window_days = 15

    # Create a value settings object.
    ca.value_settings = client.resource.value_settings do |vs|
      vs.default_value = 15
      vs.always_use_default_value = true
    end
  end

  # Create the operation.
  conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action)

  # Add the ad group ad.
  response = client.service.conversion_action.mutate_conversion_actions(
    customer_id: customer_id,
    operations: [conversion_action_operation],
  )

  puts "New conversion action with resource name = #{response.results.first.resource_name}."
endadd_conversion_action.rb

Perl

sub add_conversion_action {
  my ($api_client, $customer_id) = @_;

  # Note that conversion action names must be unique.
  # If a conversion action already exists with the specified conversion_action_name,
  # the create operation fails with error ConversionActionError.DUPLICATE_NAME.
  my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid();

  # Create a conversion action.
  my $conversion_action =
    Google::Ads::GoogleAds::V26::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V26::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V26::Services::ConversionActionService::ConversionActionOperation
    ->new({create => $conversion_action});

  # Add the conversion action.
  my $conversion_actions_response =
    $api_client->ConversionActionService()->mutate({
      customerId => $customer_id,
      operations => [$conversion_action_operation]});

  printf "New conversion action added with resource name: '%s'.\n",
    $conversion_actions_response->{results}[0]{resourceName};

  return 1;
}add_conversion_action.pl

curl

REST 요청

REST를 통해 동일한 ConversionAction를 만들려면 POST 요청을 ConversionActionService.MutateConversionActions에 전송합니다.

POST https://googleads.googleapis.com/v26/customers/{customer_id}/conversionActions:mutate

{
  "operations": [
    {
      "create": {
        "name": "Earth to Mars Cruise Conversion",
        "type": "UPLOAD_CLICKS",
        "category": "DEFAULT",
        "status": "ENABLED",
        "primaryForGoal": true,
        "countingType": "ONE_PER_CLICK",
        "clickThroughLookbackWindowDays": "60",
        "valueSettings": {
          "defaultValue": 23.41,
          "defaultCurrencyCode": "USD",
          "alwaysUseDefaultValue": true
        }
      }
    }
  ]
}

전환 액션이 ENABLED이면 전환 소스의 워크플로를 사용하여 전환 이벤트 또는 보강을 가져옵니다(전환 이벤트 가져오기 참조).

3. 오프라인 전환 업로드 상태 모니터링

클릭 전환, 통화 전환 또는 전환 조정 업로드 후 offline_conversion_upload_client_summary를 쿼리하여 최근 업로드 전반의 전체 작업 상태, 성공 및 대기 중 비율, 오류 분석을 확인합니다.

SELECT
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.total_event_count,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.success_rate,
  offline_conversion_upload_client_summary.pending_event_count,
  offline_conversion_upload_client_summary.pending_rate,
  offline_conversion_upload_client_summary.last_upload_date_time,
  offline_conversion_upload_client_summary.alerts
FROM offline_conversion_upload_client_summary

전환 액션 수준 진단을 위해 offline_conversion_upload_conversion_action_summary를 쿼리하고(오프라인 데이터 진단 모니터링 참고) 전환 가져오기 문제 해결을 참고하여 특정 오류 코드를 해결합니다.

수명 주기 단계별 가이드 디렉터리

수명 주기 단계별로 정리된 전체 전환 관리 가이드를 살펴보세요.

1. 계정 설정 및 전환 액션

전환 액션 카테고리: 올바른 전환 소스(웹사이트(WEBPAGE), 전화 통화(UPLOAD_CALLS, AD_CALL, WEBSITE_CALL), 모바일 앱(GOOGLE_PLAY_DOWNLOAD, GOOGLE_PLAY_IN_APP_PURCHASE, Firebase, SKAdNetwork), Google 애널리틱스 4(GOOGLE_ANALYTICS_4_CUSTOM, GOOGLE_ANALYTICS_4_PURCHASE), 오프라인(UPLOAD_CLICKS), 오프라인 상점(STORE_SALES))를 선택하고 해당 ConversionActionType 및 API 워크플로에 매핑합니다.
시작하기: 클라이언트 라이브러리 또는 REST를 사용하여 사용자 동의를 구성하고, ConversionTrackingSetting를 확인하고, 교차 계정 전환 추적을 설정하고, 전환 액션을 만듭니다.

2. 전환 이벤트 가져오기

오프라인 클릭 전환 가져오기: 오프라인 전환 (GCLID, GBRAID, WBRAID) 및 리드 확보용 향상된 전환 (퍼스트 파티 해싱된 이메일 및 전화번호)을 업로드하여 실제 거래를 측정합니다.
온라인 클릭 전환 가져오기: 웹용 향상된 전환(ENHANCEMENT 조정)을 사용하여 이메일 주소, 이름, 집 주소, 전화번호와 같은 퍼스트 파티 사용자 데이터로 웹사이트 전환 태그를 보완합니다.
통화 전환 가져오기: Google 착신 전화번호 또는 자체 통화 추적 시스템을 통해 추적되는 전화 통화의 전환 이벤트를 업로드합니다.
매장 판매 전환 가져오기: OfflineUserDataJobService를 사용하여 오프라인 매장 거래 데이터를 일괄 업로드합니다.

3. 전환 조정 및 최적화

가져오기 후 전환 조정: UPLOAD_CLICKS, WEBPAGE, SALESFORCE(지원 중단됨) 전환 액션에 대해 취소된 주문 (RETRACTION)을 철회하거나 수정된 전환 가치(RESTATEMENT)를 재조정합니다.
전환 가치 규칙 관리: 잠재고객, 기기, 지리적 위치 또는 운항 일정 기준에 따라 입찰 시 전환 가치를 동적으로 조정합니다.
맞춤 전환 변수: 분류된 보고를 위해 클릭, 통화, 웹 전환에 맞춤 키-값 태그 (ConversionCustomVariable)를 정의하고 연결합니다.
전환 목표: category (ConversionActionCategory) 및 origin (ConversionOrigin) 필드를 기준으로 전환 액션을 그룹화하고 고객 목표, 캠페인 및 맞춤 목표, 고객 라이프사이클 목표 (신규 고객 확보, 이탈 고객 확보, 충성도 유지)를 구성합니다. 신규 고객 전환 가치 증가분에 대한 OPTIMIZE_FOR_NEW_CUSTOMERS 추천을 가져와 적용할 수도 있습니다.

4. 모니터링, 보고, 문제 해결

오프라인 데이터 진단 모니터링: 계정 수준(offline_conversion_upload_client_summary) 및 전환 액션 수준(offline_conversion_upload_conversion_action_summary)에서 오프라인 데이터 진단을 쿼리하여 성공률, 대기 중인 이벤트, 업로드 알림을 추적합니다.
전환 통계 가져오기: GAQL에서 전환 실적 측정항목을 쿼리하고 Google Ads UI 열을 Google Ads API 필드에 매핑합니다.
전환 가져오기 문제 해결: 일반적인 ConversionUploadError 및 ConversionAdjustmentUploadError 코드를 진단하고 해결합니다.

전환 액션 카테고리