Definir ou atualizar lances

Você pode usar a API Google Ads para definir ou atualizar lances para anúncios de hotel.

Não defina os campos bidding_strategy ou bidding_strategy_type. O campo bidding_strategy_type serve apenas para ler a configuração atual de uma campanha. Ele é somente leitura.

Para uma estratégia de Comissões (por conversão ou por estadia):

Para uma estratégia de %do CPC ou CPC manual:

Definir valores de lance de CPC manual ou de porcentagem do CPC

Para as estratégias de lances de CPC manual e percentual, os valores de lances específicos precisam ser definidos como:

  • No nível do grupo de anúncios
  • Nível do grupo de fichas em nós de unidade de uma árvore de grupo de fichas

No entanto, embora você precise definir o valor no nível do grupo de anúncios, ele não será usado pelos anúncios de hotel. Os anúncios de hotel usam o valor no nível do grupo de fichas, o que substitui o valor irrelevante no nível do grupo de anúncios.

Também é possível controlar os limites de lance no nível da campanha como parte da definição da estratégia de lances. Para mais detalhes, consulte Atribuir ou atualizar uma estratégia de lances.

Definir um lance em um grupo de anúncios

O código abaixo mostra como definir um lance no nível do grupo de anúncios ao criar um novo grupo de anúncios de hotel.

Java

private String addHotelAdGroup(
    GoogleAdsClient googleAdsClient, long customerId, String campaignResourceName) {
  // Creates an ad group.
  AdGroup adGroup =
      AdGroup.newBuilder()
          .setName("Earth to Mars Cruises #" + getPrintableDateTime())
          .setCampaign(campaignResourceName)
          // Sets the ad group type to HOTEL_ADS. This cannot be set to other types.
          .setType(AdGroupType.HOTEL_ADS)
          .setCpcBidMicros(1_000_000L)
          .setStatus(AdGroupStatus.ENABLED)
          .build();

  // Creates an ad group operation.
  AdGroupOperation operation = AdGroupOperation.newBuilder().setCreate(adGroup).build();

  // Issues a mutate request to add an ad group.
  try (AdGroupServiceClient adGroupServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupServiceClient()) {
    MutateAdGroupResult mutateAdGroupResult =
        adGroupServiceClient
            .mutateAdGroups(Long.toString(customerId), Collections.singletonList(operation))
            .getResults(0);
    System.out.printf(
        "Added a hotel ad group with resource name: '%s'%n",
        mutateAdGroupResult.getResourceName());
    return mutateAdGroupResult.getResourceName();
  }
}
      

C#

private static string AddHotelAdGroup(GoogleAdsClient client, long customerId,
    string campaignResourceName)
{
    // Get the AdGroupService.
    AdGroupServiceClient service = client.GetService(Services.V16.AdGroupService);

    // Create an ad group.
    AdGroup adGroup = new AdGroup()
    {
        Name = "Earth to Mars Cruise #" + ExampleUtilities.GetRandomString(),

        // Sets the campaign.
        Campaign = campaignResourceName,

        // Optional: Sets the ad group type to HOTEL_ADS.
        // This cannot be set to other types.
        Type = AdGroupType.HotelAds,

        CpcBidMicros = 10000000,
        Status = AdGroupStatus.Enabled
    };

    // Create an ad group operation.
    AdGroupOperation adGroupOperation = new AdGroupOperation()
    {
        Create = adGroup
    };

    // Issue a mutate request to add an ad group.
    MutateAdGroupsResponse response = service.MutateAdGroups(customerId.ToString(),
        new AdGroupOperation[] { adGroupOperation });
    return response.Results[0].ResourceName;
}
      

PHP

