Serviços de configuração de extensões

Como usar os serviços de configuração de extensões

Digamos que você esteja anunciando um restaurante no Google AdWords. Você já configurou uma campanha do Google AdWords, mas deseja exibir as seguintes informações adicionais sobre sua empresa:

  • Horário de funcionamento da loja: este link direciona os usuários para http://www.example.com/storehours.
  • Dados nutricionais: este link direciona os usuários para http://www.example.com/menu/nutritiondata, onde são listadas informações nutricionais sobre os itens do cardápio.
  • Happy hours: este link direciona os usuários para http://www.example.com/happyhours e só deve ser exibido nestes horários: das 18h às 21h, de segunda a sexta, e das 17h às 20h, aos sábados.
  • Especial de Ação de Graças: você planeja oferecer um cardápio especial de Ação de Graças de 27 a 28 de novembro. Esse link deve ser exibido apenas de 20 a 27 de novembro para que os usuários possam fazer reservas em http://www.example.com/thanksgiving.

Cada um dos itens acima é uma extensão de anúncio do Google AdWords. Você pode gerenciar extensões usando os serviços de configuração de extensões na Google AdWords API.

Como adicionar extensões de anúncio

As extensões de anúncio podem ser adicionadas no nível da conta, da campanha ou do grupo de anúncios, embora nem todos os tipos de extensão estejam disponíveis em todos os níveis. Para novas extensões de anúncio, use os operadores ADD ou SET. Se o operador SET for usado sem uma extensão de anúncio, uma nova extensão de anúncio será adicionada. As extensões de anúncio têm vários formatos:

Você pode usar sitelinks para criar vinculações a subpáginas específicas do seu site, além da sua página de destino principal, facilitando a navegação dos usuários no seu site.

O snippet de código a seguir mostra como adicionar novas extensões de anúncio a uma campanha usando CampaignExtensionSettingService.

// Get the CampaignExtensionSettingService.
CampaignExtensionSettingService campaignExtensionSettingService =
    (CampaignExtensionSettingService) user.GetService(
         AdWordsService.v201705.CampaignExtensionSettingService);

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;
campaignExtensionSetting.extensionType = FeedType.SITELINK;

SitelinkFeedItem link1 = new SitelinkFeedItem() {
    sitelinkText = "Store Hours",
    sitelinkUrl = "http://www.example.com/storehours"
};

SitelinkFeedItem link2 = new SitelinkFeedItem() {
    sitelinkText = "Thanksgiving Specials",
    sitelinkUrl = "http://www.example.com/thanksgiving",
    startTime = "20141120 000000 EST",
    endTime = "20141127 235959 EST",

    // Target this sitelink for United States only. See
    // https://developers.google.com/adwords/api/docs/appendix/geotargeting
    // for valid geolocation codes.
    geoTargeting = new Location () {
      id = 2840
    };
};

SitelinkFeedItem link3 = new SitelinkFeedItem() {
    sitelinkText = "Nutrition Data",
    sitelinkUrl = "http://www.example.com/menu/nutritiondata"
};

SitelinkFeedItem link4 = new SitelinkFeedItem() {
    sitelinkText = "Happy hours",
    sitelinkUrl = "http://www.example.com/happyhours",
    scheduling = new FeedItemSchedule[] {
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.MONDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.TUESDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.WEDNESDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.THURSDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.FRIDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201705.DayOfWeek.SATURDAY,
            startHour = 17,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        }
    }
};

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] {
        link1, link2, link3, link4
    },
};

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
    operand = campaignExtensionSetting,
    @operator = Operator.ADD,
};

CampaignExtensionSettingReturnValue retVal = campaignExtensionSettingService.mutate(
    new CampaignExtensionSettingOperation[] {operation});

Extensões de chamada

Você pode listar o número de telefone de uma empresa junto com os seus anúncios que permitem a chamada diretamente a partir do anúncio usando uma extensão CallFeedItem. O snippet de código a seguir mostra como fazer isso:

CallFeedItem callFeedItem = new CallFeedItem() {
    callCountryCode = "US",
    callPhoneNumber = "212-565-0000",
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { callFeedItem },
};

Extensões de comentários

Os comentários sobre a empresa podem ser listados com os seus anúncios usando uma extensão de comentários. O snippet de código a seguir mostra como criar uma extensão de comentários:

ReviewFeedItem reviewFeeditem = new ReviewFeedItem() {
    reviewSourceName = "Example Food review magazine",
    reviewSourceUrl =
        "http://www.example.com/reviews/2014/03/the-amazing-example-hotel",
    reviewText = "The best food in New York city!",
    reviewTextExactlyQuoted = true
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { reviewFeeditem },
};

Extensões de frase de destaque

