Exemplos de scripts para gerir grupos de anúncios
As secções seguintes mostram exemplos de scripts que efetuam várias ações em grupos de anúncios.
Adicionar grupos de anúncios
Para adicionar um grupo de anúncios, comece por obter a campanha para adicionar o grupo de anúncios. Utilize o objeto CampaignSelector para selecionar a campanha. A utilização do withIds método proporciona um melhor desempenho do que transmitir o nome da campanha no withCondition método .
Em seguida, chame o novo métodoAdGroupBuilder da campanha para obter um construtor que utiliza para especificar as propriedades do grupo de anúncios. A única propriedade necessária é o nome do grupo de anúncios (veja o withName método), que tem de ser exclusivo na campanha. Se não especificar um valor CPC, a predefinição é o valor mínimo da oferta para a moeda da sua conta. Só tem de especificar o idioma se a campanha não o especificar; caso contrário, herda o valor de linguagem da campanha. Por predefinição, o estado do grupo de anúncios está em pausa.
Chamar o método do build construtor cria o grupo de anúncios de forma assíncrona; Os scripts adicionam o grupo de anúncios em algum momento antes de o script terminar ou se chamar um dos métodos da operação de compilação. Para obter informações sobre este processo, consulte O que é um construtor?
function main() {
// The ID of the campaign to add the ad groups to.
// IDs in Scripts are string integers.
var campaignId = 'CAMPAIGN ID GOES HERE';
var campaign = getCampaign(campaignId);
// Ad groups to add.
var adGroups = [];
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 2.25,
language : 'English' // Required if the campaign doesn't specify a language
});
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 1.25,
language : 'English' // Required if the campaign doesn't specify a language
});
var operations = [];
if (campaign != null)
{
for (var adGroup of adGroups) {
var operation = addAdGroup(
campaign,
adGroup.name,
adGroup.cpc,
adGroup.language);
operations.push(operation);
}
}
else {
Logger.log("Unable to retrieve campaign, " + campaignId);
}
checkBuildStatus(operations, adGroups);
}
// Get the campaign using its ID.
function getCampaign(id) {
var iterator = AdsApp.campaigns()
.withIds([id])
.get();
// Return the campaign if it exists; otherwise, null.
if (iterator.hasNext()) {
return iterator.next();
}
else {
return null;
}
}
// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {
return campaign.newAdGroupBuilder()
.withName(name)
.withCpc(cpc)
.withLanguage(language)
.build();
}
// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {
for (var i = 0; i < operations.length; i++) {
if (!operations[i].isSuccessful()) {
for (var error of operations[i].getErrors()) {
Logger.log(`Failed to add, ${adGroups[i].name}. Error: ${error}`);
}
}
}
}
Obter todos os grupos de anúncios
Para obter todos os grupos de anúncios numa conta, chame primeiro o método do adGroups objeto AdsApp para obter o seletor. Em seguida, chame o método do get seletor para obter um iterador que utiliza para iterar através da lista de grupos de anúncios. Uma vez que o exemplo não especifica filtros, o seletor devolve todos os grupos de anúncios na conta. Para determinar o número de grupos de anúncios no iterador, chame o método do totalNumEntities iterador.
function main() {
// Gets all ad groups in the account.
var iterator = AdsApp.adGroups().get();
// Iterates through the list of ad groups and logs
// each ad group's name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obter um grupo de anúncios por nome
Para obter um grupo de anúncios pelo nome, chame primeiro o método do adGroups objeto AdsApp para obter o seletor. O seletor contém vários métodos de filtro que utiliza para filtrar a lista de grupos de anúncios. Utilize o withCondition método para filtrar os grupos de anúncios para um nome de grupo de anúncios específico. Tenha em atenção que os operandos e operadores são sensíveis às maiúsculas e minúsculas.
Em seguida, chame o método do get seletor para obter o iterador. Os nomes dos grupos de anúncios numa campanha são exclusivos, mas é possível que várias campanhas tenham grupos de anúncios com o mesmo nome. Por este motivo, se filtrar apenas pelo nome, o iterador pode conter mais do que um grupo de anúncios.
Se quiser obter um grupo de anúncios por nome a partir de uma campanha específica, inclua um withCondition método que especifique o nome da campanha (CampaignName = '<campaignnamegoeshere>').
function main() {
// The name of the ad group to get.
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad groups with the specified name.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.get();
// Need a loop because multiple campaigns can have
// an ad group with the same name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obter grupo de anúncios por ID
Se tiver acesso ao ID do grupo de anúncios, utilize-o em alternativa. A utilização de IDs para obter entidades proporciona um melhor desempenho. Em vez de utilizar o withCondition método de filtro, utilize o withIds método . Por exemplo, withIds(['12345']).
function main() {
var adGroupId = '12345';
var iterator = AdsApp.adGroups()
.withIds([adGroupId])
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obter um grupo de anúncios por nome a partir de uma campanha específica
function main() {
var adGroupName = 'AD GROUP NAME GOES HERE';
var campaignName = "CAMPAIGN NAME GOES HERE";
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obter os dados de desempenho de um grupo de anúncios
Para obter as métricas de desempenho de um grupo de anúncios, chame o método getStats do grupo de anúncios. Quando obtém o grupo de anúncios, tem de especificar o intervalo de datas dos dados de métricas que pretende. Pode especificar o intervalo de datas com um literal predefinido, como LAST_MONTH ou HOJE, ou uma data de início e de fim. Para especificar o intervalo de datas, utilize um dos forDateRange métodos quando selecionar o grupo de anúncios (consulte AdGroupSelector).
Para obter uma lista das métricas a que pode aceder, veja o objeto Estatísticas .
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group. You need to specify the date range of the
// performance data you want to get.
var iterator = AdsApp.adGroups()
.forDateRange('LAST_WEEK')
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
// If the ad group is found, log some metrics.
if (iterator.hasNext()) {
var adGroup = iterator.next();
var metrics = adGroup.getStats(); // Gets the performance metrics.
}
}
Colocar um grupo de anúncios em pausa
Quando adiciona um grupo de anúncios, o respetivo estado é Colocado em pausa por predefinição. Para ativar o grupo de anúncios, chame o método do enable grupo de anúncios. Para alterar o estado do grupo de anúncios para Em pausa, chame o método do pause grupo de anúncios. Para determinar o estado do grupo de anúncios, chame os métodos , isPausede isRemoved do isEnabledgrupo de anúncios.
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
adGroup.pause();
}
}