Quer compartilhar seu feedback sobre a API Google Ads? Faça sua inscrição para receber um convite para participar da pesquisa com usuários.

Esta página foi traduzida pela API Cloud Translation.

Notas da versão

v19 (26/02/2025)

Os recursos e mudanças a seguir foram adicionados à versão 19.

Gerenciamento da conta

Os seguintes valores foram adicionados a CustomerError para considerar as próximas mudanças:
- CREATION_DENIED_FOR_POLICY_VIOLATION
- CREATION_DENIED_INELIGIBLE_MCC

Anúncios

Adição de DemandGenMultiAssetAdInfo.tall_portrait_marketing_images para oferecer suporte a recursos de imagem em modo retrato com proporção 9:16 nos anúncios de Geração de demanda.

Recursos

(Somente para contas na lista de permissões) Foi adicionado suporte a recursos de mensagens usando Asset.business_message_asset, BusinessMessageAsset e os seguintes tipos enumerados e erros.
- Tipos enumerados:
- Erros:
  - AssetError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_WHATSAPP_MESSAGE_ASSETS
  - ResourceLimitType
Adição de AssetAutomationType.GENERATE_LANDING_PAGE_PREVIEW para oferecer suporte à geração automática de uma visualização da página de destino.
A AssetAutomationType.GENERATE_SHORTER_YOUTUBE_VIDEOS agora está ativada por padrão para anúncios responsivos em vídeo da Geração de demanda.
(Somente para contas na lista de permissões; a lista está fechada no momento) Foram adicionados Asset.app_deep_link_asset e AppDeepLinkAsset.

Conversões

Metas de conversão
- LifecycleGoalValueSettings.high_lifetime_value saiu da versão Beta e agora é mutável.
- Adicionado CustomerLifecycleGoal.owner_customer para mostrar o nome do recurso do cliente que é proprietário da meta do ciclo de vida do cliente.
O uso de ConversionActionType.SALESFORCE foi descontinuado.

Feeds

Todas as entidades relacionadas ao feed foram removidas, como Feed, FeedMapping, FeedService, AdGroupFeed, feed_placeholder_view etc. Agora, os usuários precisam usar ativos para alcançar o mesmo objetivo. Acesse as Notas de migração para conferir a lista de todas as entidades removidas.

Hotel e viagens

min_days e max_days de ValueRuleItineraryAdvanceBookingWindow foram transformados em um campo optional para permitir a especificação de 0 como um valor. Isso oferece suporte à segmentação para pesquisas de viagens que acontecem hoje.

Performance Max

(Somente para contas na lista de permissões) Diretrizes da marca
- O Campaign.brand_guidelines_enabled passou a ser mutável apenas ao criar uma campanha Performance Max.
- Isso é incompatível com as campanhas Performance Max para metas de turismo.
- Para ativar as diretrizes da marca em campanhas Performance Max atuais, use uma CampaignService.EnablePMaxBrandGuidelines recém-adicionada. Não é possível desativar as diretrizes da marca.
- Campaign.brand_guidelines e BrandGuidelines foram adicionados para permitir a configuração das cores e da família de fontes da marca.
- Novos valores de erro:
  - BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE
  - BrandGuidelinesMigrationError
- CampaignError
  - BRAND_GUIDELINES_NOT_ENABLED_FOR_CAMPAIGN
  - BRAND_GUIDELINES_MAIN_AND_ACCENT_COLORS_REQUIRED
  - BRAND_GUIDELINES_COLOR_INVALID_FORMAT
  - BRAND_GUIDELINES_UNSUPPORTED_FONT_FAMILY
  - BRAND_GUIDELINES_UNSUPPORTED_CHANNEL
  - CANNOT_ENABLE_BRAND_GUIDELINES_FOR_TRAVEL_GOALS
  - CUSTOMER_NOT_ALLOWLISTED_FOR_BRAND_GUIDELINES
Adicionamos AssetAutomationType.GENERATE_ENHANCED_YOUTUBE_VIDEOS para gerar automaticamente recursos de vídeo aprimorados para campanhas Performance Max.

Planejamento

