Orçamentos flexíveis: conta de administrador

Ícone de ferramentas

Esse script estende os orçamentos flexíveis para a execução de várias contas em uma única conta de administrador. Os orçamentos flexíveis podem ajustar dinamicamente o orçamento diário da sua campanha com um esquema personalizado de distribuição do orçamento.

O script lê uma planilha para cada conta/campanha especificada e o orçamento correspondente (associado às datas de início e término), encontra a campanha, calcula o orçamento para o dia atual, define-o como o orçamento diário da campanha e registra o resultado na planilha. Isso não afetará as campanhas não especificadas na planilha.

Como funciona

O script funciona da mesma forma que o script de orçamento flexível de conta única. A única funcionalidade adicional é que ele suporta várias contas por meio da planilha especificada.

As duas primeiras colunas especificam a campanha para calcular um orçamento, as três próximas especificam as informações de orçamento e a última registra o resultado da execução.

O ID da conta precisa ser de um anunciante, não de uma conta de administrador.

Você pode ter vários orçamentos para a mesma conta/campanha, mas certifique-se de ter apenas um orçamento ativo por vez. Caso contrário, um cálculo de orçamento mais novo pode substituir um mais antigo.

Se uma conta/campanha não for especificada na planilha, o script não definirá um orçamento flexível para ela.

Teste de estratégias de orçamento

O script inclui um código de teste para simular os efeitos da execução em vários dias. Isso dá uma ideia melhor do que acontece quando o script é programado para execução diária durante um período.

Por padrão, este script simula uma distribuição uniforme de orçamento de US $500,00 gastos ao longo de 10 dias.

É possível executar o código de teste chamando testBudgetStrategy em vez de setNewBudget no método principal:

function main() {
  testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  //  setNewBudget(calculateBudgetWeighted);
}

A chamada de função setNewBudget está comentada, indicando que o script está executando o código de teste. Aqui está a saída do exemplo:

Day 1.0 of 10.0, new budget 50.0, cost so far 0.0
Day 2.0 of 10.0, new budget 50.0, cost so far 50.0
Day 3.0 of 10.0, new budget 50.0, cost so far 100.0
Day 4.0 of 10.0, new budget 50.0, cost so far 150.0
Day 5.0 of 10.0, new budget 50.0, cost so far 200.0
Day 6.0 of 10.0, new budget 50.0, cost so far 250.0
Day 7.0 of 10.0, new budget 50.0, cost so far 300.0
Day 8.0 of 10.0, new budget 50.0, cost so far 350.0
Day 9.0 of 10.0, new budget 50.0, cost so far 400.0
Day 10.0 of 10.0, new budget 50.0, cost so far 450.0
Day 11.0 of 10.0, new budget 0.0, cost so far 500.0

A cada dia, um novo orçamento é calculado para garantir que ele seja gasto de maneira uniforme todos os dias. Depois que a cota inicial do orçamento é excedida, o orçamento é definido como zero para interromper os gastos.

É possível alterar a estratégia de orçamento usada mudando a função usada ou modificando a função propriamente dita. O script vem com duas estratégias pré-criadas: calculateBudgetEvenly e calculateBudgetWeighted. O exemplo anterior testou a primeira. Atualize a linha testBudgetStrategy para usar a segunda:

testBudgetStrategy(calculateBudgetWeighted, 10, 500);

Clique em Visualizar e verifique a saída do registro. Essa estratégia aloca menos orçamento no início do período e o aumenta para os próximos dias.

Você pode usar esse método de teste para simular alterações feitas nas funções de cálculo do orçamento e testar sua própria abordagem na distribuição de um orçamento.

Alocação de orçamento

Vamos analisar melhor a estratégia de orçamento calculateBudgetWeighted:

// One calculation logic that distributes remaining budget in a weighted manner
function calculateBudgetWeighted(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / (2 * daysRemaining - 1);
  }
}

Essa função usa os seguintes argumentos:

  • costSoFar: quanto a campanha acumulou em custos desde o startDate até hoje.
  • totalBudget: quanto gastar de startDate a endDate.
  • daysSoFar: quantos dias se passaram de startDate até hoje.
  • totalDays: número total de dias entre startDate e endDate.

Você pode escrever sua própria função, desde que ela use esses argumentos. Usando esses valores, você pode comparar quanto gastou em dinheiro até agora com quanto deve gastar no geral e determinar em que ponto está no momento dentro do cronograma de todo o orçamento.

Em particular, essa estratégia de orçamento descobre quanto orçamento resta (totalBudget - costSoFar) e divide esse valor pelo dobro do número de dias restantes. Ela pondera a distribuição do orçamento mais para o final da campanha. Usando o custo desde startDate, ela também considera "dias fracos", quando você não gasta todo o orçamento definido.

Orçamento na produção

