Conexión de las secuencias de comandos de AdWords y la API de calendario avanzada

Las secuencias de comandos de AdWords se han vuelto mucho más útiles gracias al lanzamiento reciente de API avanzadas.

Estas API adicionales permiten que las secuencias de comandos de AdWords accedan a otros servicios de Google como Google analitico y calendario de Google. Cualquiera que esté familiarizado con otros scripts de Google reconocerá estos objetos como los mismos disponibles allí.

Hoy nos centraremos en la API de Calendar y crearemos una integración que le permita monitorear las fechas de inicio y finalización de la campaña a través de su calendario de Google.

Muchas veces, para reuniones o informes, es útil ver las cosas en una vista de semana o mes para que los elementos superpuestos se destaquen. Este script creará entradas en un calendario separado que representa la duración de sus campañas.

Lo primero que recomiendo hacer es crear un nuevo calendario en su cuenta de Google para contener las fechas de inicio y finalización de la campaña. De esta manera, puede compartir fácilmente el calendario con otros miembros del equipo u ocultarlo para reducir el desorden. El mío lo llamé «AdWords», pero puedes nombrarlo como quieras.

Ahora que tiene un lugar para colocar todos sus eventos, comencemos a escribir código. Cuando abra una nueva ventana de secuencias de comandos, verá un nuevo botón junto al botón Vista previa titulado «API avanzadas». Aquí es donde deberá habilitar el uso de la API de calendario antes de continuar.

También deberá habilitar la API en Developers Console. Simplemente haga clic en el enlace en la parte inferior del cuadro de diálogo y siga las instrucciones.

Una vez que todo esté habilitado, vuelva a la ventana de la secuencia de comandos de AdWords y complete el proceso de autorización de la forma habitual. Ahora tendrá acceso a una nueva clase de Calendario en sus guiones. Deberá seguir este proceso de configuración inicial para cada nuevo script que cree.

Lo primero que vamos a necesitar es una función que nos permita encontrar la identificación del calendario a partir del bonito nombre (o resumen) que ingresó anteriormente. Esto fue adaptado de algunos de los códigos de muestra en el sitio para desarrolladores de AdWords Scripts y funciona muy bien.

// Lookup the calendar id given the summary
// If no calendar id is found, an error is raised
function getCalendarId(summary) {
  var calendarList = Calendar.CalendarList.list();
  for(var i in calendarList.items) {
    var cal = calendarList.items[i];
    if(cal.summary === summary) {
      return cal.id;
    }
  }
  throw "No calendar with the summary: '"+summary+"' found.";
}

Ahora que tenemos la identificación del calendario, podemos comenzar a actualizarlo. Este script adoptará un enfoque simple y borrará todas las entradas del calendario cada vez que se ejecute.

Sí, es un poco derrochador, pero no debería importar siempre que tenga menos de 2500 campañas en su MCC. Siempre puede llamar a la función de eliminación varias veces si es necesario, ya que es bastante rápido.

// Removes all the events from a given calendar
function blowAwayTheCalendar(calendarSummary) {
  var calendarId = getCalendarId(calendarSummary);
  var calendarEvents = Calendar.Events.list(calendarId, { maxResults: 2500 } );
  if (calendarEvents.items && calendarEvents.items.length > 0) {
    for(var i = 0; i < calendarEvents.items.length; i++) {
      var calendarEvent = calendarEvents.items[i];
      Calendar.Events.remove(calendarId, calendarEvent.id);
    }
  }
}

El script se ejecutará en cada cuenta que tengamos, examinará todas las campañas y creará eventos de calendario que reflejen las fechas de inicio y finalización de la campaña.

Necesitaremos algo de código para crear el evento. Las cosas más importantes en un evento de calendario son el resumen y las fechas, así que eso es todo lo que me preocupará aquí.