private static function addHotelAdGroup(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    string $campaignResourceName
) {
    // Creates an ad group.
    $adGroup = new AdGroup([
        'name' => 'Earth to Mars Cruise #' . Helper::getPrintableDatetime(),
        // Sets the campaign.
        'campaign' => $campaignResourceName,
        // Sets the ad group type to HOTEL_ADS.
        // This cannot be set to other types.
        'type' => AdGroupType::HOTEL_ADS,
        'cpc_bid_micros' => 10000000,
        'status' => AdGroupStatus::ENABLED,
    ]);

    // Creates an ad group operation.
    $adGroupOperation = new AdGroupOperation();
    $adGroupOperation->setCreate($adGroup);

    // Issues a mutate request to add an ad group.
    $adGroupServiceClient = $googleAdsClient->getAdGroupServiceClient();
    $response = $adGroupServiceClient->mutateAdGroups(
        MutateAdGroupsRequest::build($customerId, [$adGroupOperation])
    );

    /** @var AdGroup $addedAdGroup */
    $addedAdGroup = $response->getResults()[0];
    printf(
        "Added a hotel ad group with resource name '%s'.%s",
        $addedAdGroup->getResourceName(),
        PHP_EOL
    );

    return $addedAdGroup->getResourceName();
}
      

Python

def add_hotel_ad_group(client, customer_id, campaign_resource_name):
    ad_group_service = client.get_service("AdGroupService")

    # Create ad group.
    ad_group_operation = client.get_type("AdGroupOperation")
    ad_group = ad_group_operation.create
    ad_group.name = f"Earth to Mars cruise {uuid.uuid4()}"
    ad_group.status = client.enums.AdGroupStatusEnum.ENABLED
    ad_group.campaign = campaign_resource_name
    # Sets the ad group type to HOTEL_ADS. This cannot be set to other types.
    ad_group.type_ = client.enums.AdGroupTypeEnum.HOTEL_ADS
    ad_group.cpc_bid_micros = 10000000

    # Add the ad group.
    ad_group_response = ad_group_service.mutate_ad_groups(
        customer_id=customer_id, operations=[ad_group_operation]
    )

    ad_group_resource_name = ad_group_response.results[0].resource_name

    print(
        "Added a hotel ad group with resource name '{ad_group_resource_name}'."
    )

    return ad_group_resource_name
      

Ruby

def add_hotel_ad_group(client, customer_id, campaign_resource)
  # Create an ad group.
  ad_group_operation = client.operation.create_resource.ad_group do |ag|
    ag.name = generate_random_name_field("Earth to Mars Cruise")

    # Set the campaign.
    ag.campaign = campaign_resource

    # Optional: Set the ad group type to HOTEL_ADS.
    # This cannot be set to other types.
    ag.type = :HOTEL_ADS
    ag.cpc_bid_micros = 10_000_000
    ag.status = :ENABLED
  end

  # Issue a mutate request to add the ad group.
  ad_group_service = client.service.ad_group
  response = ad_group_service.mutate_ad_groups(
    customer_id: customer_id,
    operations: [ad_group_operation]
  )

  # Fetch the new ad group's resource name.
  ad_group_resource = response.results.first.resource_name

  puts "Added hotel ad group with resource name '#{ad_group_resource}'."

  ad_group_resource
end
      

Perl

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

  # Create an ad group.
  my $ad_group = Google::Ads::GoogleAds::V16::Resources::AdGroup->new({
    name => "Earth to Mars Cruise #" . uniqid(),
    # Set the campaign.
    campaign => $campaign_resource_name,
    # Set the ad group type to HOTEL_ADS.
    # This cannot be set to other types.
    type         => HOTEL_ADS,
    cpcBidMicros => 1000000,
    status => Google::Ads::GoogleAds::V16::Enums::AdGroupStatusEnum::ENABLED
  });

  # Create an ad group operation.
  my $ad_group_operation =
    Google::Ads::GoogleAds::V16::Services::AdGroupService::AdGroupOperation->
    new({create => $ad_group});

  # Add the ad group.
  my $ad_group_resource_name = $api_client->AdGroupService()->mutate({
      customerId => $customer_id,
      operations => [$ad_group_operation]})->{results}[0]{resourceName};

  printf "Added a hotel ad group with resource name: '%s'.\n",
    $ad_group_resource_name;

  return $ad_group_resource_name;
}
      

Definir um lance em um nó de unidade de grupo de fichas

