Introdução aos serviços de feeds

Este guia é uma introdução aos feeds, que são uma maneira genérica e flexível para fornecer e utilizar dados tabulares em uma conta do Google AdWords. Alguns exemplos de recursos do Google AdWords que utilizam dados tabulares são as extensões e os personalizadores de anúncios e o remarketing dinâmico. Usamos extensões de sitelink neste guia como um exemplo para explicar como usar serviços de feeds, mas o processo é semelhante para outros tipos de dados tabulares que usam tipos de marcadores diferentes.

A linguagem Java é utilizada para as amostras de código neste guia. Para ver exemplos em outras linguagens de programação, consulte Exemplos de código.

Cenário do cliente

Suponha que você seja um anunciante que utiliza o Google AdWords para gerar tráfego no seu site. Você quer que os anúncios sejam exibidos com sitelinks para que os usuários possam navegar até as seções do seu site de forma mais rápida.

Veja a seguir alguns dos detalhes referentes a sitelinks que podem ser adicionados aos seus anúncios:

Nome do sitelink URLs finais do sitelink
Página inicial http://www.example.com
Localizador de lojas http://www.example.com/locations
Itens em promoção http://www.example.com/discounts
Suporte http://www.example.com/support
Produtos http://www.example.com/prods
Sobre nós http://www.example.com/about

Repare que os dados são tabulares, ou seja, cada coluna é uma propriedade do sitelink, e cada linha fornece valores para ele.

Serviços de feeds

Há vários serviços inter-relacionados que podem ser usados para criar e gerenciar feeds.

FeedService
Esse serviço é usado para descrever a forma dos seus dados tabulares no Google AdWords: um nome ou título do seu feed (tabela), além dos nomes e tipos das colunas dele.
FeedItemService
Este serviço é usado para preencher seu feed com dados. Cada item do feed representa uma linha na tabela.
FeedMappingService
Esse serviço é usado para especificar como o feed mapeia as colunas da sua tabela para os campos de um determinado recurso do Google AdWords. Neste guia, você verá como mapear um feed que será usado para sitelinks.
CustomerFeedService
Este serviço ativa seu feed em toda a conta do cliente (todas as campanhas e grupos de anúncios).
CampaignFeedService
Este serviço ativa seu feed em toda a campanha (todos os grupos de anúncios dessa campanha).
AdGroupFeedService
Este serviço ativa seu feed em um determinado grupo de anúncios.

Exemplo de código Java

O exemplo de código abaixo demonstra como adicionar um feed de sitelinks e associá-lo a uma campanha usando a biblioteca de cliente Java. Para ver o exemplo de código completo, consulte Exemplos de código.

Adicionar sitelinks a uma campanha consiste nas seguintes etapas:

  1. Criar o feed.
  2. Preencher o feed.
  3. Mapear o feed para os campos de marcador dos sitelinks.
  4. Associar o feed a um cliente, uma campanha ou um grupo de anúncios.
  5. Programar quando os itens de feed precisam ser ativados (opcional).
  6. Segmentar campanhas, grupos de anúncios ou critérios específicos (opcional).


1. Criar o feed

Use o FeedService para descrever a forma dos dados a serem enviados. Isso consiste no nome ou título do feed (tabela) e em um conjunto de atributos de feed (colunas), que tem um nome (cabeçalho da coluna) e um tipo.

No código de amostra, createSiteLinksFeed() usa o FeedService para criar um Feed com instâncias do FeedAttribute apropriadas aos sitelinks:

private static void createSiteLinksFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    String feedName)
    throws RemoteException {
  // Get the FeedService.
  FeedServiceInterface feedService = adWordsServices.get(session, FeedServiceInterface.class);

  // Create attributes.
  FeedAttribute textAttribute = new FeedAttribute();
  textAttribute.setType(FeedAttributeType.STRING);
  textAttribute.setName("Link Text");
  FeedAttribute finalUrlAttribute = new FeedAttribute();
  finalUrlAttribute.setType(FeedAttributeType.URL_LIST);
  finalUrlAttribute.setName("Link Final URLs");
  FeedAttribute line2Attribute = new FeedAttribute();
  line2Attribute.setType(FeedAttributeType.STRING);
  line2Attribute.setName("Line 2");
  FeedAttribute line3Attribute = new FeedAttribute();
  line3Attribute.setType(FeedAttributeType.STRING);
  line3Attribute.setName("Line 3");

  // Create the feed.
  Feed siteLinksFeed = new Feed();
  siteLinksFeed.setName(feedName);
  siteLinksFeed.setAttributes(
      new FeedAttribute[] {textAttribute, finalUrlAttribute, line2Attribute, line3Attribute});
  siteLinksFeed.setOrigin(FeedOrigin.USER);

  // Create operation.
  FeedOperation operation = new FeedOperation();
  operation.setOperand(siteLinksFeed);
  operation.setOperator(Operator.ADD);

  // Add the feed.
  FeedReturnValue result = feedService.mutate(new FeedOperation[] {operation});

  Feed savedFeed = result.getValue()[0];
  siteLinksData.siteLinksFeedId = savedFeed.getId();
  FeedAttribute[] savedAttributes = savedFeed.getAttributes();
  siteLinksData.linkTextFeedAttributeId = savedAttributes[0].getId();
  siteLinksData.linkFinalUrlFeedAttributeId = savedAttributes[1].getId();
  siteLinksData.line2FeedAttributeId = savedAttributes[2].getId();
  siteLinksData.line3FeedAttributeId = savedAttributes[3].getId();
  System.out.printf("Feed with name '%s' and ID %d with linkTextAttributeId %d"
      + " and linkFinalUrlAttributeId %d and line2AttributeId %d"
      + " and line3AttributeId %d was created.%n",
      savedFeed.getName(),
      savedFeed.getId(),
      savedAttributes[0].getId(),
      savedAttributes[1].getId(),
      savedAttributes[2].getId(),
      savedAttributes[3].getId());
}

Para descrever os dados tabulares que serão usados ​​nos sitelinks, o método cria um feed com os seguintes atributos:

  • texto do link
  • URLs finais do link
  • linha 1
  • linha 2
  • linha 3

Definimos um nome e uma origem de feed do FeedOrigin.USER para indicar que os itens dele serão preenchidos pelo anunciante, e não pelo Google AdWords.

Uma operação de modificação é chamada no FeedService para criar o feed. Depois, o FeedService retorna os IDs do feed e dos atributos desse feed. É importante armazená-los para uso futuro em outros serviços. Para simplificar, suponha que um objeto chamado siteLinksData do tipo SiteLinksDataHolder tenha sido criado e que ele contenha os campos apropriados para armazenar os IDs. Usaremos esse objeto nas etapas subsequentes para recuperar os IDs. Você pode criar um objeto semelhante na sua linguagem de implementação.

Nosso feed tem exatamente a quantidade necessária de colunas para sitelinks. No entanto, como veremos mais adiante, você também pode criar um feed com mais colunas do que o necessário para o recurso do Google AdWords. Com isso, é possível usar os valores nas colunas extras para filtrar quais itens de feed (linhas) se aplicam a qual campanha ou grupo de anúncios usando uma função de correspondência.

2. Preencher o feed

Agora que a forma dos dados foi descrita para o Google AdWords, os dados dos sitelinks podem ser preenchidos por meio da adição de itens de feed (linhas) usando o FeedItemService.

Começamos a criar itens de feed com um método auxiliar, o newSiteLinkFeedItemAddOperation(). Esse método auxiliar usa as informações sobre um sitelink e os IDs do atributo do feed para preencher um novo item. Em seguida, o novo item é incluído em uma operação ADD e retornado.

