Extensões de local

As extensões de local do Google AdWords exibem o endereço e o número de telefone da sua empresa, além de um marcador do mapa, no texto do anúncio. As extensões de local sofreram algumas mudanças importantes desde que foram lançadas. Até meados de 2014, as informações sobre o local da empresa eram gerenciadas por meio das extensões de local herdadas e do CampaignAdExtensionService. Depois, os locais passaram a ser gerenciados por meio do Google Meu Negócio e vinculados ao Google AdWords ou criados por meio de feeds de extensão de local manuais com upgrade. Agora, os feeds de extensão de local manuais deixaram de ser usados, e todos os locais de empresa devem ser gerenciados pelo Google Meu Negócio, seja por meio do Gerenciador de locais do Google Meu Negócio ou da Google My Business API.

Este guia mostra um exemplo completo de como criar locais de empresa usando a Google My Business API e como vinculá-los aos seus anúncios usando a AdWords API.

Extensões de local com o Google Meu Negócio

O Google Meu Negócio é o repositório central para seus locais de empresa em todos os produtos do Google. Você não precisa se preocupar em manter seus locais do Google Meu Negócio e as extensões de local do Google AdWords em sincronia. Basta configurar os objetos de feed necessários uma única vez. O Google AdWords sincronizará automaticamente as extensões de local com os dados mais recentes da sua conta do Google Meu Negócio.

Esta seção fornece orientações para você criar locais de empresa de forma programática usando a Google My Business API e vinculá-los ao Google AdWords, criando os objetos de feed necessários. Se quiser usar o Gerenciador de locais do Google Meu Negócio para criar seus locais, pule as seções a seguir e vá direto para a etapa 3 no processo seguinte.

Procedimento

Se você não estiver familiarizado com o conceito de feeds no Google AdWords, leia o guia de feeds para sitelinks. Estas instruções foram extraídas desse guia.

As etapas para criar e vincular locais de empresa são as seguintes:

  1. Faça autenticação para chamadas da Google My Business API e da AdWords API (OAuth2.0).

  2. Crie um novo local usando a Google My Business API.

    1. Use o parâmetro accounts.list para recuperar as contas do Google Meu Negócio sobre as quais você tem direitos de propriedade ou de gerenciamento.
    2. Selecione a conta com a qual trabalhará (por exemplo: AccountType = BUSINESS).
    3. Crie o local e especifique uma etiqueta, um endereço, o horário de funcionamento etc.
  3. Crie um novo feed de extensões de local vinculado à sua conta do Google Meu Negócio.

    1. Defina systemFeedGenerationData como um objeto PlacesLocationFeedData que contenha informações sobre sua conta do Google Meu Negócio.
    2. Defina origin como ADWORDS.
    3. Não especifique quaisquer feedAttributes. O Google AdWords criará esses atributos automaticamente para você, pois esse feed é gerado pelo sistema.
    4. Execute uma operação de adição FeedService.mutate.
  4. Associe o feed ao cliente.

    1. Use o feedId da etapa 3.
    2. Use o tipo de marcador 7 para LOCATION.
    3. Use um parâmetro matchingFunction apropriado.
    4. Execute uma operação de adição CustomerFeedService.mutate.
  5. Associe o feed a campanhas ou grupos de anúncios específicos (opcional).

    1. Use o feedId da etapa 3.
    2. Use o tipo de marcador 7 para LOCATION.
    3. Use o parâmetro matchingFunction para filtrar com base na etiqueta da etapa 2c.
    4. Execute uma operação de adição CampaignFeedService.mutate ou AdGroupFeedService.mutate.

Se você estiver familiarizado com os feeds das outras extensões, notará que as etapas acima não incluem a criação de um FeedMapping. Como esse feed é gerado pelo sistema, o Google AdWords já detecta como mapear os atributos do feed para os campos dos marcadores de posição das extensões de local. Assim, não é necessário fornecer essas informações. As seções a seguir explicam como configurar o objeto systemFeedGenerationData ao criar um novo feed (etapa 3a). Veja abaixo um exemplo de código que reúne todas as partes.

Como criar o objeto PlacesLocationFeedData no feed

Quando você configura o atributo systemFeedGenerationData no seu feed, o Google AdWords:

  • vincula suas contas do Google Meu Negócio e do Google AdWords;
  • cria automaticamente os atributos do seu feed;
  • cria automaticamente um FeedMapping para o seu feed e a segmentação por local criterionType (77);
  • limita o conjunto de locais sincronizados a partir da sua conta do Google Meu Negócio (opcional).

Defina os atributos do seu objeto PlacesLocationFeedData da seguinte forma:

Atributo Obrigatório Descrição
emailAddress Sim O endereço de e-mail do proprietário ou de um dos gerentes da sua conta do Google Meu Negócio. Esse endereço de e-mail precisa corresponder ao endereço de e-mail fornecido no oAuthInfo.
oAuthInfo Sim As informações do OAuth2 que concedem acesso à sua conta do Google Meu Negócio para a sua conta do Google AdWords.
businessAccountIdentifier Não O ID da conta da empresa gerenciada cujas localizações serão usadas. Se você estiver usando a Google My Business API, poderá ver esse ID na parte account_id do name da Account. Caso contrário, poderá copiar a parte BUSINESS_ACCOUNT_ID do URL da empresa no formulário:
https://business.google.com/b/BUSINESS_ACCOUNT_ID/...
businessNameFilter Não Nome da empresa a ser sincronizada com o Google AdWords.
categoryFilters Não Categorias das fichas cadastrais a serem sincronizadas com o Google AdWords.
labelFilters Não As etiquetas das fichas cadastrais a serem sincronizadas com o Google AdWords.

Como criar o objeto OAuthInfo no PlacesLocationFeedData

O atributo oAuthInfo no PlacesLocationFeedData fornece as informações necessárias para garantir que sua conta do Google AdWords possa ler localizações a partir da sua conta do Google Meu Negócio.

Defina os atributos do seu objeto OAuthInfo da seguinte forma:

Atributo Valor Descrição
httpMethod GET ou PUT O método HTTP para conseguir informações de autorização.
httpRequestUrl https://www.googleapis.com/auth/plus.business.manage O escopo do OAuth para o Google Meu Negócio. Sempre use o valor mostrado aqui ao configurar um feed do Google Meu Negócio.
httpAuthorizationHeader Bearer OAUTH_ACCESS_TOKEN O cabeçalho de autorização contendo token de acesso do OAuth que concede permissão para a sua conta do Google AdWords fazer leituras a partir da sua conta do Google Meu Negócio. Substitua OAUTH_ACCESS_TOKEN por um token de acesso gerado com credenciais do OAuth para o emailAddress do PlacesLocationFeedData e uma correspondência de escopo httpRequestUrl.

Exemplo de código completo

O código a seguir usa as bibliotecas cliente Java tanto para a Google My Business API quanto para a AdWords API. Consulte as respectivas instruções para configurar sua própria linguagem.

Etapa 1: faça autenticação para chamadas da Google My Business API e da AdWords API (OAuth2.0)

// Creating the default factory and transport (used later)
JsonFactory jsonFactory = JacksonFactory.getDefaultInstance();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

// Load the credentials from the ads.properties file.
// Please note: This example assumes that your AdWords and MyBusiness accounts
// are linked to the same Google account, and that both scopes were used when
// generating the refresh token:
// - https://www.googleapis.com/auth/adwords
// - https://www.googleapis.com/auth/plus.business.manage
// If you are using different Google accounts, you must authenticate
// separately and maintain two credentials (see
// /my-business/content/set-up-java-client).
Credential credential =
    new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .withHttpTransport(httpTransport)
        .fromFile()
        .build()
        .generateCredential();

Etapa 2: crie um novo local usando a Google My Business API

// Initialize GMB.
Mybusiness gmb =
    new Mybusiness.Builder(httpTransport, jsonFactory, credential)
        .setApplicationName(APPLICATION_NAME)
        .build();
// Get list of GMB accounts (2a).
Mybusiness.Accounts.List listAccounts = gmb.accounts().list();
ListAccountsResponse response = listAccounts.execute();
List<Account> accounts = response.getAccounts();

// Find the account to work with (2b). The first BUSINESS account is used
// here, but you can use any other account as well (e.g., PERSONAL).
Account mainAccount = null;
for (Account account : accounts) {
  if (account.getType().equalsIgnoreCase("BUSINESS")) {
    mainAccount = account;
    break;
  }
}
if (mainAccount == null) {
  throw new RuntimeException("Main GMB account not found");
}
// Create the location (2c).
Location location = new Location();
location.setLocationName("My Company");
location.setStoreCode("Company-1");
location.setPrimaryPhone("16505550001");
location.setPrimaryCategory(new Category().setCategoryId("gcid:software_company"));
location.setWebsiteUrl("https://www.example.com/");
// Create an address.
Address address = new Address();
List<String> addressLines = new ArrayList<String>();
addressLines.add("1600 Amphitheatre Pkwy");
address.setAddressLines(addressLines);
address.setLocality("Mountain View");
address.setAdministrativeArea("CA");
address.setCountry("US");
address.setPostalCode("94043");
location.setAddress(address);
// Create business hours (optional).
BusinessHours businessHours = new BusinessHours();
List<TimePeriod> periods = new ArrayList<TimePeriod>();
List<String> days =
    Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");