Com a extensão de anúncios de frase de destaque, você pode fornecer detalhes adicionais, como os produtos e serviços que oferece, incluindo texto logo abaixo dos seus anúncios da rede de pesquisa. O snippet de código a seguir mostra como criar uma extensão de frase de destaque:

CalloutFeedItem freeDeliveryCallout = new CalloutFeedItem() {
   calloutText = "Free delivery",
};
CalloutFeedItem kidsCallout = new CalloutFeedItem() {
   calloutText = "Kids eat free",
};

CampaignExtensionSetting campaignExtensionSetting = new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;
campaignExtensionSetting.extensionType = FeedType.CALLOUT;
campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] {
        freeDeliveryCallout, kidsCallout
    }
};

Extensões de aplicativo

Se sua empresa desenvolveu um aplicativo para Android ou iOS com o objetivo de segmentar usuários de dispositivos móveis, você pode exibir links para o aplicativo com os seus anúncios por meio de uma extensão de aplicativo. As extensões de aplicativo são exibidas somente para usuários que fizeram login no Google e que ainda não instalaram seu aplicativo. Ao clicar no link da extensão de aplicativo, o usuário é direcionado à página do Google Play ou do Apple iTunes para fazer o download do seu aplicativo. Este snippet de código mostra como criar uma extensão de aplicativo para um aplicativo no Google Play:

AppFeedItem appFeedItem = new AppFeedItem() {
    appId = "com.example.mobileapp",
    appStore = AppFeedItemAppStore.GOOGLE_PLAY,
    appLinkText = "Install our mobile app!",
    appUrl = "https://play.google.com/store/apps/details?id=com.example.mobileapp"
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { appFeedItem },
};

Extensões de mensagem

As extensões de mensagem permitem que as pessoas vejam seu anúncio, cliquem em um ícone e entrem em contato diretamente com sua empresa por mensagem de texto. Com um simples toque no anúncio, as pessoas podem entrar em contato para marcar uma consulta, fazer uma cotação, pedir informações ou solicitar um serviço. O snippet de código a seguir mostra como fazer isso usando um MessageFeedItem:

MessageFeedItem messageFeedItem = new MessageFeedItem() {
    messageBusinessName = "Travel Here",
    messageCountryCode = "US",
    messagePhoneNumber = "212-565-0000",
    messageText = "I want to know more.",
    messageExtensionText = "Ask us about travel.",
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { messageFeedItem },
};

Extensões de preço

A extensão de preço é um tipo de extensão que fornece aos usuários detalhes comparativos e os preços dos seus produtos ou serviços. Com as extensões de preço, você pode inserir uma lista de serviços, produtos, eventos ou outros itens, com uma lista de preços a serem exibidos ao usuário.

As extensões de preço são totalmente configuráveis e segmentáveis como os outros tipos de extensão, e ainda mostram títulos, informações descritivas e detalhes de preços para no mínimo três e no máximo oito produtos ou serviços que você oferece.

As extensões de preço podem ser inseridas no nível da conta, da campanha ou do grupo de anúncios.

O snippet de código a seguir mostra como criar uma extensão de preço:

// Create the price extension feed item.
PriceFeedItem priceFeedItem = new PriceFeedItem();
priceFeedItem.setPriceExtensionType(PriceExtensionType.SERVICES);

// Price qualifier is optional.
priceFeedItem.setPriceQualifier(PriceExtensionPriceQualifier.FROM);
priceFeedItem.setTrackingUrlTemplate("http://tracker.example.com/?u={lpurl}");
priceFeedItem.setLanguage("en");
FeedItemCampaignTargeting campaignTargeting = new FeedItemCampaignTargeting();
campaignTargeting.setTargetingCampaignId(campaignId);
priceFeedItem.setCampaignTargeting(campaignTargeting);
priceFeedItem.setScheduling(
    new FeedItemScheduling(
        new FeedItemSchedule[] {
          new FeedItemSchedule(DayOfWeek.SUNDAY, 10, MinuteOfHour.ZERO, 18, MinuteOfHour.ZERO),
          new FeedItemSchedule(DayOfWeek.SATURDAY, 10, MinuteOfHour.ZERO, 22, MinuteOfHour.ZERO)
        }));

// To create a price extension, at least three table rows are needed.
List<PriceTableRow> priceTableRows = new ArrayList<>();
String currencyCode = "USD";
priceTableRows.add(
    createPriceTableRow(
        "Scrubs",
        "Body Scrub, Salt Scrub",
        "http://www.example.com/scrubs",
        "http://m.example.com/scrubs",
        60000000,
        currencyCode,
        PriceExtensionPriceUnit.PER_HOUR));
priceTableRows.add(
    createPriceTableRow(
        "Hair Cuts",
        "Once a month",
        "http://www.example.com/haircuts",
        "http://m.example.com/haircuts",
        75000000,
        currencyCode,
        PriceExtensionPriceUnit.PER_MONTH));