Para entender como criar um FeedItem, lembre-se desta forma de caracterizar uma tabela: cada linha é um conjunto de células, e cada célula está localizada em uma determinada coluna e contém algum conteúdo. Da mesma forma, um FeedItem (linha) é um conjunto de instâncias de FeedItemAttributeValue (células), e cada FeedItemAttributeValue (célula) tem o ID de um FeedAttribute (a coluna na qual a célula está localizada) e um stringValue (o conteúdo da célula, se for ela uma string).

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3) {
  return newSiteLinkFeedItemAddOperation(siteLinksData, text, finalUrl, line2, line3, null);
}

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3,
    Long locationId) {
  // Create the FeedItemAttributeValues for our text values.
  FeedItemAttributeValue linkTextAttributeValue = new FeedItemAttributeValue();
  linkTextAttributeValue.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextAttributeValue.setStringValue(text);
  FeedItemAttributeValue linkFinalUrlAttributeValue = new FeedItemAttributeValue();
  linkFinalUrlAttributeValue.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlAttributeValue.setStringValues(new String[] {finalUrl});
  FeedItemAttributeValue line2TextAttributeValue = new FeedItemAttributeValue();
  line2TextAttributeValue.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2TextAttributeValue.setStringValue(line2);
  FeedItemAttributeValue line3TextAttributeValue = new FeedItemAttributeValue();
  line3TextAttributeValue.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3TextAttributeValue.setStringValue(line3);

  // Create the feed item and operation.
  FeedItem item = new FeedItem();
  item.setFeedId(siteLinksData.siteLinksFeedId);
  item.setAttributeValues(new FeedItemAttributeValue[] {linkTextAttributeValue,
      linkFinalUrlAttributeValue, line2TextAttributeValue, line3TextAttributeValue});

  // OPTIONAL: Use geographical targeting on a feed item.
  // IDs can be found in the documentation or retrieved with the
  // LocationCriterionService.
  if (locationId != null) {
    Location location = new Location();
    location.setId(locationId);
    item.setGeoTargeting(location);
    // OPTIONAL: Restrict targeting only to people physically within the location.
    FeedItemGeoRestriction geoTargetingRestriction = new FeedItemGeoRestriction();
    geoTargetingRestriction.setGeoRestriction(GeoRestriction.LOCATION_OF_PRESENCE);
    item.setGeoTargetingRestriction(geoTargetingRestriction);
  }

  // Optional: use item.setStartTime() and item.setEndTime() to specify the
  // time period for the feed to deliver.  The example below will make the feed
  // start now and stop in one month.
  // Make sure you specify the DateTime in the customer's time zone.  You can
  // retrieve this from customer.getDateTimeZone().
  //   item.setStartTime(new DateTime(customerTimeZone).toString("yyyyMMdd HHmmss"));
  //   item.setEndTime(new DateTime(customerTimeZone).plusMonths(1).toString("yyyyMMdd HHmmss"));

  // Optional: use item.setScheduling() to specify time and days of the week for feed to deliver.
  FeedItemOperation operation = new FeedItemOperation();
  operation.setOperand(item);
  operation.setOperator(Operator.ADD);
  return operation;
}

Em seguida, definimos o método createSiteLinksFeedItems() que cria todos os itens de feed e as operações que os incluem. Para isso, chamamos nosso método auxiliar com informações diferentes para cada sitelink que gostaríamos de criar.

Os itens de feed retornados pela chamada de modificação incluem IDs que serão armazenados em siteLinksData para uso posterior. Novamente, suponha que esse objeto já tenha sido criado e que contenha os campos apropriados para armazenar os IDs.