(Somente para contas na lista de permissões) Foi adicionado o ContentCreatorInsightsService.GenerateTrendingInsights, que permite que os usuários vejam os temas de conteúdo em alta no YouTube para determinadas definições de público-alvo.
Foi adicionado GenerateCreatorInsightsRequest.country_locations[] para especificar os países em que os critérios serão pesquisados.
A GenerateCreatorInsightsRequest.search_brand foi adicionada para especificar uma marca na pesquisa de criadores
Adicionamos novos campos a YouTubeChannelInsights para fornecer mais informações do canal para solicitações search_channels:
- channel_url
- channel_description
- top_videos
Foram adicionados novos campos de metadados a AudienceInsightsAttributeMetadata:
- youtube_video_metadata
- user_interest_attribute_metadata
- knowledge_graph_attribute_metadata

Vídeos

Após o lançamento de DataLinkService.CreateDataLink, adicionamos os seguintes métodos para permitir a mutação de vinculações de dados criadas anteriormente:
- RemoveDataLink para remover vinculações de dados em uma conta do Google Ads
- UpdateDataLink para aceitar, rejeitar e revogar vinculações de dados em uma conta do Google Ads
A compatibilidade com VIDEO_OUTSTREAM foi removida dos seguintes tipos enumerados:

v18 (16/10/2024)

Os seguintes novos recursos e atualizações foram adicionados à v18.

Gerenciamento da conta

(Somente para contas na lista de permissões) Adicionamos o DataLinkService.CreateDataLink, que permite vincular uma conta do Google Ads a vídeos hospedados no canal do criador de conteúdo. Com a vinculação de vídeos, a conta do Google Ads pode veicular anúncios de parceria usando vídeos de criadores de conteúdo.

Grupos de anúncios

Foi adicionado o AdGroup.exclude_demographic_expansion, que permite excluir a expansão de dados demográficos quando optimized_targeting_enabled é true, um recurso que antes só era compatível com a Geração de demanda.

Anúncios

Adição de AdGroupAd.ad_group_ad_asset_automation_settings, que permite ativar ou desativar a geração automática de recursos.
Os seguintes valores foram adicionados a AssetAutomationType:
- GENERATE_VERTICAL_YOUTUBE_VIDEOS
- GENERATE_SHORTER_YOUTUBE_VIDEOS
Adicionado AdNetworkType.GOOGLE_OWNED_CHANNELS, que é usado por anúncios veiculados em canais do Google, como o YouTube, o Gmail e o feed do Discover.

Recursos

AssetType.DISCOVERY_CAROUSEL_CARD foi renomeado como AssetType.DEMAND_GEN_CAROUSEL_CARD.

Campanhas

A metrics.store_visits_last_click_model_attributed_conversions foi adicionada, o que retorna o número de visitas à loja atribuídas pelo modelo de último clique de uma campanha.
Adicionamos as seguintes métricas relacionadas às visualizações de vídeo de uma campanha:
Adicionado metrics.results_conversions_purchase, que retorna compras de conversão para os resultados de metas unificadas de uma campanha.
O valor padrão de DemandGenCampaignSettings.upgraded_targeting foi alterado de false para true.

Critério

A content_criterion_view foi adicionada e retorna métricas de performance de conteúdos segmentados, como palavras-chave, canais e tópicos, para campanhas de display, Geração de demanda e vídeo.

Hotel e viagens

Suporte para feeds de viagem nos anúncios de pesquisa
- A ClickType.TRAVEL_ASSETS foi adicionada para permitir a segmentação das métricas dos feeds de viagem nos anúncios de pesquisa.
- Adicionamos o AssetSetType.TRAVEL_FEED, que pode ser usado para ativar e desativar o uso do feed de viagens nos anúncios de pesquisa.
(Somente para contas na lista de permissões) Adicionamos o itinerário de viagem como uma nova regra do valor da conversão com os seguintes campos e valores:
- ConversionValueRule.itinerary_condition com ValueRuleItineraryCondition, que permite especificar uma janela de reserva futura, a duração do itinerário e os dias da semana de início da viagem
- ConversionValueRulePrimaryDimensionEnum.ITINERARY
- ValueRuleSetDimension.ITINERARY
Adicionamos os seguintes segmentos aos relatórios campaign e ad_group para permitir a segmentação dos dados de performance com base em destinos específicos (cidades, países e regiões) para campanhas de hotel e de pesquisa:

Serviços locais

PhoneCallDetails.call_recording_url vai ficar vazio, em vez de fornecer um URL inválido se a gravação de chamada não existir para a conversa de lead do Serviços locais.
Foi adicionado CategoryBid.target_cpa_bid_micro, que permite definir o CPA desejado de uma categoria usando Campaign.local_services_campaign_settings.