Conforme descrito em Criar grupos de fichas de hotéis, os anúncios de hotel não vão ser veiculados até que você crie uma árvore válida de grupos de fichas com pelo menos um nó de unidade. Além disso, os nós são objetos da classe ListingGroupInfo, que contêm o campo ListingGroupType, que indica se os nós são uma unidade ou subdivisão. Definir ListingGroupInfo como listing_group de AdGroupCriterion vincula o objeto ListingGroupInfo ao AdGroup. É possível definir lances em nós de unidade configurando o campo percent_cpc_bid_micros ou o campo cpc_bid_micros de AdGroupCriterion. A tentativa de fazer isso em nós de subdivisão falhará com um erro.

Ao definir lances no nível do grupo de fichas, observe o seguinte:

  • Não é possível definir o valor do lance no grupo de fichas de hotéis "Todos os hotéis" (raiz).
  • Não é possível definir o valor do lance em uma subdivisão.
  • O Google recomenda não definir lances em "Outros" nós que sejam nós de unidade. Lances em nós "Outros" (bloco) podem ter efeitos não intencionais em outros lances de anúncios de hotel.

O código abaixo mostra como definir um lance em um nó do bloco de um grupo de fichas.

Java

private static String addLevel1Nodes(
    long customerId,
    long adGroupId,
    String rootResourceName,
    List<AdGroupCriterionOperation> operations,
    long percentCpcBidMicroAmount) {
  // Creates hotel class info and dimension info for 5-star hotels.
  ListingDimensionInfo fiveStarredDimensionInfo =
      ListingDimensionInfo.newBuilder()
          .setHotelClass(HotelClassInfo.newBuilder().setValue(5).build())
          .build();
  // Creates listing group info for 5-star hotels as a UNIT node.
  ListingGroupInfo fiveStarredUnit =
      ListingGroupInfo.newBuilder()
          .setType(ListingGroupType.UNIT)
          .setParentAdGroupCriterion(rootResourceName)
          .setCaseValue(fiveStarredDimensionInfo)
          .build();
  // Creates an ad group criterion for 5-star hotels.
  AdGroupCriterion fiveStarredAdGroupCriterion =
      createAdGroupCriterion(customerId, adGroupId, fiveStarredUnit, percentCpcBidMicroAmount);
  // Decrements the temp ID for the next ad group criterion.
  AdGroupCriterionOperation operation = generateCreateOperation(fiveStarredAdGroupCriterion);
  operations.add(operation);

  // You can also create more UNIT nodes for other hotel classes by copying the above code in
  // this method and modifying the value passed to HotelClassInfo() to the value you want.
  // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star
  // hotels instead.

  // Creates hotel class info and dimension info for other hotel classes by not specifying
  // any attributes on those object.
  ListingDimensionInfo otherHotelsDimensionInfo =
      ListingDimensionInfo.newBuilder()
          .setHotelClass(HotelClassInfo.newBuilder().build())
          .build();
  // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be
  // used as a parent node for children nodes of the next level.
  ListingGroupInfo otherHotelsSubdivision =
      createListingGroupInfo(
          ListingGroupType.SUBDIVISION, rootResourceName, otherHotelsDimensionInfo);
  // Creates an ad group criterion for other hotel classes.
  AdGroupCriterion otherHotelsAdGroupCriterion =
      createAdGroupCriterion(
          customerId, adGroupId, otherHotelsSubdivision, percentCpcBidMicroAmount);
  operation = generateCreateOperation(otherHotelsAdGroupCriterion);
  operations.add(operation);

  return otherHotelsAdGroupCriterion.getResourceName();
}
      

C#