for (String day : days) {
  TimePeriod period = new TimePeriod();
  period.setOpenDay(day);
  period.setOpenTime("9:00");
  period.setCloseTime("17:00");
  period.setCloseDay(day);
  periods.add(period);
}
businessHours.setPeriods(periods);
location.setRegularHours(businessHours);

// Assign a label to the location (optional). This example uses the AdWords
// customer ID as a label to associate the location with an ad group in AdWords.
// You can use any label value to identify locations, or no label at all
// (e.g., filter by business name or category).
location.setLabels(Collections.singletonList(INSERT_CUSTOMER_ID_HERE));
CreateLocationRequest createLocationRequest = new CreateLocationRequest();
createLocationRequest.setLocation(location);
createLocationRequest.setLanguageCode("en-US");
// Use a random request ID.
createLocationRequest.setRequestId(UUID.randomUUID().toString());
Mybusiness.Accounts.Locations.Create createLocation =
    gmb.accounts().locations().create(mainAccount.getName(),
    createLocationRequest);
Location createdLocation = createLocation.execute();

Etapa 3: crie um novo feed vinculado à sua conta do Google Meu Negócio

// Initialize AdWords.
AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(credential)
    .build();
session.setClientCustomerId(INSERT_CUSTOMER_ID_HERE);
AdWordsServices services = new AdWordsServices();
FeedServiceInterface feedService =
    services.get(session, FeedServiceInterface.class);
// Create the feed object.
Feed gmbFeed = new Feed();
gmbFeed.setName("GMB feed #" + System.currentTimeMillis());
// Create the PlacesLocationFeedData object (3a).
PlacesLocationFeedData feedData = new PlacesLocationFeedData();
feedData.setEmailAddress(GMB_ACCOUNT_EMAIL);
OAuthInfo oAuthInfo = new OAuthInfo();
oAuthInfo.setHttpMethod("GET");
oAuthInfo.setHttpRequestUrl(
    "https://www.googleapis.com/auth/plus.business.manage");
oAuthInfo.setHttpAuthorizationHeader(
    String.format("Bearer %s", credential.getAccessToken()));
feedData.setOAuthInfo(oAuthInfo);
gmbFeed.setSystemFeedGenerationData(feedData);
// Since this feed's feed items will be managed by AdWords,
// you must set its origin to ADWORDS (3b).
gmbFeed.setOrigin(FeedOrigin.ADWORDS);
// Note: No feed attributes for the feed were specified, as this is a
// system-generated feed (3c).
// Create an operation to add the feed.
FeedOperation feedOperation = new FeedOperation();
feedOperation.setOperand(gmbFeed);
feedOperation.setOperator(Operator.ADD);
// Add the feed (3d).
FeedReturnValue addFeedResult = feedService.mutate(
    new FeedOperation[] {feedOperation});
Feed createdFeed = addFeedResult.getValue(0);

Etapa 4: associe o feed ao cliente

CustomerFeedServiceInterface customerFeedService =
    services.get(session, CustomerFeedServiceInterface.class);
CustomerFeed customerFeed = new CustomerFeed();
// Set feedId and placeholder type (4a + 4b).
customerFeed.setFeedId(createdFeed.getId());
customerFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Create a matching function that will always evaluate to true (4c).
Function customerMatchingFunction = new Function();
ConstantOperand constOperand = new ConstantOperand();
constOperand.setType(ConstantOperandConstantType.BOOLEAN);
constOperand.setBooleanValue(true);
customerMatchingFunction.setLhsOperand(
    new FunctionArgumentOperand[] {constOperand});
customerMatchingFunction.setOperator(FunctionOperator.IDENTITY);
customerFeed.setMatchingFunction(customerMatchingFunction);
// Create an operation to add the customer feed.
CustomerFeedOperation customerFeedOperation = new CustomerFeedOperation();
customerFeedOperation.setOperand(customerFeed);
customerFeedOperation.setOperator(Operator.ADD);
// Add the feed (4d).
CustomerFeedReturnValue customerFeedResult = customerFeedService.mutate(
    new CustomerFeedOperation[] {customerFeedOperation});
CustomerFeed createdCustomerFeed = customerFeedResult.getValue(0);

Etapa 5: associe o feed a grupos de anúncios específicos (semelhante para campanhas)

AdGroupFeedServiceInterface adgroupFeedService =
    services.get(session, AdGroupFeedServiceInterface.class);