Performance Max

Suporte para diretrizes de marca
- Adicionamos o Campaign.brand_guidelines_enabled, que mostra se as diretrizes da marca estão ativadas para uma determinada campanha Performance Max. Se ativada, os recursos com field_type definidos como BUSINESS_NAME, LOGO, LANDSCAPE_LOGO precisam ser vinculados como recursos CampaignAsset em vez de AssetGroupAsset.
- Foram adicionados os erros CampaignError.REQUIRED_BUSINESS_NAME_ASSET_NOT_LINKED e CampaignError.REQUIRED_LOGO_ASSET_NOT_LINKED, que indicam que as campanhas Performance Max com diretrizes de marca ativadas não têm os recursos CampaignAsset necessários vinculados à campanha.
- Quando as diretrizes de marca estão ativadas, pelo menos um recurso com field_type definido como BUSINESS_NAME e pelo menos um com LOGO precisam ser vinculados à campanha como recursos CampaignAsset. As campanhas Performance Max para vendas on-line com um feed de produtos precisam atender a esse requisito apenas quando há recursos vinculados aos grupos de recursos da campanha.
- Os seguintes valores foram adicionados a AssetLinkError:
  - BRAND_ASSETS_NOT_LINKED_AT_ASSET_GROUP_LEVEL, que é gerado ao tentar vincular recursos de marca a campanhas como recursos CampaignAsset em vez de AssetGroupAsset em campanhas Performance Max com diretrizes de marca não ativadas.
  - Erro BRAND_ASSETS_NOT_LINKED_AT_CAMPAIGN_LEVEL, que é gerado ao tentar vincular recursos de marca a campanhas como recursos AssetGroupAsset em vez de CampaignAsset em campanhas Performance Max com diretrizes de marca ativadas.
Adicionado performance_max_placement_view, que retorna impressões dos canais em que os anúncios Performance Max foram veiculados.
AssetGroupListingGroupFilterError.TREE_WAS_INVALID_BEFORE_MUTATION adicionado

Planejamento

(Somente para contas na lista de permissões) Foi adicionado um novo serviço com o método ContentCreatorInsightsService.GenerateCreatorInsights, que permite que os usuários acessem insights sobre os principais criadores de conteúdo do YouTube. Assim, os clientes podem pesquisar criadores com base em uma combinação de segmentação por público-alvo e conteúdo ou insights sobre criadores com uma lista de IDs de canais do YouTube.
Atualizações do AudienceInsightsService.GenerateSuggestedTargetingInsights:
- audience, baseline_audience e data_month foram movidos para audience_definition.
- Adição de audience_description para gerar sugestões de segmentação com base em uma descrição de texto livre usando a IA generativa.
A AudienceInsightsService.GenerateTargetingSuggestionMetrics foi adicionada e retorna métricas de alcance potencial para determinadas combinações de segmentação por público-alvo.

Recomendações

Agora, o RecommendationService.GenerateRecommendations pode ser usado para gerar recomendações sobre sugestões de orçamento otimizado durante a criação da campanha. Basta incluir o tipo de recomendação CAMPAIGN_BUDGET em GenerateRecommendationsRequest.recommendation_types[]. Isso funciona para campanhas Performance Max e de pesquisa.

Relatórios

Os campos summary_row_setting e return_total_results_count de SearchGoogleAdsRequest foram substituídos pelo campo search_settings, cujo tipo é SearchSettings, com os seguintes campos:
- omit_results
- return_summary_row
- return_total_results_count
Foram adicionadas as seguintes métricas sobre cliques inválidos gerais, como os gerados por bots ou rastreadores, que têm padrões irregulares. Elas podem ser consultadas com o relatório campaign.
- metrics.general_invalid_clicks
- metrics.general_invalid_click_rate
Os seguintes valores foram adicionados a QuotaError:
- EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION
- EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION

v17.1.0 (7 de agosto de 2024)

Os novos recursos e atualizações a seguir foram adicionados à v17_1.

Recursos

Com AdGroupAdService.RemoveAutomaticallyCreatedAssets(), você pode remover recursos automáticos específicos vinculados aos anúncios responsivos de pesquisa.

Públicos-alvo