Quando estiver contente com sua estratégia de orçamento, você precisará fazer algumas alterações antes de programar a execução diária desse script.

Primeiro, atualize a planilha para especificar a conta, a campanha, o orçamento, a data de início e a data de término (uma linha para cada orçamento da campanha).

  • ID da conta: ID da conta (no formato xxx-xxx-xxxx) da campanha a que a estratégia de orçamento deve ser aplicada.
  • Nome da campanha: nome da campanha a que a estratégia de orçamento deve ser aplicada.
  • Data de início: data de início da sua estratégia de orçamento. Deve ser a data atual ou um dia no passado.
  • Data de término: último dia para anunciar com esse orçamento.
  • Orçamento total: valor total que você está tentando gastar. Esse valor está na moeda da conta e pode ser excedido dependendo do agendamento de execução do script.

Em seguida, desative o teste e ative a lógica para alterar efetivamente o orçamento:

function main() {
  //  testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  setNewBudget(calculateBudgetWeighted);
}

O resultado de cada campanha é registrado na coluna Execution Result.

Agendamento

Agende este script para ser executado diariamente, à meia-noite ou pouco depois no fuso horário local, para que ele direcione o máximo possível o orçamento do dia seguinte. No entanto, dados de relatórios recuperados, como o custo, podem ter um atraso de cerca de três horas. Por isso, o parâmetro costSoFar pode estar fazendo referência ao total de ontem para um script programado para ser executado após a meia-noite.

Instalação

  • Clique no botão abaixo para criar o script na sua conta do Google Ads.

    Instalar o modelo de script

  • Clique no botão abaixo para fazer uma cópia da planilha modelo.

    Copiar a planilha de modelo

  • Atualize spreadsheet_url no script.

  • Agende o script para ser executado Diariamente.

Código-fonte

// Copyright 2015, Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * @name MCC Flexible Budgets
 *
 * @overview The MCC Flexible Budgets script dynamically adjusts campaign budget
 *     daily for accounts under an MCC account with a custom budget distribution
 *     scheme. See
 *     https://developers.google.com/google-ads/scripts/docs/solutions/manager-flexible-budgets
 *     for more details.
 *
 * @author Google Ads Scripts Team [adwords-scripts@googlegroups.com]
 *
 * @version 2.1
 *
 * @changelog
 * - version 2.1
 *   - Split into info, config, and code.
 *  - version 2.0
 *   - Updated to use new Google Ads scripts features.
 * - version 1.0.4
 *   - Add support for video and shopping campaigns.
 * - version 1.0.3
 *   - Added validation for external spreadsheet setup.
 * - version 1.0.2
 *   - Fix a minor bug in variable naming.
 *   - Use setAmount on the budget instead of campaign.setBudget.
 * - version 1.0.1
 *   - Improvements to time zone handling.
 * - version 1.0
 *   - Released initial version.
 */
/**
 * Configuration to be used for the Flexible Budgets script.
 */
CONFIG = {
  // URL of the default spreadsheet template. This should be a copy of
  // https://docs.google.com/spreadsheets/d/17wocOgrLeRWF1Qi_BjEigCG0qVMebFHrbUS-Vk_kpLg/copy
  // Make sure the sheet is owned by or shared with same Google user executing the script
  'spreadsheet_url': 'YOUR_SPREADSHEET_URL',

  'advanced_options': {
    // Please fix the following variables if you need to reformat the
    // spreadsheet
    // column numbers of each config column. Column A in your spreadsheet has
    // column number of 1, B has number of 2, etc.
    'column': {
      'accountId': 2,
      'campaignName': 3,
      'startDate': 4,
      'endDate': 5,
      'totalBudget': 6,
      'results': 7
    },

    // Actual config (without header and margin) starts from this row
    'config_start_row': 5
  }
};

const SPREADSHEET_URL = CONFIG.spreadsheet_url;
const COLUMN = CONFIG.advanced_options.column;
const CONFIG_START_ROW = CONFIG.advanced_options.config_start_row;

function main() {
  // Uncomment the following function to test your budget strategy function
  // testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  setNewBudget(calculateBudgetWeighted);
}