// Create the ad group feed.
AdGroupFeed adgroupFeed = new AdGroupFeed();
adgroupFeed.setAdGroupId(AD_GROUP_ID);
// Set feedId and placeholder type (5a + 5b).
adgroupFeed.setFeedId(createdFeed.getId());
adgroupFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Define matching function based on the label (5c).
Function matchingFunction = new Function();
String matchingFunctionString = String.format(
    "EQUALS(FeedAttribute[%d, 14], \"%s\")",
    createdFeed.getId(),
    createdLocation.getLabels().get(0));
matchingFunction.setFunctionString(matchingFunctionString);
adgroupFeed.setMatchingFunction(matchingFunction);
// Create an operation to add the ad group feed.
AdGroupFeedOperation operation = new AdGroupFeedOperation();
operation.setOperand(adgroupFeed);
operation.setOperator(Operator.ADD);
// Add the feed (5d).
AdGroupFeedReturnValue result = adgroupFeedService.mutate(
    new AdGroupFeedOperation[]{operation});
AdGroupFeed createdAdGroupFeed = result.getValue(0);

Como filtrar extensões de local

As extensões de local são automaticamente aplicadas a todos os grupos de anúncios e campanhas na conta. Por meio de filtros, é possível aplicar extensões de local a uma campanha ou um grupo de anúncios específico.

Estratégias de filtragem

Com as extensões de local, é possível definir filtros de local em vários níveis da sua conta usando uma série de mecanismos. Use a matchingFunction de um CampaignFeed ou AdGroupFeed se quiser que locais diferentes sejam exibidos em anúncios de diferentes campanhas ou grupos de anúncios.

O filtro mais específico é priorizado. Por exemplo, digamos que você tenha:

  • um CustomerFeed
  • um CampaignFeed para a campanha A
  • um AdGroupFeed para o grupo de anúncios G na campanha A
  • outra campanha B que não apresenta CampaignFeed nem AdGroupFeed

Com essa configuração, você notará o seguinte comportamento (as linhas pontilhadas mostram qual função correspondente é usada para cada anúncio):

  • Os anúncios veiculados para o grupo de anúncios G exibirão apenas extensões de local para itens que corresponderem à função de correspondência do AdGroupFeed.
  • Anúncios veiculados para todos os grupos de anúncios da campanha A exibirão apenas extensões de local para os itens que corresponderem à função de correspondência do CampaignFeed.
  • Anúncios veiculados para a campanha B exibirão extensões de local para itens que corresponderem à função de correspondência do CustomerFeed.

Como usar atributos para filtragem

Os filtros em objetos de feed limitam os itens do feed que são sincronizados por meio dos atributos businessNameFilter, categoryFilters ou labelFilters do objeto PlacesLocationFeedData. Além disso, os filtros em outros objetos determinam quais itens de feed do Google AdWords serão usados como extensões de local para uma determinada combinação de cliente, campanha e grupo de anúncios. Você poderá usar esses filtros se:

  • estiver usando a mesma conta do Google Meu Negócio com várias contas do Google AdWords, e cada conta do Google AdWords estiver logicamente associada a um subconjunto de locais;
  • tiver locais na sua conta do Google Meu Negócio que não queira exibir nunca nos anúncios.

Para contas, campanhas ou grupos de anúncios, você pode especificar matchingFunctions para filtrar com base em qualquer um dos atributos disponíveis no feed de extensões de local. Recomendamos que a filtragem seja feita com base nos seguintes atributos:

  • Etiquetas (marcadores de posição 14): ao especificar etiquetas para cada local no Google Meu Negócio e usá-las para realizar filtragens no Google AdWords, é possível personalizar a filtragem por completo. Por exemplo, você pode usar o ID de cliente ou um ID exclusivo gerado pelo seu aplicativo.

    Se labelFilters for especificado, somente as fichas cadastrais com alguma das etiquetas especificadas estarão classificadas para sincronização com os FeedItems. Se labelFilters não tiver entradas, todas as fichas cadastrais se qualificarão para sincronização. Além disso, todas as etiquetas de uma ficha cadastral do Google Meu Negócio são sincronizadas com um atributo de feed com feedAttributeId = 14 e type = STRING_LIST. Você pode filtrar itens de feed que têm uma ou mais etiquetas especificando uma condição na sua função correspondente desta forma:

    CONTAINS_ANY(FeedAttribute[FeedId,14],{"label1","label2","label3"})
    
  • Nome da empresa (marcador de posição 1): você pode usar o nome da empresa do local para filtragem granular.

  • Categoria da empresa (marcador de posição 9): ao filtrar por categorias, é possível definir correspondências mais amplas ou resolver ambiguidades quando AND combina com o nome da empresa.

Para saber mais sobre filtragem por ID de atributo de feed, consulte o guia de funções correspondentes. Para exemplos de como criar CampaignFeeds e AdGroupFeeds, consulte o guia de feed de sitelinks.

Enviar comentários sobre…

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