Novos valores de enumeração em UserListCustomerTypeCategory:
- LOYALTY_TIER_1_MEMBERS
- LOYALTY_TIER_2_MEMBERS
- LOYALTY_TIER_3_MEMBERS
- LOYALTY_TIER_4_MEMBERS
- LOYALTY_TIER_5_MEMBERS
- LOYALTY_TIER_6_MEMBERS
- LOYALTY_TIER_7_MEMBERS

Campanhas

ShareablePreviewService.GenerateShareablePreviews() gera os URLs (shareable_preview_url na resposta) para as prévias de anúncios compartilháveis de grupos de recursos ativados e pausados.
- O campo expiration_date_time indica a data de validade dos URLs na resposta.
- Se ocorrer um erro, o método vai retornar partial_failure_error em vez dos URLs.

Histórico de alterações

Novo tipo de recurso de mudança de status: ASSET_GROUP.

Conversões

Novo campo de segmento para a versão da SKAdNetwork: segments.sk_ad_network_version
offline_conversion_upload_conversion_action_summary, que expõe o diagnóstico de upload de conversões no nível da ação de conversão.
As métricas a seguir são adicionadas aos relatórios de diagnóstico off-line para informar o número de conversões enviadas que ainda estão sendo processadas:
- offline_conversion_upload_client_summary
  - pending_event_count
  - pending_rate
- offline_conversion_upload_conversion_action_summary:
  - pending_count

Planejamento

AudienceInsights.GenerateAudienceOverlapInsights(), que aceita um atributo principal de entrada e um conjunto de atributos de público-alvo e retorna as estimativas da sobreposição do alcance potencial do YouTube entre o atributo principal e os atributos do público-alvo.

Relatórios

Suporte para segmentar per_store_view com base em segments.date

Vídeos

Suporte para a recuperação de informações relacionadas às seguintes estratégias de lances padrão para campanhas de vídeo usando relatórios, como ad_group, campaign:
- Campaign.fixed_cpm (CPM fixo (custo por mil impressões))
- Campaign.target_cpv (CPV desejado (custo por visualização))
Campaign.video_campaign_settings, que permite determinar em quais inventários os anúncios em vídeo podem ser veiculados usando os seguintes campos de relatório:
segments.ad_format_type, que permite segmentar os seguintes relatórios com base no tipo de formato de anúncio em vídeo:

v17 (05/06/2024)

Os recursos e mudanças a seguir foram adicionados à versão 17.

Anúncios

AdService.getAd foi removido. Isso alinha o AdService a outros serviços na API Google Ads. Consulte Como buscar objetos para saber a maneira recomendada de buscar anúncios e outros tipos de recursos.
Foram adicionadas mais validações para ImageAdInfo.image_asset relacionadas a dimensões e formato. Os seguintes erros podem ser gerados se a imagem for inválida:
- ImageError.UNEXPECTED_SIZE
- ImageError.FORMAT_NOT_ALLOWED

Recursos

Foi adicionado um novo tipo enumerado: ClickType.AD_IMAGE
Adicionamos os seguintes relatórios com novas métricas para campanhas Performance Max e de pesquisa:
- campaign_aggregate_asset_view
- channel_aggregate_asset_view

Públicos-alvo

OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED adicionado

Jobs em lote

Foi adicionado BatchJobError.REQUEST_TOO_LARGE, que será gerado quando o AddBatchJobOperationsRequest enviado for maior que 10484504 bytes.
Adição de suporte para definir MutateOperation.asset_group_operation ao usar BatchJobService. Assim, você pode usar o processamento em lote para criar e gerenciar campanhas Performance Max inteiras. Confira nosso novo guia dedicado.

Campanhas

A Discovery foi renomeada para Geração de demanda em todos os campos, tipos enumerados e erros de todos os recursos da API Google Ads, como campanhas, anúncios e recursos. Por exemplo, AdvertisingChannelType.DISCOVERY agora é AdvertisingChannelType.DEMAND_GEN.
Adicionamos Campaign.keyword_match_type para que você possa definir o tipo de correspondência de palavra-chave para todas as palavras-chave em uma campanha.

Conversões

Para conversões da SKAdNetwork,
- segments.sk_ad_network_conversion_value foi renomeado como segments.sk_ad_network_fine_conversion_value.
- segments.sk_ad_network_redistributed_fine_conversion_value foi adicionado.
As métricas a seguir são retornadas com a resposta, mesmo quando são zero. Isso as torna consistentes com outras métricas.