private string AddLevel1Nodes(long customerId, long adGroupId, string rootResourceName,
    List<AdGroupCriterionOperation> operations, long percentCpcBidMicroAmount)
{
    // Create listing dimension info for 5-star class hotels.
    ListingDimensionInfo fiveStarredListingDimensionInfo = new ListingDimensionInfo
    {
        HotelClass = new HotelClassInfo
        {
            Value = 5
        }
    };

    // Create a listing group info for 5-star hotels as a UNIT node.
    ListingGroupInfo fiveStarredUnit = CreateListingGroupInfo(ListingGroupType.Unit,
        rootResourceName, fiveStarredListingDimensionInfo);

    // Create an ad group criterion for 5-star hotels.
    AdGroupCriterion fiveStarredAdGroupCriterion = CreateAdGroupCriterion(customerId,
        adGroupId, fiveStarredUnit, percentCpcBidMicroAmount);

    // Create an operation and add it to the list of operations.
    operations.Add(new AdGroupCriterionOperation
    {
        Create = fiveStarredAdGroupCriterion
    });

    // Decrement the temp ID for the next ad group criterion.
    nextTempId--;

    // You can also create more UNIT nodes for other hotel classes by copying the above code
    // in this method and modifying the value passed to HotelClassInfo().
    // For instance, passing 4 instead of 5 in the above code will instead create a UNIT
    // node of 4-star hotels.

    // Create hotel class info and dimension info for other hotel classes by *not*
    // specifying any attributes on those object.
    ListingDimensionInfo otherHotelsListingDimensionInfo = new ListingDimensionInfo
    {
        HotelClass = new HotelClassInfo()
    };

    // Create listing group info for other hotel classes as a SUBDIVISION node, which will
    // be used as a parent node for children nodes of the next level.
    ListingGroupInfo otherHotelsSubdivisionListingGroupInfo = CreateListingGroupInfo
        (ListingGroupType.Subdivision, rootResourceName, otherHotelsListingDimensionInfo);

    // Create an ad group criterion for other hotel classes.
    AdGroupCriterion otherHotelsAdGroupCriterion = CreateAdGroupCriterion(customerId,
        adGroupId, otherHotelsSubdivisionListingGroupInfo, percentCpcBidMicroAmount);

    // Create an operation and add it to the list of operations.
    operations.Add(new AdGroupCriterionOperation
    {
        Create = otherHotelsAdGroupCriterion
    });

    // Decrement the temp ID for the next ad group criterion.
    nextTempId--;

    return otherHotelsAdGroupCriterion.ResourceName;
}
      

PHP

private static function addLevel1Nodes(
    int $customerId,
    int $adGroupId,
    string $rootResourceName,
    array &$operations,
    int $percentCpcBidMicroAmount
) {
    // Creates hotel class info and dimension info for 5-star hotels.
    $fiveStarredDimensionInfo = new ListingDimensionInfo([
        'hotel_class' => new HotelClassInfo(['value' => 5])
    ]);
    // Creates listing group info for 5-star hotels as a UNIT node.
    $fiveStarredUnit = self::createListingGroupInfo(
        ListingGroupType::UNIT,
        $rootResourceName,
        $fiveStarredDimensionInfo
    );
    // Creates an ad group criterion for 5-star hotels.
    $fiveStarredAdGroupCriterion = self::createAdGroupCriterion(
        $customerId,
        $adGroupId,
        $fiveStarredUnit,
        $percentCpcBidMicroAmount
    );
    // Decrements the temp ID for the next ad group criterion.
    self::$nextTempId--;
    $operation = self::generateCreateOperation($fiveStarredAdGroupCriterion);
    $operations[] = $operation;

    // You can also create more UNIT nodes for other hotel classes by copying the above code in
    // this method and modifying the value passed to HotelClassInfo() to the value you want.
    // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star
    // hotels instead.

    // Creates hotel class info and dimension info for other hotel classes by *not* specifying
    // any attributes on those object.
    $othersHotelsDimensionInfo = new ListingDimensionInfo([
        'hotel_class' => new HotelClassInfo()
    ]);
    // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be
    // used as a parent node for children nodes of the next level.
    $otherHotelsSubDivision = self::createListingGroupInfo(
        ListingGroupType::SUBDIVISION,
        $rootResourceName,
        $othersHotelsDimensionInfo
    );
    // Creates an ad group criterion for other hotel classes.
    $otherHotelsAdGroupCriterion = self::createAdGroupCriterion(
        $customerId,
        $adGroupId,
        $otherHotelsSubDivision,
        $percentCpcBidMicroAmount
    );
    $operation = self::generateCreateOperation($otherHotelsAdGroupCriterion);
    $operations[] = $operation;

    self::$nextTempId--;
    return $otherHotelsAdGroupCriterion->getResourceName();
}
      