private static void createSiteLinksFeedItems(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // Get the FeedItemService.
  FeedItemServiceInterface feedItemService =
      adWordsServices.get(session, FeedItemServiceInterface.class);

  // Create operations to add FeedItems.
  FeedItemOperation home = newSiteLinkFeedItemAddOperation(siteLinksData, "Home",
      "http://www.example.com", "Home line 2", "Home line 3");
  FeedItemOperation stores = newSiteLinkFeedItemAddOperation(siteLinksData, "Stores",
      "http://www.example.com/stores", "Stores line 2", "Stores line 3");
  FeedItemOperation onSale = newSiteLinkFeedItemAddOperation(siteLinksData, "On Sale",
      "http://www.example.com/sale", "On Sale line 2", "On Sale line 3");
  FeedItemOperation support = newSiteLinkFeedItemAddOperation(siteLinksData, "Support",
      "http://www.example.com/support", "Support line 2", "Support line 3");
  FeedItemOperation products = newSiteLinkFeedItemAddOperation(siteLinksData, "Products",
      "http://www.example.com/prods", "Products line 2", "Products line 3");
  // This site link is using geographical targeting by specifying the
  // criterion ID for California.
  FeedItemOperation aboutUs = newSiteLinkFeedItemAddOperation(siteLinksData, "About Us",
      "http://www.example.com/about", "About Us line 2", "About Us line 3", 21137L);

  FeedItemOperation[] operations =
      new FeedItemOperation[] {home, stores, onSale, support, products, aboutUs};

  FeedItemReturnValue result = feedItemService.mutate(operations);
  for (FeedItem item : result.getValue()) {
    System.out.printf("FeedItem with feedItemId %d was added.%n", item.getFeedItemId());
    siteLinksData.siteLinkFeedItemIds.add(item.getFeedItemId());
  }
}

3. Mapear para marcadores

Existe, para cada recurso compatível do Google AdWords que utiliza dados tabulares, um tipo de marcador que especifica os campos e tipos de dados exigidos. O FeedMappingService é usado com o objetivo de mapear um feed para um tipo de marcador e indicar como esse feed deve ser usado, além de mapear alguns atributos do feed (colunas) para os campos do marcador e indicar como esses atributos devem ser interpretados no recurso específico do Google AdWords.

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_SITELINKS = 1;

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_FIELD_SITELINK_LINK_TEXT = 1;
private static final int PLACEHOLDER_FIELD_SITELINK_FINAL_URL = 5;
private static final int PLACEHOLDER_FIELD_LINE_2_TEXT = 3;
private static final int PLACEHOLDER_FIELD_LINE_3_TEXT = 4;

private static void createSiteLinksFeedMapping(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // Get the FeedItemService.
  FeedMappingServiceInterface feedMappingService =
      adWordsServices.get(session, FeedMappingServiceInterface.class);

  // Map the FeedAttributeIds to the fieldId constants.
  AttributeFieldMapping linkTextFieldMapping = new AttributeFieldMapping();
  linkTextFieldMapping.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_LINK_TEXT);
  AttributeFieldMapping linkFinalUrlFieldMapping = new AttributeFieldMapping();
  linkFinalUrlFieldMapping.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_FINAL_URL);
  AttributeFieldMapping line2FieldMapping = new AttributeFieldMapping();
  line2FieldMapping.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_2_TEXT);
  AttributeFieldMapping line3FieldMapping = new AttributeFieldMapping();
  line3FieldMapping.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_3_TEXT);

  // Create the FeedMapping and operation.
  FeedMapping feedMapping = new FeedMapping();
  feedMapping.setPlaceholderType(PLACEHOLDER_SITELINKS);
  feedMapping.setFeedId(siteLinksData.siteLinksFeedId);
  feedMapping.setAttributeFieldMappings(new AttributeFieldMapping[] {linkTextFieldMapping,
      linkFinalUrlFieldMapping, line2FieldMapping, line3FieldMapping});
  FeedMappingOperation operation = new FeedMappingOperation();
  operation.setOperand(feedMapping);
  operation.setOperator(Operator.ADD);

  // Save the field mapping.
  FeedMappingReturnValue result =
      feedMappingService.mutate(new FeedMappingOperation[] {operation});
  for (FeedMapping savedFeedMapping : result.getValue()) {
    System.out.printf(
        "Feed mapping with ID %d and placeholderType %d was saved for feed with ID %d.%n",
        savedFeedMapping.getFeedMappingId(), savedFeedMapping.getPlaceholderType(),
        savedFeedMapping.getFeedId());
  }
}