priceTableRows.add(
    createPriceTableRow(
        "Skin Care Package",
        "Four times a month",
        "http://www.example.com/skincarepackage",
        null,
        250000000,
        currencyCode,
        PriceExtensionPriceUnit.PER_MONTH));
priceFeedItem.setTableRows(priceTableRows.toArray(new PriceTableRow[priceTableRows.size()]));

// Create your campaign extension settings. This associates the sitelinks
// to your campaign.
CustomerExtensionSetting customerExtensionSetting = new CustomerExtensionSetting();
customerExtensionSetting.setExtensionType(FeedType.PRICE);
ExtensionSetting extensionSetting = new ExtensionSetting();
extensionSetting.setExtensions(new ExtensionFeedItem[] {priceFeedItem});
customerExtensionSetting.setExtensionSetting(extensionSetting);

A referência a createPriceTableRow é definida conforme mostrado abaixo:

/**
 * Creates a new {@link PriceTableRow} with the specified attributes.
 *
 * @param header the header for the row
 * @param description the description for the row
 * @param finalUrl the final URL for the row
 * @param finalMobileUrl the final mobile URL for the row, or null if this field should not be set
 * @param priceInMicros the price for the row, in micros
 * @param currencyCode the currency for the row
 * @param priceUnit the price unit for the row
 * @return a new {@link PriceTableRow}
 */
private static PriceTableRow createPriceTableRow(
    String header,
    String description,
    String finalUrl,
    String finalMobileUrl,
    long priceInMicros,
    String currencyCode,
    PriceExtensionPriceUnit priceUnit) {
  PriceTableRow priceTableRow = new PriceTableRow();
  priceTableRow.setHeader(header);
  priceTableRow.setDescription(description);

  UrlList finalUrls = new UrlList();
  finalUrls.setUrls(new String[] {finalUrl});
  priceTableRow.setFinalUrls(finalUrls);

  if (finalMobileUrl != null) {
    UrlList finalMobileUrls = new UrlList();
    finalMobileUrls.setUrls(new String[] {finalMobileUrl});
    priceTableRow.setFinalMobileUrls(finalMobileUrls);
  }

  MoneyWithCurrency price = new MoneyWithCurrency();
  Money priceMoney = new Money();
  price.setCurrencyCode(currencyCode);
  priceMoney.setMicroAmount(priceInMicros);
  price.setMoney(priceMoney);
  priceTableRow.setPrice(price);
  priceTableRow.setPriceUnit(priceUnit);

  return priceTableRow;
}

Extensões de promoção

As extensões de promoção permitem destacar vendas e outras promoções e, assim, os usuários podem ver como eles podem economizar comprando agora. Existem muitos campos que permitem personalizar exatamente o que aparece na extensão, mas os obrigatórios são:

  • promotionTarget: o texto que aparece no anúncio quando a extensão é exibida.
  • percentOff ou moneyAmountOff: um deles é obrigatório. Eles mostram ao usuário o valor do desconto.

    • percentOff exibe um valor em micros, onde um milhão de micros representa 1%, e é exibido como uma porcentagem quando renderizado. Por exemplo, o valor 10000000 será renderizado como "10%".
    • moneyAmountOff também está em micros. Exige tanto uma moeda quanto um valor em dinheiro.
  • finalUrls: os destinos de URL da sua página de destino se alguém clicar na extensão.

Campos opcionais:

  • occasion: por exemplo, NEW_YEARS ou HALLOWEEN.

    • Ao usar occasion sem usar serviços de configuração de extensão, verifique se os valores correspondem exatamente aos valores de enumeração documentados para PromotionFeedItem.
  • discountModifier: permite que você adicione a palavra "até" à promoção, caso as taxas de promoção sejam variáveis.

    • Ao usar discountModifier sem usar serviços de configuração de extensão, verifique se os valores correspondem exatamente aos valores de enumeração documentados para PromotionFeedItem.
  • promotionCode: para que os usuários insiram e recebam o desconto.

  • ordersOverAmount: para indicar um gasto mínimo de qualificação do usuário para a promoção.

    • Apenas um promotionCode ou ordersOverAmount é permitido por PromotionFeedItem.
  • promotionStart e promotionEnd: garante que a extensão só seja exibida durante o período de promoção. Um formato de data e hora deve ser definido, embora apenas meia-noite seja permitido. Por exemplo, você pode definir promotionStart como "20170601 000000" e promotionEnd como "20170701 000000" para uma promoção veiculada somente em junho.

    • Você pode limpar esses campos definindo o valor especial: "00000101 000000".

Para detalhes sobre o restante dos campos, confira os documentos de PromotionFeedItem.

Veja um exemplo de snippet de código que mostra como criar uma extensão de promoção:

PromotionFeedItem promotionFeedItem = new PromotionFeedItem() {
    promotionTarget = "Wool Socks",
    percentOff = 10000000,
    promotionCode = "WinterSocksDeal",
    finalUrls = new string[] { "http://www.example.com/socks" },
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { promotionFeedItem },
};

Como atualizar extensões de anúncio

Suponha que você tenha decidido alterar o happy hour do seu restaurante aos sábados para o horário das 17h às 22h.

A primeira etapa é recuperar a lista de configurações existentes:

// Get the CampaignExtensionSettingService.
CampaignExtensionSettingService campaignExtensionSettingService =
    (CampaignExtensionSettingService) user.GetService(
         AdWordsService.v201705.CampaignExtensionSettingService);

Selector selector = new Selector() {
    fields = new string[] { "CampaignId", "ExtensionType", "Extensions" },
    predicates = new Predicate[] {
        new Predicate() {
            field = "CampaignId",
            @operator = PredicateOperator.EQUALS,
            values = new string[] {campaignId.ToString()}
        },
        new Predicate() {
            field = "ExtensionType",
            @operator = PredicateOperator.EQUALS,
            values = new string[] {"SITELINK"}
        },
    }
};

CampaignExtensionSettingPage page = campaignExtensionSettingService.get(selector);

Em seguida, atualize o sitelink desejado:

CampaignExtensionSetting campaignExtensionSetting = page.entries[0];
foreach (SitelinkFeedItem siteLink in
     campaignExtensionSetting.extensionSetting.extensions) {
  if (siteLink.sitelinkText == "Happy hours") {
    foreach (FeedItemSchedule schedule in siteLink.scheduling) {
      if (schedule.dayOfWeek == AdWords.v201705.DayOfWeek.SATURDAY) {
         schedule.startHour = 17;
         schedule.startMinute = MinuteOfHour.ZERO;
         schedule.endHour = 22;
         schedule.endMinute = MinuteOfHour.ZERO;
      }
    }
  }
}

Por fim, envie o campaignExtensionSetting modificado para o servidor.

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
  operand = campaignExtensionSetting,
  @operator = Operator.SET,
};

Para impedir que novas configurações substituam as antigas, lembre-se de enviar novamente todos os itens do feed, mesmo que você modifique apenas um deles.

Como remover extensões de anúncio

Nos bastidores, os serviços de configuração de extensão ainda usam feeds para controlar suas extensões de anúncio. Quando você cria uma nova configuração de extensão, o serviço cria itens de feed no feed apropriado e os associa à campanha, ao grupo de anúncios ou à conta fornecida, dependendo do serviço utilizado.

Da mesma forma, quando você remove um ExtensionFeedItem de uma configuração de extensão ou remove a configuração de extensão junto, o serviço remove a associação entre os itens de feed e a entidade anexada, mas não remove os itens de feed porque eles podem estar associados a outra entidade.

Existem duas maneiras de remover a associação entre um item de feed e uma entidade:

  1. Você pode remover toda a configuração de extensão com um operador REMOVE. Isso eliminará a associação entre a entidade e todos os itens de feed na configuração da extensão.
  2. Você pode remover ExtensionFeedItems individuais da configuração de extensão especificando um novo conjunto de ExtensionFeedItems que não contêm aquele que você deseja remover.

Em ambos os casos, os itens de feed subjacentes não são removidos. Portanto, se os itens de feed não estiverem mais associados a nenhuma outra entidade, considere excluir os itens de feed, o que liberará espaço e permitirá que você gere novas extensões no futuro. Como alternativa, você pode reutilizar os itens de feed em outras configurações de extensão.

Se você não remover ou reutilizar itens de feed criados a partir dos serviços de configuração de extensão ao remover as extensões, esses itens de feed se acumularão ao longo do tempo e você talvez acabe atingindo o limite com relação ao número de itens de feed permitidos na sua conta.

Como excluir itens de feed

Se você quiser excluir os itens de feed subjacentes depois de desassociá-los de uma entidade, simplesmente pegue o feedId e feedItemId da extensão excluída e exclua o FeedItem correspondente.

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
  operand = campaignExtensionSetting,
  @operator = Operator.REMOVE,
};

campaignExtensionSettingService.mutate(new CampaignExtensionSettingOperation[] {operation});

List<FeedItemOperation> operations = new List<FeedItemOperation>();
foreach(ExtensionFeedItem extensionFeedItem in
    campaignExtensionSetting.extensionSetting.extensions) {
  FeedItemOperation operation = new FeedItemOperation() {
    @operator = Operator.REMOVE,
    operand = new FeedItem() {
      feedItemId = extensionFeedItem.feedItemId,
      feedId = extensionFeedItem.feedId
    }
  };
  operations.Add(operation);
}

feedItemService.mutate(operations.ToArray());