// Creates an event on the given calendar
function createEvent(calendarId,eventSummary,startDate,endDate) {
  var eventData = {
    'summary': eventSummary,
    'description': '', // You can add something here if you wish
    'start': { 'date': formatDate(startDate) },
    'end': { 'date': formatDate(endDate) }
  };
  var maxRetries = 3;
  while(maxRetries > 0) {
    try {
      var calendarEvent = Calendar.Events.insert(eventData, calendarId);
      Logger.log('New event with ID = %s was created.',calendarEvent.getId());
      return calendarEvent.getId();
    } catch(e) {
      maxRetries--;
      Utilities.sleep(1000);
    }
  }
  throw "Could not create calendar event: "+eventSummary;
}

// Helper function for formatting the date
function formatDate(theDate) {
  return Utilities.formatDate(theDate, 
                              AdWordsApp.currentAccount().getTimeZone(), 
                              'yyyy-MM-dd');
}

Con solo unas pocas líneas de código, ahora podemos crear eventos a partir de nuestras campañas de AdWords. Esto creará un nuevo evento de todo el día que comenzará en la fecha de inicio y finalizará en la fecha de finalización. Hay muchos otros parámetros personalizables que puede agregar si lo desea, pero esto funcionará por ahora.

Es posible que observe la lógica de reintento aquí cuando intente crear el evento. Si está ejecutando esto en paralelo con otras cuentas, lo más probable es que se encuentre con el límite de cinco eventos por segundo. La lógica de reintento captura eso y vuelve a intentarlo después de esperar un segundo.

Esto debería ayudar con cualquier problema de cuota. Ahora estamos listos para armar el código para iterar a través de nuestras cuentas y agregar los eventos a nuestro calendario. Podemos usar un comando simple executeInParallel para lograr esto.

// This is the nice name you used when
// creating your calendar.
var CALENDAR_SUMMARY = 'AdWords';

function main() {
  blowAwayTheCalendar(CALENDAR_SUMMARY); // remove all existing entries
  MccApp.accounts().executeInParallel('campaignsToCalender');
}

// Iterates through the campaigns in an account
// and adds a calendar event using the start and 
// optional end date of the campaign.
function campaignsToCalender() {
  var calendarId = getCalendarId(CALENDAR_SUMMARY);
  var accountName = AdWordsApp.currentAccount().getName();
  var campIter = AdWordsApp.campaigns().get();
  while(campIter.hasNext()) {
    var camp = campIter.next();
    var start = camp.getStartDate() ? awDateToDate(camp.getStartDate()) : null;
    if(!start) { continue; } // this shouldn't happen
    var end;
    if(camp.getEndDate()) {
      end = awDateToDate(camp.getEndDate());
    } else {
      // Default campaign length is a year
      // Maybe a few months is better?
      end = new Date(start);
      end.setFullYear(end.getYear()+1);
    }
    // Event name will be Account > Campaign
    var summary = [accountName,camp.getName()].join(' > ');
    var eventId = createEvent(calendarId,summary,start,end);
  }
}

// Helper function to transform AdWordsDate
// objects to normal Date objects.
function awDateToDate(awDate) {
  return new Date(awDate.year, 
                  awDate.month, 
                  awDate.day, 0, 0, 0);
}

Pensamientos finales

Nuestra función principal se vuelve extremadamente simple porque hemos creado funciones para todas las cosas complicadas. Una cosa a tener en cuenta es que, si bien todas las campañas tendrán una fecha de inicio, no todas requieren una fecha de finalización.

En casos como estos, tendrá que decidir qué quiere hacer. En este código, estoy configurando las campañas para una duración de un año solo para poder realizar un seguimiento de ellas, pero usted puede hacer lo que tenga sentido para su cuenta.

Este es solo un ejemplo simple, por supuesto; pero es de esperar que tenga una idea para que continúe explorando estas nuevas API. Por ejemplo, puede ampliar este código para permitirle cambiar eventos en su calendario y hacer que sus campañas se actualicen automáticamente.

Hay muchas otras API avanzadas que se han habilitado recientemente y le animo a que las consulte. Cada vez es más difícil mantenerse al día con el impulso de las secuencias de comandos de AdWords, y no puedo esperar a ver lo que tienen reservado para nosotros a continuación.

Las opiniones expresadas en este artículo pertenecen al autor invitado y no necesariamente a El Blog informatico. Los autores del personal se enumeran aquí.