How to sync your keywords and ad labels with an AdWords Script

Columnist Daniel Gilbert shares a free script to help solve labeling issues by copying labels within an ad group from ads to keywords or vice versa.

The label functionality in AdWords can sometimes be a bit bewildering, and manually having to label a lot of ads or keywords is a task we wouldn’t wish on anyone.

We’ve all been there: You make a bid adjustment, label some keywords in an ad group to reflect this change, and then when looking at ads within that same ad group, you can’t see the labels. So you set about the mind-numbing chore of copying labels from entity to entity.

Because we feel your pain, my company created a script to solve your labeling issues. It will copy labels within an ad group from ads to keywords or vice versa. And best of all, it’s free!

The script

I have outlined the script code below. Copy the code below into a new blank script in the AdWords Bulk Actions area, and then change the options at the top as I’ve described here.

Script outline

Fill in label names with the names of the labels you want to be copied

Note that this is case-sensitive — type carefully!

• copyLabelsFrom is the type of entity you’re copying labels from.
• copyLabelsTo is the type of entity you’re copying labels to.
• copyLabelsFrom and copyLabelsTo can be any of “Keyword” and “Ad”
• A threshold is the proportion of entities of the type copyLabelsFrom that must be labeled for the entities of the type copyLabelsTo to be labeled.

For instance, if copyLabelsTo is “Keyword” and copyLabelsFrom is “Ad” then:

• 1 means the keywords are only labeled if all ads are labeled.
• 0.9 means the keywords are labeled if at least 90 percent of ads are labeled.
• 0 means the keywords are labeled if at least one ad is labeled.

Including and excluding certain campaigns

campaignNameContains and campaignNameDoesNotContain filter which campaigns the script gets data from.

For example, if campaignNameContains is [“Brand”, “Generic”], then only campaigns with names containing “brand” or “generic” are included. If campaignNameDoesNotContain is [“Display”, “Competitor”] then any campaigns with names containing “display” or “competitor” are ignored.

This next part is not case-sensitive.

Leave campaignNameContains blank, [ ], to include all campaigns.

If you need to put a double quote into campaignNameContains or campaignNameDoesNotContain — if the campaign name itself uses quotation marks — put a backslash, \, before it.

ignorePausedCampaigns, ignorePausedAdGroups and ignorePausedAdsAndKeywords filter which entities the script looks at based on status. They should all be set to “true” if you only want to look at currently active things.

Removed things are always ignored — they’re deleted, so it’s not like you can change them!

I should mention this does not work for shopping, video or universal app campaigns.

AdWords Scripts can only run for 30 minutes. If your account is too big for the script to run, you could run it multiple times.

Use campaignNameContains and campaignNameDoesNotContain to go over different parts of the account each time.

/**

* Copying Labels From Keywords To Ads Or Vice-Versa

*

* If a certain percentage of keywords (or ads) are labelled with a particular

* label within an ad group, the script applies the label to all ads (or

* keywords) in that ad group.

*

* Version: 1.0

* Google AdWords Script maintained on brainlabsdigital.com

*/

//***************************************************************************//

//***************************************************************************//

var labelNames = [‘Label 1’, ‘Label 2’];

// Set which labels should be copied.

// For example, [“January Only”, “February Only”] would only copy

// the labels ‘January Only’ and ‘February Only’.

var copyLabelsFrom = ‘Keyword’;

// Set which type of entity the labels should be copied from.

// This can take any of two possible values: “Ad” and “Keyword”.

var copyLabelsTo = ‘Ad’;

// Set which type of entity the labels should be copied to.

// This can take any of two possible values: “Ad” and “Keyword”,

// and it can’t have the same value as copyLabelsFrom.

var threshold = 0.5;

// The proportion of entities of the type copyLabelsFrom that must be labelled for the

// entities of the type copyLabelsTo to be labelled.

// For instance, if copyLabelsTo is “Keyword” and copyLabelsFrom is “Ad”, then 1 means

// the keywords are only labelled if all ads are labelled.

// 0.9 means the keywords are labelled if at least 90% of ads are labelled.