Python

def add_level1_nodes(
    client,
    customer_id,
    ad_group_id,
    root_resource_name,
    operations,
    percent_cpc_bid_micro_amount,
):
    """Creates child nodes on level 1, partitioned by the hotel class info.

    Args:
        client: The Google Ads API client.
        customer_id: The Google Ads customer ID.
        ad_group_id: The ad group ID to which the hotel listing group will be
            added.
        root_resource_name: The string resource name of the listing group's root
            node.
        operations: A list of AdGroupCriterionOperations.
        percent_cpc_bid_micro_amount: The CPC bid micro amount to be set on
            created ad group criteria.

    Returns:
        The string resource name of the "other hotel classes" node, which serves
        as the parent node for the next level of the listing tree.
    """
    global next_temp_id

    # Create listing dimension info for 5-star class hotels.
    five_starred_listing_dimension_info = client.get_type(
        "ListingDimensionInfo"
    )
    five_starred_listing_dimension_info.hotel_class.value = 5

    # Create a listing group info for 5-star hotels as a UNIT node.
    five_starred_unit = create_listing_group_info(
        client,
        client.enums.ListingGroupTypeEnum.UNIT,
        root_resource_name,
        five_starred_listing_dimension_info,
    )

    # Create an ad group criterion for 5-star hotels.
    five_starred_ad_group_criterion = create_ad_group_criterion(
        client,
        customer_id,
        ad_group_id,
        five_starred_unit,
        percent_cpc_bid_micro_amount,
    )

    # Create an operation and add it to the list of operations.
    five_starred_ad_group_criterion_operation = client.get_type(
        "AdGroupCriterionOperation"
    )
    client.copy_from(
        five_starred_ad_group_criterion_operation.create,
        five_starred_ad_group_criterion,
    )
    operations.append(five_starred_ad_group_criterion_operation)

    # Decrement the temp ID for the next ad group criterion.
    next_temp_id -= 1

    # You can also create more UNIT nodes for other hotel classes by copying the
    # above code in this method and modifying the hotel class value.
    # For instance, passing 4 instead of 5 in the above code will instead create
    # a UNIT node of 4-star hotels.

    # Create hotel class info and dimension info without any specifying
    # attributes. This node will then represent hotel classes other than those
    # already covered by UNIT nodes at this level.
    other_hotels_listing_dimension_info = client.get_type(
        "ListingDimensionInfo"
    )
    # Set "hotel_class" as the oneof field on the ListingDimensionInfo object
    # without specifying the optional hotel_class field.
    client.copy_from(
        other_hotels_listing_dimension_info.hotel_class,
        client.get_type("HotelClassInfo"),
    )

    # Create listing group info for other hotel classes as a SUBDIVISION node,
    # which will be used as a parent node for children nodes of the next level.
    other_hotels_subdivision_listing_group_info = create_listing_group_info(
        client,
        client.enums.ListingGroupTypeEnum.SUBDIVISION,
        root_resource_name,
        other_hotels_listing_dimension_info,
    )

    # Create an ad group criterion for other hotel classes.
    other_hotels_ad_group_criterion = create_ad_group_criterion(
        client,
        customer_id,
        ad_group_id,
        other_hotels_subdivision_listing_group_info,
        percent_cpc_bid_micro_amount,
    )

    # Create an operation and add it to the list of operations.
    other_hotels_ad_group_criterion_operation = client.get_type(
        "AdGroupCriterionOperation"
    )
    client.copy_from(
        other_hotels_ad_group_criterion_operation.create,
        other_hotels_ad_group_criterion,
    )
    operations.append(other_hotels_ad_group_criterion_operation)

    # Decrement the temp ID for the next ad group criterion.
    next_temp_id -= 1

    return other_hotels_ad_group_criterion.resource_name
      

Ruby