Nesse exemplo, o método configura o feed a ser usado nos sitelinks definindo um tipo de marcador no FeedMapping como a constante PLACEHOLDER_SITELINKS. O valor dessa constante é 1. O método também mapeia os atributos do feed para os campos de marcadores necessários nos sitelinks. Esse mapeamento indica ao Google AdWords quais atributos (colunas) correspondem a quais aspectos dos sitelinks.

Nem todos os atributos precisam ser mapeados para um campo de marcador. Conforme observado anteriormente, um feed pode ter mais atributos do que o exigido pelo recurso do Google AdWords. Esses atributos adicionais podem ser úteis para filtrar os itens de feed usando uma função de correspondência.

É possível usar o mesmo feed em mais de um FeedMapping. Isso pode ser útil se vários recursos do Google AdWords exigirem dados tabulares semelhantes.

4. Associar a um cliente, uma campanha ou um grupo de anúncios

Nesse momento, o feed já estará pronto para ser usado nos sitelinks. A última etapa é associá-lo a um cliente (CustomerFeedService), uma campanha (CampaignFeedService) ou um grupo de anúncios (AdGroupFeedService) a fim de ativar os sitelinks para o conjunto de anúncios específico.

A opção por associar ou não um feed a um cliente, uma campanha ou um grupo de anúncios se baseia nos dados contidos no seu feed e no nível de controle que você quer ter. Usando novamente os sitelinks como exemplo, se todos os grupos de anúncios em uma campanha exibirem os mesmos sitelinks, associe o feed à campanha. Da mesma forma, se você quiser que os sitelinks sejam usados em todas as campanhas, associe o feed à conta. Se vários grupos de anúncios na mesma campanha mostrarem sitelinks diferentes, associe o feed separadamente apenas a grupos específicos.

Ao associar um feed, você pode filtrar quais itens (linhas) serão ativados para o cliente, a campanha ou o grupo de anúncios em questão. Por exemplo, é possível ter um único feed em que alguns itens são usados ​​para uma campanha devido a aplicação de um filtro, outros itens são usados ​​para outra campanha devido à aplicação de outro filtro, e assim por diante. Após os filtros serem aplicados, uma função de correspondência é criada e avaliada para cada item do feed.

private static void createSiteLinksCampaignFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    Long campaignId)
    throws RemoteException {
  // Get the CampaignFeedService.
  CampaignFeedServiceInterface campaignFeedService =
      adWordsServices.get(session, CampaignFeedServiceInterface.class);

  // Construct a matching function that associates the sitelink feed items to the campaign, and
  // sets the device preference to mobile. See the matching function guide at
  // https://developers.google.com/adwords/api/docs/guides/feed-matching-functions
  // for more details.
  String matchingFunctionString = String.format(
      "AND( IN(FEED_ITEM_ID, {%s}), EQUALS(CONTEXT.DEVICE, 'Mobile') )",
      Joiner.on(',').join(siteLinksData.siteLinkFeedItemIds));

  CampaignFeed campaignFeed = new CampaignFeed();
  campaignFeed.setFeedId(siteLinksData.siteLinksFeedId);
  campaignFeed.setCampaignId(campaignId);

  Function matchingFunction = new Function();
  matchingFunction.setFunctionString(matchingFunctionString);

  campaignFeed.setMatchingFunction(matchingFunction);
  // Specifying placeholder types on the CampaignFeed allows the same feed
  // to be used for different placeholders in different Campaigns.
  campaignFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_SITELINKS});

  CampaignFeedOperation operation = new CampaignFeedOperation();
  operation.setOperand(campaignFeed);
  operation.setOperator(Operator.ADD);
  CampaignFeedReturnValue result =
      campaignFeedService.mutate(new CampaignFeedOperation[] {operation});
  for (CampaignFeed savedCampaignFeed : result.getValue()) {
    System.out.printf("Campaign with ID %d was associated with feed with ID %d.%n",
        savedCampaignFeed.getCampaignId(), savedCampaignFeed.getFeedId());
  }
}