O primeiro REMOVE, no CampaignExtensionSettingService, remove a associação entre essa extensão e a campanha. O segundo REMOVE, no FeedItemService, remove os itens de feed subjacentes, liberando espaço para que você possa usar novas extensões no futuro.

Como reutilizar itens de feed

Você pode associar o mesmo item de feed a várias entidades. Por exemplo, se desejar que os mesmos sitelinks apareçam em várias campanhas, você poderá associar cada campanha ao mesmo conjunto de itens de feed.

Do mesmo modo, depois de remover uma extensão de anúncio de uma entidade, você pode associar o item de feed subjacente a uma entidade diferente capturando o feedItemId na resposta.

Por exemplo, se você tiver o feedItemId antigo de uma configuração de extensão removida anteriormente armazenado em um storedFeedItemId variável, poderá reutilizá-lo preenchendo apenas o feedItemId no SitelinkFeedItem:

SitelinkFeedItem link = new SitelinkFeedItem() {
  feedItemId = storedFeedItemId
};

CampaignExtensionSetting campaignExtensionSetting = new CampaignExtensionSetting();
campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
  extensions = new ExtensionFeedItem[] {
    link
  }
};

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
  operand = campaignExtensionSetting,
  @operator = Operator.ADD,
};

CampaignExtensionSettingReturnValue retVal = campaignExtensionSettingService.mutate(
    new CampaignExtensionSettingOperation[] {operation});

Opções de segmentação para extensões

Além de usar ExtensionSetting para segmentar uma extensão nos níveis do cliente, da campanha ou do grupo de anúncios, você também pode configurar opções de segmentação em um ExtensionFeedItem individual. Para isso, configure os atributos campaignTargeting, adGroupTargeting, keywordTargeting ou geoTargeting.

Essas opções de segmentação serão combinadas com as propriedades ExtensionSetting para selecionar os itens do feed da extensão que serão usados para uma determinada impressão.

Por exemplo, digamos que você crie um SitelinkFeedItem com as seguintes opções de segmentação:

adGroupTargeting.TargetingAdGroupId = 12345
keywordTargeting.id = 7890

Além disso, você define a restrição de plataforma de AdGroupExtensionSetting como MOBILE.

Ao veicular impressões para esse grupo de anúncios, o Google AdWords só veiculará sitelinks de SitelinkFeedItem se os atributos de impressão atenderem às opções de segmentação nos objetos AdGroupExtensionSetting e SitelinkFeedItem.

Caso Atributos de impressão Resultado
1
  • Código do grupo de anúncios: 12345
  • Palavra-chave: 7890
  • Um usuário de computador
A opção SitelinkFeedItem não será usada porque a plataforma (computador) não atende às opções de segmentação presentes em AdGroupExtensionSetting.
2
  • Código do grupo de anúncios: 12345
  • Palavra-chave: 8910
  • Um usuário de dispositivo móvel
A opção SitelinkFeedItem não será usada porque a palavra-chave (7890) não atende às opções de segmentação presentes em SitelinkFeedItem.
3
  • Código do grupo de anúncios: 12345
  • Palavra-chave: 7890
  • Um usuário de dispositivo móvel
A opção SitelinkFeedItem será usada porque os atributos atendem às opções de segmentação em AdGroupExtensionSetting e SitelinkFeedItem.

Acompanhar o desempenho da extensão de anúncio

Use o Relatório de marcadores de posição ou o Relatório de itens do feed de marcador de posição para acompanhar o desempenho das suas extensões de anúncio. Para identificar suas extensões de anúncio, use a coluna FeedItemId.

Migrar extensões de anúncio para serviços de configuração de extensões

O restante deste guia aborda as vantagens e as desvantagens dos serviços de configuração de extensões para ajudar você a decidir se deve começar a usá-los ou permanecer com os serviços de feed. Ele também descreve como migrar para os novos serviços.

Os serviços de configuração de extensões fornecem uma camada simplificada em comparação com as extensões de anúncio com base em feeds existentes. Veja as vantagens dos novos serviços:

  • Eles são compatíveis com tipos concretos de todas as extensões de anúncio suportadas.
  • Fornecem uma API simplificada que permite gerenciar extensões de anúncio para uma campanha ou um grupo de anúncios.

Devo realizar a migração?

Os serviços de configuração de extensões englobam todos os recursos de extensão de anúncio atualmente disponíveis na interface do usuário do Google AdWords. A maioria dos usuários verá vantagens em gastar algum tempo para recriar os serviços, migrar os dados e usar os serviços simplificados de configuração de extensões. As seções a seguir ajudarão você a decidir se deve ou não migrar para os serviços de configuração de extensões.

Quando é melhor usar os serviços de configuração de extensões?