def add_level1_nodes(
  client,
  customer_id,
  ad_group_id,
  root_resource_name,
  operations,
  percent_cpc_bid_micro_amount)
  # Creates hotel class info and dimension info for 5-star hotels.
  five_starred_dimension_info = client.resource.listing_dimension_info do |d|
    d.hotel_class = client.resource.hotel_class_info do |c|
      c.value = 5
    end
  end

  # Creates listing group info for 5-star hotels as a UNIT node.
  five_starred_unit = create_listing_group_info(
    client,
    :UNIT,
    root_resource_name,
    five_starred_dimension_info,
  )

  # Creates an ad group criterion for 5-star hotels.
  five_starred_ad_group_criterion = create_ad_group_criterion(
    client,
    customer_id,
    ad_group_id,
    five_starred_unit,
    percent_cpc_bid_micro_amount,
  )

  operations << generate_create_operation(
    client,
    five_starred_ad_group_criterion,
  )

  # You can also create more UNIT nodes for other hotel classes by copying the
  # above code in this method and modifying the value passed to HotelClassInfo()
  # to the value you want.
  # For instance, passing 4 instead of 5 in the above code will create a UNIT
  # node of 4-star hotels instead.

  # Creates hotel class info and dimension info for other hotel classes
  # by *not* specifying any attributes on those object.
  other_hotels_dimention_info = client.resource.listing_dimension_info do |d|
    d.hotel_class = client.resource.hotel_class_info
  end

  # Creates listing group info for other hotel classes as a SUBDIVISION node,
  # which will be used as a parent node for children nodes of the next level.
  other_hotels_subdivision = create_listing_group_info(
    client,
    :SUBDIVISION,
    root_resource_name,
    other_hotels_dimention_info,
  )

  # Creates an ad group criterion for other hotel classes.
  other_hotels_ad_group_criterion = create_ad_group_criterion(
    client,
    customer_id,
    ad_group_id,
    other_hotels_subdivision,
    percent_cpc_bid_micro_amount,
  )

  operations << generate_create_operation(
    client,
    other_hotels_ad_group_criterion,
  )

  other_hotels_ad_group_criterion.resource_name
end
      

Perl

sub add_level_1_nodes {
  my ($customer_id, $ad_group_id, $root_resource_name, $operations,
    $percent_cpc_bid_micro_amount)
    = @_;

  # Create hotel class info and dimension info for 5-star hotels.
  my $five_starred_dimension_info =
    Google::Ads::GoogleAds::V16::Common::ListingDimensionInfo->new({
      hotelClass => Google::Ads::GoogleAds::V16::Common::HotelClassInfo->new({
          value => 5
        })});

  # Create listing group info for 5-star hotels as a UNIT node.
  my $five_starred_unit = create_listing_group_info(UNIT, $root_resource_name,
    $five_starred_dimension_info);

  # Create an ad group criterion for 5-star hotels.
  my $five_starred_ad_group_criterion =
    create_ad_group_criterion($customer_id, $ad_group_id, $five_starred_unit,
    $percent_cpc_bid_micro_amount);

  my $operation = generate_create_operation($five_starred_ad_group_criterion);
  push @$operations, $operation;

  # You can also create more UNIT nodes for other hotel classes by copying the
  # above code in this method and modifying the value passed to HotelClassInfo
  # to the value you want. For instance, passing 4 instead of 5 in the above code
  #  will create a UNIT node of 4-star hotels instead.

  # Create hotel class info and dimension info for other hotel classes by *not*
  # specifying any attributes on those object.
  my $others_hotels_dimension_info =
    Google::Ads::GoogleAds::V16::Common::ListingDimensionInfo->new({
      hotelClass => Google::Ads::GoogleAds::V16::Common::HotelClassInfo->new()}
    );

  # Create listing group info for other hotel classes as a SUBDIVISION node, which
  # will be used as a parent node for children nodes of the next level.
  my $other_hotels_subdivision =
    create_listing_group_info(SUBDIVISION, $root_resource_name,
    $others_hotels_dimension_info);

  # Create an ad group criterion for other hotel classes.
  my $other_hotels_ad_group_criterion =
    create_ad_group_criterion($customer_id, $ad_group_id,
    $other_hotels_subdivision, $percent_cpc_bid_micro_amount);

  $operation = generate_create_operation($other_hotels_ad_group_criterion);
  push @$operations, $operation;

  return $other_hotels_ad_group_criterion->{resourceName};
}