// 0 means the keywords are labelled if at least one ad is labelled.

var campaignNameDoesNotContain = [];

// Use this if you want to exclude some campaigns.

// For example [“Display”] would ignore any campaigns with ‘Display’ in the name,

// while [“Display”,”Shopping”] would ignore any campaigns with ‘Display’ or

// ‘Shopping’ in the name.

// Leave as [] to not exclude any campaigns.

var campaignNameContains = [];

// Use this if you only want to look at some campaigns.

// For example [“Brand”] would only look at campaigns with ‘Brand’ in the name,

// while [“Brand”,”Generic”] would only look at campaigns with ‘Brand’ or ‘Generic’

// in the name.

// Leave as [] to include all campaigns.

var ignorePausedCampaigns = true;

// Set this to true to only look at currently active campaigns.

// Set to false to also include campaigns that are currently paused.

var ignorePausedAdGroups = true;

// Set this to true to only look at currently active ad groups.

// Set to false to also include ad groups that are currently paused.

var ignorePausedAdsAndKeywords = true;

// Set this to true to only look at currently active keywords and ads.

// Set to false to also include keywords and ads that are currently paused.

//***************************************************************************//

//***************************************************************************//

var countLabelledEntities = {};

var labelChecks = {};

labelNames.forEach(function(labelName) {

labelChecks[labelName] = false;

});

function main()

{

validateEntityTypes(copyLabelsFrom, copyLabelsTo);

validateNumber(“threshold”, threshold, 0, 1);

validateLabelNames(labelNames);

copyLabels();

checkLabelsAreNotUseless();

}

/**

* Works out which proportion of entities are labelled and labels accordingly.

* @return void

*/

function copyLabels()

{

var campaignIds = getEntityIds(‘Campaign’, [], []);

var adGroupIds = getEntityIds(‘AdGroup’, campaignIds, []);

Logger.log(‘Looking at which entities have which labels…’);

for (var i = 0; i < adGroupIds.length; i += 10000) {

var batchOfAdGroupIds = adGroupIds.slice(i, i + 10000);

var reportForCopyLabelsFrom = downloadBottomLevelReport(

copyLabelsFrom,

batchOfAdGroupIds

);

var counts = getCounts(reportForCopyLabelsFrom);

updateLabelChecks(counts);

var ratios = getRatios(counts);

Logger.log(‘Labelling ‘ + copyLabelsTo.toLowerCase() + ‘s, if appropriate…’);

labelEntities(ratios);

logWhatHasBeenLabelled();

}

}

/**

* @param Report report

* @return object (keyed by ad group IDs and then by label name)

*/

function getCounts(report)

{

var counts = {};

var rows = report.rows();

while (rows.hasNext()) {

var row = rows.next();

var adGroupId = row[‘AdGroupId’];

if (!(adGroupId in counts)) {

counts[adGroupId] = {};

counts[adGroupId][‘Total’] = 0;

}

counts[adGroupId][‘Total’] += 1;

if (row[‘Labels’] === “–“) {

var labelsThatTheEntityHas = [];

} else {

var labelsThatTheEntityHas = JSON.parse(row[‘Labels’]);

}

labelsThatTheEntityHas.forEach(function(entityLabelName) {

if (labelNames.indexOf(entityLabelName) > –1) {

if (!(entityLabelName in counts[adGroupId])) {

counts[adGroupId][entityLabelName] = 0;

}

counts[adGroupId][entityLabelName] += 1;

}

});

}

return cleanUpCounts(counts);

}

/**

* Removes any values keyed by an ad group ID whose ad group

* does not have any of the relevant labels

* @param object counts

* @return counts

*/

function cleanUpCounts(counts)

{

for (var adGroupId in counts) {

var hasSomeLabel = false;

labelNames.forEach(function(labelName) {

if (labelName in counts[adGroupId]) {

hasSomeLabel = true;

}

});

if (!hasSomeLabel) {

delete counts[adGroupId];

}

}

return counts;

}

/**

* Calculates ratios from counts

* @param object counts (keyed by ad group IDs and then by label name)

* @return object (keyed in the same way)

*/

