GAWS
TypeScript modules for writing powerful AdWords Scripts quickly & efficiently
Table of Contents
Installation
npm install @gaws/gawsGetting Started
The quickest way to get started is to clone the starter repo. The starter uses Rollup to build the bundle. One of rollup's features is tree shaking. Any functions that are not called will be removed from the bundled output. AdWords Scripts require a "main" function to run. To keep this function in your bundled output, you will need to call it. The easiest way to do this is to use an Immediately Invoked Function Expression (IIFE). e.g.
(function main(){
// your code...
})();But, in some cases, IIFEs can cause a script to miss iterations. So, the safest way to make sure you function remains in your bundled output is to call it then remove the call when you move your script to AdWords.
function main(){
// your code
}
main(); // remove this from your bundled outputUsage
Iterators
An iterator takes as an input an object containing the following AdWords selectors as properties:
-
entity: any AdWords entity i.e.AdWordsApp.keywords(),AdWordsApp.campaigns(), etc. -
conditions: an array of conditions i.e.['Impressions > 100','Clicks > 0'] -
dateRange: either an AdWords date string or object -
order: specifies the ordering of the returned entities -
ids: adds a collection of IDs as a condition -
limit: limits the number of returned entities to the specified value
Only the entity property is required. More information on valid inputs for conditions, date ranges, order values and ids can be found here.
Methods available for Iterators mirror the following native JavaScript Array methods:
everyfilterfindfindIndexforEachmapreduceslicesome
The length property is also available. The following is a very basic example which logs the name of each ad group with at least 100 impressions over the last 7 days:
import { Iterator } from '@gaws/core'
function main() {
const iterator = new Iterator({
entity: AdWordsApp.adGroups(),
conditions: ['Impressions > 100'],
dateRange: 'LAST_7_DAYS'
})
iterator.forEach(group => Logger.log(group.getName()))
}
main() Reports
Documentation coming soon. They are very similar to Iterators. The underlying method logic is the same.
HTML
You can create and import HTML templates for emails (or any other use) and interpolate values similar to handlebars, mustache, etc. Let's set up two html templates and a css file:
<!-- template.html -->
<!doctype html>
<html>
<head>
<style>
{{ style }}
</style>
</head>
<body>
<table>
<thead>
<td>AdGroup</td>
<td>Clicks</td>
<td>Impressions</td>
<td>Conversions</td>
</thead>
<tbody>
{{ rows }}
</tbody>
</table>
</body>
</html>
<!-- row.html -->
<tr>
<td>{{ name }}</td>
<td>{{ clicks }}</td>
<td>{{ impressions }}</td>
<td>{{ conversions }}</td>
</tr>/* styles.css */
table {
color: blue
}You can use the following script to fill out your template and send an email with every ad group that has at least one click in the last 7 days:
import { Iterator } from '@gaws/core'
import { Template } from '@gaws/html'
import template from './template.html'
import row from './row.html'
import styles from './styles.css'
const dateRange = 'LAST_7_DAYS'
function main() {
const cells = new Iterator({
entity: AdWordsApp.adGroups(),
conditions: ['Clicks > 0'],
dateRange: dateRange
}).reduce((str, group) => {
const stats = group.getStatsFor(dateRange)
return str + new Template(row).render({
name: group.getName(),
clicks: stats.getClicks(),
impressions: stats.getImpressions(),
conversions: stats.getConversions()
})
}, '')
const html = new Template(template).render({
style: styles,
rows: cells
})
MailApp.sendEmail({
to: 'example@example.com',
subject: 'testing',
htmlBody: html
})
}
main()