Se você simplesmente precisa adicionar extensões de anúncio a uma campanha ou a um grupo de anúncios, definir a preferência de dispositivo ou gerenciar a programação dele, recomendamos usar os serviços de configuração de extensões. Outra vantagem do uso desses serviços é que, diferentemente dos serviços de feed, mantemos o esquema e os dados do seu feed. Assim, você não precisará acompanhar a estrutura de feed subjacente.

Quando é melhor usar os serviços legados de feed?

Recomendamos o uso dos serviços legados de feed quando você precisa usar um ou mais dos recursos listados abaixo:

  • Extensões de local: os serviços de configuração de extensões não incluem suporte para extensões de local.
  • Campos personalizados ou funções de correspondência: os serviços de configuração de extensões não são compatíveis com campos personalizados em feeds ou com a criação de funções de correspondência personalizadas.
  • Vários feeds: os serviços de configuração de extensões são compatíveis apenas com um feed por tipo de extensão que é gerenciado pelo sistema.

Etapas da migração

Se você só usou feeds criados na interface do usuário do Google AdWords, pode usar os serviços de configuração de extensões imediatamente.

No entanto, se você criou feeds personalizados com a API, precisará primeiro concluir estas etapas:

  1. Recupere os itens do feed nos seus feeds personalizados.
  2. Identifique os itens do feed que você deseja manter.
  3. Exclua as opções CustomerFeed, CampaignFeed e AdGroupFeed que usam os itens do feed dos feeds personalizados.
  4. Crie as opções CustomerExtensionSetting, CampaignExtensionSetting e AdGroupExtensionSetting que usam os novos ExtensionFeedItem.
  5. (Opcional) Exclua os itens do feed que não estão mais em uso.

As seções abaixo abordam principalmente o upgrade das extensões de anúncio no nível da campanha, mas o mesmo processo pode ser usado no nível do grupo de anúncios.

Recuperar os itens do feed nos seus feeds personalizados

Para recuperar os itens do feed nos seus feeds personalizados, você precisa primeiro identificar todos os feeds personalizados que criou usando a Google AdWords API, como mostrado a seguir:

private Feed[] GetFeeds(AdWordsUser user) {
  FeedService feedService = (FeedService)user.GetService(
      AdWordsService.v201705.FeedService);
  FeedPage page = feedService.query("SELECT Id, Name, Attributes where " +
      "Origin='USER' and FeedStatus='ENABLED'");
  return page.entries;
}

Em seguida, recupere os itens do feed nesses feeds. O exemplo usa sitelinks, mas a abordagem é semelhante para as outras extensões de anúncio.

private FeedItem[] GetFeedItems(AdWordsUser user, long feedId) {
  FeedItemService feedItemService = (FeedItemService) user.GetService(
      AdWordsService.v201705.FeedItemService);
  FeedItemPage page = feedItemService.query(string.Format("Select FeedItemId, " +
      "AttributeValues, Scheduling where Status = 'ENABLED' and FeedId = '{0}'", feedId));
  return page.entries;
}

Para facilitar, carregue os valores em uma classe definida localmente chamada SitelinkFromFeed:

class SiteLinkFromFeed {
  public long FeedId {get;set;}
  public long FeedItemId { get; set; }
  public string Text { get; set; }
  public string Url { get; set; }
  public string[] FinalUrls { get; set; }
  public string[] FinalMobileUrls { get; set; }
  public string TrackingUrlTemplate { get; set; }
  public string Line2 { get; set; }
  public string Line3 { get; set; }
  public FeedItemSchedule[] Scheduling { get; set; }
}

Também é necessário definir algumas constantes para ajudar na análise das opções FeedMapping. Os valores desses marcadores de posição estão na página de marcadores de posição de feeds.

const int PLACEHOLDER_TYPE_SITELINKS = 1;

class SiteLinkFields {
  public const long TEXT = 1;
  public const long URL = 2;
  public const long LINE2 = 3;
  public const long LINE3 = 4;
  public const long FINAL_URLS = 5;
  public const long FINAL_MOBILE_URLS = 6;
  public const long TRACKING_URL_TEMPLATE = 7;
};

Para converter um objeto FeedItem em um SitelinksFromFeed, você precisa recuperar FeedMapping para o feed e, depois, mapear cada atributo para as propriedades de objeto correspondentes:

private Dictionary<long, SiteLinkFromFeed> GetSiteLinksFromFeed(AdWordsUser user,
    long feedId) {
  Dictionary<long, SiteLinkFromFeed> siteLinks =
      new Dictionary<long, SiteLinkFromFeed>();

  Dictionary<long, long> feedMappings = GetFeedMapping(user, feedId,
      PLACEHOLDER_TYPE_SITELINKS);
  FeedItem[] feedItems = GetFeedItems(user, feedId);

  if (feedItems != null) {
    foreach (FeedItem feedItem in feedItems) {
      SiteLinkFromFeed sitelinkFromFeed = new SiteLinkFromFeed() {
        FeedId = feedItem.feedId,
        FeedItemId = feedItem.feedItemId
      };
      foreach (FeedItemAttributeValue attributeValue in feedItem.attributeValues) {
        switch (attributeValue.feedAttributeId) {
          case SiteLinkFields.TEXT:
            sitelinkFromFeed.Text = attributeValue.stringValue;
            break;

          case SiteLinkFields.URL:
            sitelinkFromFeed.Url = attributeValue.stringValue;
            break;

          case SiteLinkFields.FINAL_URLS:
            sitelinkFromFeed.FinalUrls = attributeValue.stringValues;
            break;

          case SiteLinkFields.FINAL_MOBILE_URLS:
            sitelinkFromFeed.FinalMobileUrls = attributeValue.stringValues;
            break;

          case SiteLinkFields.TRACKING_URL_TEMPLATE:
            sitelinkFromFeed.TrackingUrlTemplate = attributeValue.stringValue;
            break;

          case SiteLinkFields.LINE2:
            sitelinkFromFeed.Line2 = attributeValue.stringValue;
            break;

          case SiteLinkFields.LINE3:
            sitelinkFromFeed.Text = attributeValue.stringValue;
            break;
        }
      }
      sitelinkFromFeed.Scheduling = feedItem.scheduling;
      siteLinks.Add(feedItem.feedItemId, sitelinkFromFeed);
    }
  }
  return siteLinks;
}

private Dictionary<long, long> GetFeedMapping(AdWordsUser user, long feedId,
    long placeHolderType) {
  FeedMappingService feedMappingService = (FeedMappingService) user.GetService(
      AdWordsService.v201705.FeedMappingService);
  FeedMappingPage page = feedMappingService.query(string.Format(
      "SELECT FeedMappingId,AttributeFieldMappings where FeedId='{0}' " +
      "and PlaceholderType={1} and Status='ENABLED'",
      feedId, placeHolderType));

  Dictionary<long, long> attributeMappings = new Dictionary<long, long>();

  if (page.entries != null) {
    foreach (FeedMapping feedMapping in page.entries) {
      foreach (AttributeFieldMapping attributeMapping in
          feedMapping.attributeFieldMappings) {
        attributeMappings.Add(attributeMapping.feedAttributeId,
            attributeMapping.fieldId);
      }
    }
  }
  return attributeMappings;
}

Identificar os itens do feed que você deseja manter

Para identificar a lista de itens do feed associados a uma campanha, recupere a opção CampaignFeed associada à campanha e analise a matchingFunction correspondente. Como as funções de correspondência permitem que você crie uma árvore de expressão genérica, criar um analisador para um caso genérico é complicado. Portanto, esse assunto não será abordado neste guia. Nós usaremos o caso mais simples, em que alguns itens do feed de um único feed foram associados a uma campanha. Essa função de correspondência tem o seguinte formato:

FEEDITEM_ID IN (FEEDITEM_ID_1, FEEDITEM_ID_2…)

private CampaignFeed[] GetCampaignFeeds(AdWordsUser user, Feed feed, int placeholderType) {
  CampaignFeedService campaignFeedService = (CampaignFeedService) user.GetService(
      AdWordsService.v201705.CampaignFeedService);

  CampaignFeedPage page = campaignFeedService.query(string.Format(
      "SELECT CampaignId, MatchingFunction, PlaceholderTypes where Status='ENABLED' " +
      "and FeedId = '{0}' and PlaceholderTypes CONTAINS_ANY[{1}]", feed.id, placeholderType));
  return page.entries;
}

private List<long> GetFeedItemsForCampaign(CampaignFeed campaignFeed) {
  List<long> feedItems = new List<long>();
  if (campaignFeed.matchingFunction.lhsOperand.Length == 1 &&
      campaignFeed.matchingFunction.lhsOperand[0] is RequestContextOperand &&
      (campaignFeed.matchingFunction.lhsOperand[0] as
           RequestContextOperand).contextType ==
           RequestContextOperandContextType.FEED_ITEM_ID &&
      campaignFeed.matchingFunction.@operator == FunctionOperator.IN) {
    foreach (ConstantOperand argument in campaignFeed.matchingFunction.rhsOperand) {
      feedItems.Add(argument.longValue);
    }
  }
  return feedItems;
}

Excluir "CampaignFeed" existente

Antes de adicionar configurações de extensões a uma campanha, você precisa excluir o CampaignFeed existente dela. Como o Google AdWords é compatível com apenas um CampaignFeed por tipo de extensão para uma campanha, essa ação é obrigatória. Exclua seu CampaignFeed criado manualmente para que o CampaignExtensionSettingService crie um novo CampaignFeed gerenciado pelo sistema quando você adicionar configurações de extensões.