function getRatios(counts)

{

var ratios = {};

for (var adGroupId in counts) {

ratios[adGroupId] = {};

labelNames.forEach(function(labelName) {

if (labelName in counts[adGroupId]) {

ratios[adGroupId][labelName] = counts[adGroupId][labelName] / counts[adGroupId][‘Total’];

}

});

}

return ratios;

}

/**

* Breaks everything that needs to be labelled into

* manageable batches and then labels it

* @param object ratios (keyed by ad group IDs and then by label name)

* @return void

*/

function labelEntities(ratios)

{

var batchOfAdGroupIds = Object.keys(ratios);

var batchOfIdsToLabel = getEntityIds(

copyLabelsTo,

batchOfAdGroupIds,

[]

);

for (var j = 0; j < batchOfIdsToLabel.length; j += 10000) {

var subBatchOfIdsToLabel = batchOfIdsToLabel.slice(j, j + 10000);

labelBatchOfEntities(subBatchOfIdsToLabel, ratios);

}

}

/**

* Labels a batch of entities

* @param array batchOfIds

* @param object ratios (keyed by ad group IDs and then by label name)

* @return void

*/

function labelBatchOfEntities(batchOfIds, ratios)

{

var selector = getSelector(copyLabelsTo, batchOfIds);

labelNames.forEach(function(labelName) {

selector = selector.withCondition(“LabelNames CONTAINS_NONE [‘” + labelName + “‘]”);

var iterator = selector.get();

while (iterator.hasNext()) {

var entity = iterator.next();

var adGroupId = entity.getAdGroup().getId();

if (adGroupId in ratios && labelName in ratios[adGroupId]) {

if (ratios[adGroupId][labelName] > threshold) {

entity.applyLabel(labelName);

countLabelledEntities[labelName] += 1;

}

}

}

});

}

/**

* Looks at the current state of countLabelledEntities

* and prints a message with this information

* @return void

*/

function logWhatHasBeenLabelled()

{

for (var labelName in countLabelledEntities) {

var message = countLabelledEntities[labelName] + ” “ + copyLabelsTo.toLowerCase() + “s”;

message += ” have been labelled with the label ‘” + labelName + “‘.”;

Logger.log(message);

}

}

/**

* Looks through the current counts and updates labelChecks

* if something has been labelled with one of the relevant labels

* @param object counts (keyed by ad group IDs and then by label name)

* @return void

*/

function updateLabelChecks(counts)

{

labelNames.forEach(function(labelName) {

for (var adGroupId in counts) {

if (counts[adGroupId][labelName] > 0) {

labelChecks[labelName] = true;

}

}

});

}

/**

* Checks, for each label provided, whether there is

* something labelled with it; if not, it logs a warning message

* @return void

*/

function checkLabelsAreNotUseless()

{

labelNames.forEach(function(labelName) {

if (!labelChecks[labelName]) {

var message = “Warning: there do not seem to be any “ + copyLabelsFrom.toLowerCase() + “s”;

message += ” labelled with the label name ‘” + labelName + “‘.”;

Logger.log(message);

}

});

}

/**

* Downloads a report either for ads or for keywords

* @param string entityType (will be passed copyLabelsFrom)

* @param array adGroupIds

* @return Report

*/

function downloadBottomLevelReport(entityType, adGroupIds)

{

var whereStatement = “WHERE “;

var idForReport = “Id”;

whereStatement += “AdGroupId IN [“ + adGroupIds.join(“,”) + “] AND “;

if (ignorePausedAdsAndKeywords) {

whereStatement += “Status = ENABLED “;

} else {

whereStatement += “Status IN [‘ENABLED’,’PAUSED’] “;

}

var query = “SELECT “;

query += idForReport + “,” + “AdGroupId,Labels “;

query += “FROM “ + getReportType(entityType) + ” “;

query += whereStatement;

query += “DURING LAST_30_DAYS”;

var report = AdWordsApp.report(query);

return report;

}