// Core logic for calculating and setting campaign daily budget
function setNewBudget(budgetFunc) {
  console.log(`Using spreadsheet - ${SPREADSHEET_URL}.`);
  const spreadsheet = validateAndGetSpreadsheet(SPREADSHEET_URL);
  spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
  const sheet = spreadsheet.getSheets()[0];

  const endRow = sheet.getLastRow();

  const mccAccount = AdsApp.currentAccount();
  sheet.getRange(2, 6, 1, 2).setValue(mccAccount.getCustomerId());

  const today = new Date();

  for (let i = CONFIG_START_ROW; i <= endRow; i++) {
    console.log(`Processing row ${i}`);

    const accountId = sheet.getRange(i, COLUMN.accountId).getValue();
    const campaignName = sheet.getRange(i, COLUMN.campaignName).getValue();
    const startDate = new Date(sheet.getRange(i, COLUMN.startDate).getValue());
    const endDate = new Date(sheet.getRange(i, COLUMN.endDate).getValue());
    const totalBudget = sheet.getRange(i, COLUMN.totalBudget).getValue();
    const resultCell = sheet.getRange(i, COLUMN.results);

    const accountIter = AdsManagerApp.accounts().withIds([accountId]).get();
    if (!accountIter.hasNext()) {
      resultCell.setValue('Unknown account');
      continue;
    }
    const account = accountIter.next();
    AdsManagerApp.select(account);

    const campaign = getCampaign(campaignName);
    if (!campaign) {
      resultCell.setValue('Unknown campaign');
      continue;
    }

    if (today < startDate) {
      resultCell.setValue('Budget not started yet');
      continue;
    }
    if (today > endDate) {
      resultCell.setValue('Budget already finished');
      continue;
    }

    const costSoFar = campaign
                          .getStatsFor(
                              getDateStringInTimeZone('yyyyMMdd', startDate),
                              getDateStringInTimeZone('yyyyMMdd', endDate))
                          .getCost();
    const daysSoFar = datediff(startDate, today);
    const totalDays = datediff(startDate, endDate);
    const newBudget = budgetFunc(costSoFar, totalBudget, daysSoFar, totalDays);
    campaign.getBudget().setAmount(newBudget);
    console.log(
        `AccountId=${accountId}, CampaignName=${campaignName}, ` +
        `StartDate=${startDate}, EndDate=${endDate}, ` +
        `CostSoFar=${costSoFar}, DaysSoFar=${daysSoFar}, ` +
        `TotalDays=${totalDays}, NewBudget=${newBudget}'`);
    resultCell.setValue(`Set today's budget to ${newBudget}`);
  }

  // update "Last execution" timestamp
  sheet.getRange(1, 3).setValue(today);
  AdsManagerApp.select(mccAccount);
}

// One calculation logic that distributes remaining budget evenly
function calculateBudgetEvenly(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / daysRemaining;
  }
}

// One calculation logic that distributes remaining budget in a weighted manner
function calculateBudgetWeighted(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / (2 * daysRemaining - 1);
  }
}

// Test function to verify budget calculation logic
function testBudgetStrategy(budgetFunc, totalDays, totalBudget) {
  let daysSoFar = 0;
  let costSoFar = 0;
  while (daysSoFar <= totalDays + 2) {
    const newBudget = budgetFunc(costSoFar, totalBudget, daysSoFar, totalDays);
    console.log(
        `Day ${daysSoFar + 1} of ${totalDays}, ` +
        `new budget ${newBudget}, cost so far ${costSoFar}`);
    costSoFar += newBudget;
    daysSoFar += 1;
  }
}

// Return number of days between two dates, rounded up to nearest whole day.
function datediff(from, to) {
  const millisPerDay = 1000 * 60 * 60 * 24;
  return Math.ceil((to - from) / millisPerDay);
}

// Produces a formatted string representing a given date in a given time zone.
function getDateStringInTimeZone(format, date, timeZone) {
  date = date || new Date();
  timeZone = timeZone || AdsApp.currentAccount().getTimeZone();
  return Utilities.formatDate(date, timeZone, format);
}

/**
 * Finds a campaign by name, whether it is a regular, video, or shopping
 * campaign, by trying all in sequence until it finds one.
 *
 * @param {string} campaignName The campaign name to find.
 * @return {Object} The campaign found, or null if none was found.
 */
function getCampaign(campaignName) {
  const selectors =
      [AdsApp.campaigns(), AdsApp.videoCampaigns(), AdsApp.shoppingCampaigns()];
  for (const selector of selectors) {
    const campaignIter =
        selector.withCondition(`CampaignName = "${campaignName}"`).get();
    if (campaignIter.hasNext()) {
      return campaignIter.next();
    }
  }
  return null;
}

/**
 * Validates the provided spreadsheet URL to make sure that it's set up
 * properly. Throws a descriptive error message if validation fails.
 *
 * @param {string} spreadsheeturl The URL of the spreadsheet to open.
 * @return {Spreadsheet} The spreadsheet object itself, fetched from the URL.
 * @throws {Error} If the spreadsheet URL hasn't been set
 */
function validateAndGetSpreadsheet(spreadsheeturl) {
  if (spreadsheeturl == 'YOUR_SPREADSHEET_URL') {
    throw new Error(
        'Please specify a valid Spreadsheet URL. You can find' +
        ' a link to a template in the associated guide for this script.');
  }
  return SpreadsheetApp.openByUrl(spreadsheeturl);
}