private CampaignFeed DeleteCampaignFeed(AdWordsUser user, CampaignFeed campaignFeed) {
  CampaignFeedService campaignFeedService = (CampaignFeedService) user.GetService(
      AdWordsService.v201705.CampaignFeedService);

  CampaignFeedOperation operation = new CampaignFeedOperation() {
    operand = campaignFeed,
    @operator = Operator.REMOVE,
  };

  return campaignFeedService.mutate(
       new CampaignFeedOperation[] { operation }).value[0];
}

Adicionar configurações de extensões

Agora, você pode criar configurações de extensões correspondentes aos itens do feed antigos:

private static void CreateExtensionSetting(AdWordsUser user,
    Dictionary<long, SiteLinkFromFeed> feedItems, CampaignFeed campaignFeed,
    List<long> feedItemIds) {
  CampaignExtensionSetting extensionSetting = new CampaignExtensionSetting() {
    campaignId = campaignFeed.campaignId,
    extensionType = FeedType.SITELINK,
    extensionSetting = new ExtensionSetting() {
    }
  };

  List<ExtensionFeedItem> extensionFeedItems = new List<ExtensionFeedItem>();

  foreach (long feedItemId in feedItemIds) {
    SiteLinkFromFeed feedItem = feedItems[feedItemId];
    SitelinkFeedItem newFeedItem = new SitelinkFeedItem() {
      sitelinkText = feedItem.Text,
      sitelinkUrl = feedItem.Url,
      sitelinkFinalUrls = feedItem.FinalUrls,
      sitelinkFinalMobileUrls = feedItem.FinalMobileUrls,
      sitelinkTrackingUrlTemplate = feedItem.TrackingUrlTemplate,
      sitelinkLine2 = feedItem.Line2,
      sitelinkLine3 = feedItem.Line3,
      scheduling = feedItem.Scheduling
    };
    extensionFeedItems.Add(newFeedItem);
  }
  extensionSetting.extensionSetting.extensions = extensionFeedItems.ToArray();

  CampaignExtensionSettingService campaignExtensionSettingService =
      (CampaignExtensionSettingService) user.GetService(
          AdWordsService.v201705.CampaignExtensionSettingService);
  CampaignExtensionSettingOperation operation =
      new CampaignExtensionSettingOperation() {
        operand = extensionSetting,
        @operator = Operator.ADD
      };

  campaignExtensionSettingService.mutate(
      new CampaignExtensionSettingOperation[] {operation});
  return;
}

Lembre-se de que esse processo não desfaz a duplicação das configurações de extensões. Convém melhorar esse código para excluir itens duplicados.

Excluir "FeedItems" antigos

Por fim, exclua os FeedItems antigos:

private void DeleteOldFeedItems(AdWordsUser user, List<long> feedItemIds,
    long feedId) {
  if (feedItemIds.Count == 0) {
    return;
  }
  List<FeedItemOperation> operations = new List<FeedItemOperation>();
  foreach (long feedItemId in feedItemIds) {
    FeedItemOperation operation = new FeedItemOperation() {
      @operator = Operator.REMOVE,
      operand = new FeedItem() {
        feedItemId = feedItemId,
        feedId = feedId
      }
    };
    operations.Add(operation);
  }
  FeedItemService feedItemService = (FeedItemService) user.GetService(
      AdWordsService.v201705.FeedItemService);
  feedItemService.mutate(operations.ToArray());
  return;
}

Essa etapa é opcional, mas recomendamos excluir os itens do feed não utilizados para manter o número de itens ativos do feed dentro dos limites do sistema.

Reunir tudo: Loop principal

O loop principal desse programa corresponde à sequência de etapas discutidas anteriormente:

Feed[] feeds = GetFeeds(user);
foreach (Feed feed in feeds) {
  Dictionary<long, SiteLinkFromFeed> feedItems = GetSiteLinksFromFeed(user, feed.id);
  CampaignFeed[] campaignFeeds = GetCampaignFeeds(user, feed,
      PLACEHOLDER_TYPE_SITELINKS);

  if (campaignFeeds != null) {
    HashSet<long> allFeedItemsToDelete = new HashSet<long>();
    foreach (CampaignFeed campaignFeed in campaignFeeds) {
      // Optional: Replace with custom logic that upgrades only selected
      // feed items.
      List<long> feedItemIds = GetFeedItemsForCampaign(campaignFeed);
      DeleteCampaignFeed(user, campaignFeed);
      CreateExtensionSetting(user, feedItems, campaignFeed, feedItemIds);
      allFeedItemsToDelete.UnionWith(feedItemIds);
    }
    DeleteOldFeedItems(user, new List<long>(allFeedItemsToDelete), feed.id);
  }
}

Exemplos de código

Consulte os exemplos de código a seguir nas nossas bibliotecas cliente para saber mais sobre os serviços de configuração de extensões.

Enviar comentários sobre…

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