/**

* This function is pretty general. It gets entity IDs with possible filters.

* @param string entityType any of ‘Campaign’, ‘AdGroup’, ‘Keyword’, ‘Ad’

* @param array oneLevelUpIds array of IDs to filter by, one level above.

* Pass it an empty array if no filter is required.

* @param array twoLevelsUpIds array of IDs to filter by, two levels above.

* It only makes sense to use this for ads

* and for keywords, and even then only if

* oneLevelUpIds has been passed an empty array.

* Pass it an empty array if no filter is required.

* @return array

* @throws error if entity type is not recognised

* or if no entity IDs pass the filters.

*/

function getEntityIds(entityType, oneLevelUpIds, twoLevelsUpIds)

{

var whereStatement = “WHERE “;

var whereStatementsArray = [];

var entityIds = [];

switch (entityType) {

case “Campaign”:

var idForReport = “CampaignId”;

if (ignorePausedCampaigns) {

whereStatement += “CampaignStatus = ENABLED “;

} else {

whereStatement += “CampaignStatus IN [‘ENABLED’,’PAUSED’] “;

}

campaignNameDoesNotContain.forEach(function(word) {

whereStatement += “AND CampaignName DOES_NOT_CONTAIN_IGNORE_CASE ‘” + word.replace(/”/g,‘\\\”‘) + “‘ “;

});

if (campaignNameContains.length === 0) {

whereStatementsArray = [whereStatement];

} else {

campaignNameContains.forEach(function(word) {

whereStatementsArray.push(whereStatement + ‘AND CampaignName CONTAINS_IGNORE_CASE “‘ + word.replace(/”/g,‘\\\”‘) + ‘” ‘);

});

}

break;

case “AdGroup”:

var idForReport = “AdGroupId”;

if (oneLevelUpIds.length > 0) {

var oneLevelUpName = “Campaign”;

whereStatement += oneLevelUpName + “Id IN [“ + oneLevelUpIds.join(“,”) + “] AND “;

}

if (ignorePausedAdGroups) {

whereStatement += “AdGroupStatus = ENABLED “;

} else {

whereStatement += “AdGroupStatus IN [‘ENABLED’,’PAUSED’] “;

}

whereStatementsArray.push(whereStatement);

break;

case “Keyword”: // Fallthrough

case “Ad”:

var idForReport = ‘Id’;

if (oneLevelUpIds.length > 0) {

var oneLevelUpName = “AdGroup”;

whereStatement += oneLevelUpName + “Id IN [“ + oneLevelUpIds.join(“,”) + “] AND “;

}

if (twoLevelsUpIds.length > 0) {

var twoLevelsUpName = “Campaign”;

whereStatement += twoLevelsUpName + “Id IN [“ + twoLevelsUpIds.join(“,”) + “] AND “;

}

if (ignorePausedAdsAndKeywords) {

whereStatement += “Status = ENABLED “;

} else {

whereStatement += “Status IN [‘ENABLED’,’PAUSED’] “;

}

whereStatementsArray.push(whereStatement);

break;

default:

throw new Error(“Type “ + entityType + ” not recognised”);

}

whereStatementsArray.forEach(function(statement) {

var query = “SELECT “;

if (entityType === “Keyword” || entityType === “Ad”) {

query += idForReport + “,” + “AdGroupId “;

} else {

query += idForReport + ” “;

}

query += “FROM “ + getReportType(entityType) + ” “;

query += statement;

query += “DURING LAST_30_DAYS”;

var report = AdWordsApp.report(query);

var rows = report.rows();

while (rows.hasNext()) {

var row = rows.next();

if (entityType === “Keyword” || entityType === “Ad”) {

entityIds.push([row[“AdGroupId”], row[idForReport]]);

} else {

entityIds.push(row[idForReport]);

}

}

});

if (entityIds.length == 0) {

throw new Error(“No “ + entityType + “s found with the given settings.”);

}

if (entityType === “Campaign”) {

Logger.log(“Number of “ + entityType.toLowerCase() + “s found: “ + entityIds.length);

}

return entityIds;

}

/**

* Returns a selector containing entities with the given IDs

* @param string entityType

* @param array batchOfIds

* @return Selector

* @throws error if entity type is not recognised

*/