Critérios

Adicionado aos seguintes campos para AdGroupCriterion para mostrar se o critério do grupo de anúncios está sendo veiculado ou os motivos pelos quais ele não está veiculando:
- primary_status
- primary_status_reasons
Inclusão de suporte a metrics.search_impression_share para gender_view.
Inclusão de suporte a metrics.phone_calls para keyword_view.

Serviços locais

Adicionado LocalServicesLeadService.AppendLeadConversation(), usado para anexar um novo LocalServicesLeadConversation a LocalServicesLead, que envia as mensagens aos usuários pelos canais apropriados, como SMS, dependendo de como o lead foi criado.
- O tamanho de AppendLeadConversationRequest.conversations é limitado a 1.000.
- Apenas LocalServicesLead com lead_type definido como LeadType.MESSAGE pode ser especificado em Conversation.local_services_lead.
Foram adicionados novos valores de tipo enumerado a ConversationType:
- WHATSAPP para representar uma conversa iniciada pelo WhatsApp.
- ADS_API para representar uma conversa introduzida usando o novo método LocalServicesLeadService.AppendLeadConversation().
Os seguintes campos foram adicionados a local_services_verification_artifact:
- local_services_verification_artifact.insurance_verification_artifact.expiration_date_time
- local_services_verification_artifact.license_verification_artifact.expiration_date_time

Relatórios

Agora é possível selecionar apenas campos relacionados a um produto vinculado ao consultar product_link. A seleção de vários campos de vários produtos vinculados vai gerar QueryError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE. Por exemplo, product_link.advertising_partner.customer e product_link.data_partner.data_partner_id não podem ser selecionados na mesma consulta.
Transmitir um page_size para GoogleAdsService.Search resultará em um erro RequestError.PAGE_SIZE_NOT_SUPPORTED.

Shopping

Foi adicionado um novo relatório shopping_product, que corresponde à página Produtos da interface do Google Ads. Ele oferece suporte para retornar dados relacionados ao estado atual dos produtos das contas do Google Merchant Center vinculadas a uma conta do Google Ads.
- É possível filtrar as métricas do relatório shopping_product usando segments.date ao usar GoogleAdsService.Search ou GoogleAdsService.SearchStream. A segmentação por data não é permitida e vai retornar um erro ShoppingProductError.UNSUPPORTED_DATE_SEGMENTATION.

Metas unificadas

A UserListCustomerTypeService.MutateUserListCustomerTypes() foi adicionada para configurar tipos de clientes de público-alvo.
CustomerLifecycleGoal.lifecycle_goal_customer_definition_settings foi removido. Para configurar as configurações de público-alvo das metas do ciclo de vida do cliente, use UserListCustomerTypeService.MutateUserListCustomerTypes().
- Anexe ou remova uma lista de usuários definindo UserListCustomerType.customer_type_category para UserListCustomerTypeCategory.PURCHASERS para incluir ou excluir a lista de uma definição de cliente atual para as metas do ciclo de vida do cliente, respectivamente. Acesse segmentar seus públicos-alvo para mais detalhes.

Vídeos

Os seguintes valores foram adicionados a ContentLabelType. É possível excluir os seguintes ContentLabelTypes no nível do cliente:
- BRAND_SUITABILITY_CONTENT_FOR_FAMILIES
- BRAND_SUITABILITY_GAMES_FIGHTING
- BRAND_SUITABILITY_GAMES_MATURE
- BRAND_SUITABILITY_HEALTH_SENSITIVE
- BRAND_SUITABILITY_HEALTH_SOURCE_UNDETERMINED
- BRAND_SUITABILITY_NEWS_RECENT
- BRAND_SUITABILITY_NEWS_SENSITIVE
- BRAND_SUITABILITY_NEWS_SOURCE_NOT_FEATURED
- BRAND_SUITABILITY_POLITICS
- BRAND_SUITABILITY_RELIGION
Adição de AdVideoAsset.ad_video_asset_info para oferecer suporte a preferências de inventário para recursos de vídeo ao criar DemandGenVideoResponsiveAdInfo.
(Somente contas na lista de permissões) Campaign.video_brand_safety_suitability tornou-se mutável.

Notas de lançamento arquivadas

Consulte Versões descontinuadas para conferir as Notas de lançamento arquivadas.