Esse método cria uma associação entre uma campanha e um feed. Há dois trechos desses dados configurados com essa associação: os tipos de marcador e a função de correspondência (filtro).

Talvez você se pergunte por que o tipo de marcador (neste exemplo, sitelinks) precisa ser configurado novamente para o CampaignFeed quando já havia sido configurado no mapeamento do feed. O motivo é o seguinte: exigir que os marcadores sejam configurados novamente oferece a flexibilidade para que um feed com vários mapeamentos seja usado apenas para alguns tipos de marcadores em algumas campanhas e para outros tipos em outras campanhas.

Definir uma função de correspondência no CampaignFeed indica ao sistema de veiculação quais itens de feed (linhas) usar como sitelinks. Consulte o guia sobre funções de correspondência para mais detalhes. Nesse exemplo, usamos FEED_ITEM_ID como RequestContextOperand na nossa Function de correspondência. No entanto, poderíamos ter aplicado outro tipo de RequestContextOperand ou até mesmo ter feito a correspondência com um FeedAttributeOperand, como FeedAttributeId.

O mesmo processo funciona para grupos de anúncios e clientes. Você pode conectar os feeds ao criar um AdGroupFeed com o AdGroupFeedService ou um CustomerFeed usando o CustomerFeedService.

5. Programar itens de feed (opcional)

Como alternativa, você pode especificar os dias e horários em que os itens de feed são ativados definindo o atributo schedules do item. Basta definir schedules como um FeedItemScheduling que contenha um FeedItemSchedule para cada dia da semana e horário de início/término nos quais você gostaria de ativar o item.

Para remover toda a programação de um item de feed, defina os schedules dele como um objeto FeedItemScheduling com um conjunto feedItemSchedules vazio.

Para ver um exemplo de como criar um FeedItemSchedule, confira o snippet de código para atualizar as extensões de anúncio.

6. Definir a segmentação para itens de feed (opcional)

A partir da versão 201802, você pode usar o FeedItemTargetService para que os itens de feed individuais segmentem somente campanhas, grupos de anúncios ou critérios específicos.

Por exemplo, se você quiser que um determinado item de feed seja aplicado a um grupo de anúncios em uma campanha, crie um FeedItemAdGroupTarget que inclua feedId, feedItemId e adGroupId. O FeedItemAdGroupTarget garante que o item seja veiculado somente nesse grupo.

Lembre-se de que essa segmentação é apenas restritiva, o que significa que a entidade segmentada precisa já estar incluída na função de correspondência configurada anteriormente. Configurar um FeedItemTarget limitará a exibição do item de feed em uma entidade específica, mas não expandirá a função de correspondência para incluir essa entidade caso você ainda não a tenha adicionado.

Como remover itens de feed

Para remover um item do feed, defina o status dele como REMOVED. Os itens removidos que não tiverem estatísticas associadas serão excluídos permanentemente após algum tempo.

Exemplos de código

Para saber mais sobre os serviços de feeds, veja os exemplos de código a seguir nas nossas bibliotecas de cliente.

Biblioteca Exemplo de AddSitelinksUsingFeeds
Java AddSitelinksUsingFeeds.java
Perl add_site_links_using_feeds.pl
PHP AddSitelinksUsingFeeds.php
Python add_site_links_using_feeds.py
Ruby add_site_links_using_feeds.rb
C# AddSitelinksUsingFeeds.cs
VB.NET AddSitelinksUsingFeeds.vb

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.