function getSelector(entityType, batchOfIds)

{

switch (entityType) {

case ‘Campaign’:

var selector = AdWordsApp.campaigns();

break;

case ‘AdGroup’:

var selector = AdWordsApp.adGroups();

break;

case ‘Ad’:

var selector = AdWordsApp.ads();

break;

case ‘Keyword’:

var selector = AdWordsApp.keywords();

break;

default:

throw new Error(“Type ‘” + entityType + “‘ not recognised”);

}

selector = selector.withIds(batchOfIds);

return selector;

}

/**

* Returns the correct name of the report for the given entity

* @param string entityType

* @return string

* @throws error if entity type is not recognised

*/

function getReportType(entityType) {

switch(entityType) {

case “Campaign”:

return “CAMPAIGN_PERFORMANCE_REPORT”;

case “AdGroup”:

return “ADGROUP_PERFORMANCE_REPORT”;

case “Keyword”:

return “KEYWORDS_PERFORMANCE_REPORT”;

case “Ad”:

return “AD_PERFORMANCE_REPORT”;

case “Label”:

return “LABEL_REPORT”;

default:

throw new Error(“Type ‘” + entityType + “” not recognised”);

}

}

/**

* Validates entity types names

* @param string copyLabelsFrom

* @param string copyLabelsTo

* @return void

* @throws error if one of the two entity names is not recognised

* or if they are the same

*/

function validateEntityTypes(copyLabelsFrom, copyLabelsTo)

{

copyLabelsFrom = capitaliseCorrectly(copyLabelsFrom);

copyLabelsTo = capitaliseCorrectly(copyLabelsTo);

if (!((copyLabelsFrom === ‘Ad’ && copyLabelsTo === ‘Keyword’) ||

(copyLabelsFrom === ‘Keyword’ && copyLabelsTo === ‘Ad’))

) {

throw new Error(“copyLabelsFrom and copyLabelsTo cannot be the same.”);

}

}

/**

* Makes the entity type name the right capitalisation

* @param string entityType

* @return string

* @throws error if the entity type name is not recognised

*/

function capitaliseCorrectly(entityType)

{

var lowerCaseName = entityType.toLowerCase().replace(/ /g,“”);

if (lowerCaseName.substr(–1) == “s”) {

lowerCaseName = lowerCaseName.slice(0,–1);

}

var correctCapitalisation = {};

correctCapitalisation[“keyword”] = “Keyword”;

correctCapitalisation[“ad”] = “Ad”;

if (!(lowerCaseName in correctCapitalisation)) {

throw new Error(“Level name ‘” + entityType + “‘ not recognised.”);

}

return correctCapitalisation[lowerCaseName];

}

/**

* Validates a number (to be used for the threshold)

* @param string name

* @param float number

* @param float lowerBound

* @param float upperBound

* @return void

* @throws error if the threshold isn’t right

*/

function validateNumber(name, number, lowerBound, upperBound)

{

if (isNaN(number)) {

throw new Error(name + ” must be a number, ‘” + number + “‘ is not.”);

}

if (number < lowerBound) {

throw new Error(name + ” must be “ + lowerBound + ” or greater, ‘” + number + “‘ is not.”);

}

if (number > upperBound) {

throw new Error(name + ” must be “ + upperBound + ” or lower, ‘” + number + “‘ is not.”);

}

}

/**

* Validates the label names

* @param array labelNames

* @return void

* @throws error if no label in the account has one of the given label names

*/

function validateLabelNames(labelNames)

{

var labels = AdWordsApp.labels()

.withCondition(“Name IN [‘” + labelNames.join(“‘,'”) + “‘]”)

.get();

var existingLabelNames = [];

while (labels.hasNext()) {

var label = labels.next();

existingLabelNames.push(label.getName());

}

labelNames.forEach(function(labelName) {

if (existingLabelNames.indexOf(labelName) > –1) {

countLabelledEntities[labelName] = 0;

} else {

throw new Error(“Could not find the label ‘” + labelName + “‘. Please check it is spelt and capitalised correctly.”)

}

});

}