Google Ads 관리자 계정용 링크 검사기 스크립트는 단일 계정 링크 검사기 스크립트를 확장하여 관리자 계정의 여러 계정에 대해 실행합니다.
웹사이트가 발전함에 따라 새 페이지가 추가되고 오래된 페이지가 게시 중단되며 링크가 깨지고 수정됩니다. Google Ads 캠페인과 웹사이트의 동기화 상태를 유지하는 일은 많은 광고주가 계속하는 싸움입니다. 실시간 광고가 존재하지 않는 페이지를 가리킬 수 있으며, 광고주는 404 오류가 발생하는 클릭에 대해 비용을 지불하게 됩니다.
링크 검사 프로그램은 모든 광고, 키워드 및 사이트링크를 반복하고, URL에서 '페이지를 찾을 수 없음' 또는 다른 유형의 오류 응답을 생성하지 않는지 확인하고, 오류 응답이 발견되면 이메일을 보내고, 분석 결과를 스프레드시트에 저장하여 이 문제를 해결합니다.
일부 계정에는 실행 시간 제한 또는 quotas으로 인해 한 번의 실행으로 모두 확인할 수 없는 많은 수의 URL이 있을 수 있습니다. 이 스크립트는 여러 실행에 걸쳐 진행 상황을 추적하고 이전에 확인하지 않은 URL만 확인하여 이러한 사례를 처리하도록 설계되었습니다. 이 스크립트는 여러 실행이 완료되도록 하는 경우에도 모든 URL을 통과하는 하나의 전체 패스를 지칭하기 위해 '분석'이라는 용어를 사용합니다.
구성
스크립트의 기본 옵션은 스프레드시트에서 설정할 수 있습니다.
- 범위
- 스크립트가 광고, 키워드, 사이트링크를 확인하는지와 일시중지된 경우에도 스크립트가 이를 확인하는지 여부를 결정합니다. 대부분의 사용자는 모든 URL을 확인하기 위해 세 가지를 모두 포함해야 하지만, 일반적으로는 일시중지된 항목을 확인할 필요는 없습니다.
- 유효한 응답 코드
- 유효한 것으로 간주되는 HTTP 응답 코드의 목록입니다. 대부분의 사용자는
200만 유효한 응답 코드로 간주해야 합니다. - 각 스크립트 실행 후 이메일 전송
- 이 옵션을 사용 설정하면 스크립트가 실행될 때마다 확인한 URL의 요약이 이메일로 전송됩니다. 이렇게 하면 모든 URL이 확인될 때까지 기다릴 필요 없이(여러 번 실행됨) URL 오류에 대한 조기 알림을 제공할 수 있습니다.
- 전체 분석 완료 후 이메일 전송
- 이 옵션을 사용 설정하면 모든 URL 확인이 완료된 후 스크립트에서 통합 요약을 이메일로 보냅니다.
- 오류가 발견되지 않은 경우에도 이메일 전송
- 이 옵션을 사용 설정하면 오류가 발견되지 않은 경우에도 앞의 두 가지 옵션을 기반으로 스크립트가 이메일을 보냅니다. 대부분의 사용자는 오류가 있을 때만 이메일을 받는 것을 선호하지만, 오류가 발생하지 않더라도 이메일을 수신하면 스크립트가 예정대로 실행되도록 하는 데 유용할 수 있습니다.
- 스프레드시트에 확인 URL 저장
- 이 옵션을 사용 설정하면 스크립트가 오류가 있는 URL뿐만 아니라 확인하는 모든 URL을 스프레드시트에 저장합니다. 대부분의 사용자는 깨진 URL만 저장하는 것을 선호하지만 일부 사용자는 스크립트에서 검사한 URL을 모두 확인하고자 할 수 있습니다.
- 분석 간 일수
- 이 옵션을 사용하면 스크립트가 전체 URL 목록에 대한 새 분석을 시작하는 빈도를 제어할 수 있습니다. 이 옵션은 분석 간 최소 일수를 제어합니다. URL 수가 많은 경우와 같이 분석 시간이 더 오래 걸리면 실제 수치가 더 커질 수 있습니다. 자세한 내용은 예약을 참조하세요.
고급 링크 확인
일부 사용 사례에서는 URL이 유효한 페이지를 반환하는지 확인하는 것만으로는 충분하지 않을 수 있습니다. 예를 들어 제품 페이지에 '제품 단종됨'이라는 텍스트가 포함된 경우를 생각해 보세요. 이 경우 해당 페이지를 깨진 링크로 신고할 수 있습니다
스크립트는 두 가지 유효성 검사 옵션을 제공합니다.
- 실패 문자열
단순 실패 문자열 일치 사용을
Yes로 설정하여 실패 문자열에 정의된 문자열 목록에서 일치하는 항목을 검색합니다. 웹페이지에서 발견되는 경우 페이지가 손상된 것으로 표시됩니다.- 커스텀 유효성 검사
각 URL과 응답에 맞춤 자바스크립트 유효성 검사 함수를 사용하여 유연성을 높일 수 있습니다. 예를 들어 다음과 같이 웹페이지 제목에 브랜드 이름이 포함되어 있음을 확인할 수 있습니다.
- 맞춤 유효성 검사 함수 사용을
Yes로 설정합니다. 스크립트 상단의 함수에 맞춤 유효성 검사 로직을 삽입합니다.
function isValidResponse(url, response, options, entityDetails) { // Your custom logic here, returning true for valid links, false otherwise. // ... }
응답 텍스트에 액세스하는 방법의 예와 함께 기본 구현이 이미 마련되어 있습니다.
- 맞춤 유효성 검사 함수 사용을
예약
스크립트가 실행될 때마다 이미 진행 중인 분석을 재개해야 하는지 또는 마지막 분석이 완료되었으며 분석을 새로 시작할 시점인지 자동으로 감지합니다 (분석 간 일수 옵션 기준). 따라서 새로운 분석을 실행하는 빈도에 관계없이 각 분석이 최대한 빨리 URL에서 반복되도록 스크립트를 매시간 실행하도록 예약하세요.
예를 들어 스크립트가 새 분석을 하루에 한 번 이하로 실행하려면 분석 간 일수를 1로 설정합니다. 스크립트가 매시간 실행되도록 예약되고 하루 이내에 모든 URL 확인이 완료되면, 후속 실행은 다음 날 새 분석을 시작할 때까지 즉시 종료됩니다.
사용 방법
진행률을 추적하기 위해 스크립트는 라벨을 만들고 확인한 후 광고, 키워드, 사이트링크에 적용합니다. 그러면 스크립트가 다음 실행 시 확인된 URL을 식별할 수 있습니다. 분석이 완료되면 (모든 URL이 확인됨) 스크립트는 새 분석을 위해 라벨을 지웁니다.
스크립트는 UrlFetchApp를 사용하여 최종 도착 URL과 모바일 최종 도착 URL을 확인합니다.
설정
아래 버튼을 클릭하여 Google Ads 계정에서 스프레드시트 기반 스크립트를 만들 수 있습니다.
템플릿 스프레드시트의 사본을 만들려면 아래 버튼을 클릭하세요.
스크립트에서
spreadsheet_url를 업데이트합니다.스크립트가 매시간 실행되도록 예약합니다.
소스 코드
// 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 Link Checker - Manager Accounts
*
* @overview The Link Checker script iterates through the ads, keywords, and
* sitelinks in your manager account hierarchy and makes sure their URLs
* do not produce "Page not found" or other types of error responses. See
* https://developers.google.com/google-ads/scripts/docs/solutions/manager-link-checker
* for more details.
*
* @author Google Ads Scripts Team [adwords-scripts@googlegroups.com]
*
* @version 3.1
*
* @changelog
* - version 3.1
* - Split into info, config, and code.
* - version 3.0
* - Updated to use new Google Ads scripts features.
* - version 2.2
* - Added support for failure strings and custom validation functions.
* - version 2.1
* - Added expansion of conditional ValueTrack parameters (e.g. ifmobile).
* - Added expanded text ad and other ad format support.
* - version 2.0.3
* - Added validation for external spreadsheet setup.
* - version 2.0.2
* - Allow the custom tracking label to include spaces.
* - version 2.0.1
* - Catch and output all UrlFetchApp exceptions.
* - Completely revised the script to work on larger accounts and hierarchies.
* - version 1.3
* - Enhanced to include ad group sitelinks.
* - Updated to track completion across runs and send at most one email
* per day.
* - version 1.2
* - Remove label flushing code from the script.
* - version 1.1
* - Remove some debug code.
* - version 1.0
* - Released initial version.
*/
/**
* Configuration to be used for the Link Checker.
*/
CONFIG = {
// URL of the spreadsheet template.
// This should be a copy of
// https://docs.google.com/spreadsheets/d/1iO1iEGwlbe510qo3Li-j4KgyCeVSmodxU6J7M756ppk/copy.
// Make sure the sheet is owned by or shared with same Google user executing the script
'spreadsheet_url': 'YOUR_SPREADSHEET_URL',
// Array of addresses to be alerted via email if issues are found.
'recipient_emails': ['YOUR_EMAIL_HERE'],
// Label to use when a link has been checked.
'label': 'LinkChecker_Done',
// A list of ManagedAccountSelector conditions to restrict the population
// of child accounts that will be processed. Leave blank or comment out
// to include all child accounts.
'account_conditions': [],
// Number of seconds to sleep after each URL request. Use this throttle
// to reduce the load that the script imposes on your web server(s).
'throttle_seconds': 0,
// Number of seconds before timeout that the script should stop checking URLs
// to make sure it has time to output its findings.
'timeout_buffer_seconds': 120,
'advanced_options': {
/**
* Parameters controlling the script's behavior after hitting a UrlFetchApp
* QPS quota limit.
*/
'quota_config': {
// Initial number of milliseconds to sleep.
'INIT_SLEEP_TIME_MILLIS': 250,
// Multiplicative factor to increase sleep time by on each retry.
'BACKOFF_FACTOR': 2,
// Maximum number of tries for a single URL.
'MAX_TRIES': 5
}
}
};
/**
* Performs custom validation on a URL, with access to details such as the URL,
* the response from the server, configuration options and entity Details.
*
* To use, the "Use Custom Validation" option in the configuration spreadsheet
* must be set to "Yes", and your custom validation code implemented within the
* below function.
*
* See the documentation for this solution for further details.
*
* @param {string} url The URL being checked.
* @param {!HTTPResponse} response The response object for the request.
* @param {!Object} options Configuration options.
* @param {!Object} entityDetails Details of the associated Ad / Keywords etc.
* @return {boolean} Return true if the URL and response are deemed valid.
*/
function isValidResponse(url, response, options, entityDetails) {
/*
Some examples of data that can be used in determining the validity of this
URL. This is not exhaustive and there are further properties available.
*/
// The HTTP status code, e.g. 200, 404
// const responseCode = response.getResponseCode();
// The HTTP response body, e.g. HTML for web pages:
// const responseText = response.getContentText();
// The failure strings from the configuration spreadsheet, as an array:
// const failureStrings = options.failureStrings;
// The type of the entity associated with the URL, e.g. Ad, Keyword, Sitelink.
// const entityType = entityDetails.entityType;
// The campaign name
// const campaignName = entityDetails.campaign;
// The ad group name, if applicable
// const adGroupName = entityDetails.adGroup;
// The ad text, if applicable
// const adText = entityDetails.ad;
// The keyword text, if applicable
// const keywordText = entityDetails.keyword;
// The sitelink link text, if applicable
// const sitelinkText = entityDetails.sitelink;
/*
Remove comments and insert custom logic to determine whether this URL and
response are valid, using the data obtained above.
If valid, return true. If invalid, return false.
*/
// Placeholder implementation treats all URLs as valid
return true;
}
const MILLISECONDS_PER_SECOND = 1000;
const QUOTA_CONFIG = CONFIG.advanced_options.quota_config;
const SPREADSHEET_URL = CONFIG.spreadsheet_url;
const RECIPIENT_EMAILS = CONFIG.recipient_emails;
const LABEL = CONFIG.label;
const THROTTLE_SECONDS = CONFIG.throttle_seconds;
const TIMEOUT_BUFFER_SECONDS = CONFIG.timeout_buffer_seconds;
const ACCOUNT_CONDITIONS = CONFIG.account_conditions;
/**
* Exceptions that prevent the script from finishing checking all URLs in an
* account but allow it to resume next time.
*/
const EXCEPTIONS = {
QPS: 'Reached UrlFetchApp QPS limit',
LIMIT: 'Reached UrlFetchApp daily quota',
TIMEOUT: 'Approached script execution time limit'
};
/**
* Named ranges in the spreadsheet.
*/
const NAMES = {
CHECK_AD_URLS: 'checkAdUrls',
CHECK_KEYWORD_URLS: 'checkKeywordUrls',
CHECK_SITELINK_URLS: 'checkSitelinkUrls',
CHECK_PAUSED_ADS: 'checkPausedAds',
CHECK_PAUSED_KEYWORDS: 'checkPausedKeywords',
CHECK_PAUSED_SITELINKS: 'checkPausedSitelinks',
VALID_CODES: 'validCodes',
EMAIL_EACH_RUN: 'emailEachRun',
EMAIL_NON_ERRORS: 'emailNonErrors',
EMAIL_ON_COMPLETION: 'emailOnCompletion',
SAVE_ALL_URLS: 'saveAllUrls',
FAILURE_STRINGS: 'failureStrings',
FREQUENCY: 'frequency',
DATE_STARTED: 'dateStarted',
DATE_COMPLETED: 'dateCompleted',
DATE_EMAILED: 'dateEmailed',
NUM_ERRORS: 'numErrors',
RESULT_HEADERS: 'resultHeaders',
ARCHIVE_HEADERS: 'archiveHeaders',
USE_SIMPLE_FAILURE_STRINGS: 'useSimpleFailureStrings',
USE_CUSTOM_VALIDATION: 'useCustomValidation'
};
function main() {
const spreadsheet = validateAndGetSpreadsheet(SPREADSHEET_URL);
validateEmailAddresses();
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
const options = loadOptions(spreadsheet);
const status = loadStatus(spreadsheet);
if (!status.dateStarted) {
// This is the very first execution of the script.
startNewAnalysis(spreadsheet);
} else if (status.dateStarted > status.dateCompleted) {
console.log(`Resuming work from a previous execution.`);
} else if (dayDifference(status.dateStarted, new Date()) <
options.frequency) {
console.log(`Waiting until ${options.frequency} days have elapsed since ` +
`the start of the last analysis.`);
return;
} else {
// Enough time has passed since the last analysis to start a new one.
removeLabelsInAccounts();
removeAccountLabels([LABEL]);
startNewAnalysis(spreadsheet);
}
ensureAccountLabels([LABEL]);
// Get up to 50 accounts that have not yet had all of their URLs checked.
const accountSelector = getAccounts(false).withLimit(50);
if (accountSelector.get().hasNext()) {
accountSelector
.executeInParallel('processAccount', 'processResults', JSON.stringify(options));
} else {
processResults([]);
}
}
/**
* Retrieves all accounts that either have had their URLs checked or need to
* have their URLs checked.
*
* @param {boolean} isChecked True to get accounts that have been checked
* already, false to get accounts that have not have been checked already.
* Ignored if the label does not exist.
* @return {Object} An account selector.
*/
function getAccounts(isChecked) {
let accountSelector = AdsManagerApp.accounts();
const accountLabel = getAccountLabel(LABEL);
if (accountLabel) {
accountSelector = accountSelector
.withCondition(`customer_client.applied_labels ${(isChecked ? `CONTAINS ANY` : `CONTAINS NONE`)}` +
` ("${accountLabel.getResourceName()}")`);
}
if (ACCOUNT_CONDITIONS) {
for (const condition of ACCOUNT_CONDITIONS) {
accountSelector =
accountSelector.withCondition(condition);
}
}
return accountSelector;
}
/**
* Removes the tracking in each account that was previously analyzed, thereby
* clearing that account for a new analysis.
*/
function removeLabelsInAccounts() {
const managerAccount = AdsApp.currentAccount();
const accounts = getAccounts(true).get();
for (const account of accounts) {
AdsManagerApp.select(account);
removeLabels([LABEL]);
}
AdsManagerApp.select(managerAccount);
}
/**
* Performs the link checking analysis on the current account.
*
* @param {string} options Options from the spreadsheet as JSON.
* @return {string} JSON stringified results of the analysis.
*/
function processAccount(options) {
return JSON.stringify(analyzeAccount(JSON.parse(options)));
}
/**
* Consolidates results from each account and outputs them.
*
* @param {Array.<Object>} executionResults A list of ExecutionResult objects.
*/
function processResults(executionResults) {
const spreadsheet = SpreadsheetApp.openByUrl(SPREADSHEET_URL);
const options = loadOptions(spreadsheet);
const results = {
urlChecks: [],
didComplete: true
};
for (const result of executionResults) {
if (!result.getError()) {
const accountResult = JSON.parse(result.getReturnValue());
results.urlChecks = results.urlChecks.concat(accountResult.urlChecks);
results.didComplete = results.didComplete && accountResult.didComplete;
if (accountResult.didComplete) {
AdsManagerApp.accounts()
.withIds([result.getCustomerId()])
.get()
.next()
.applyLabel(LABEL);
}
} else {
console.log(`Processing for ${result.getCustomerId()} failed.`);
}
}
// The entire analysis is not complete if there are any accounts that have
// not been labeled (i.e., the account was not started, or not all URLs in
// the account have been checked).
results.didComplete = results.didComplete &&
!getAccounts(false).get().hasNext();
outputResults(results, options);
}
/**
* Checks as many new URLs as possible that have not previously been checked,
* subject to quota and time limits.
*
* @param {Object} options Dictionary of options.
* @return {Object} An object with fields for the URLs checked and an indication
* if the analysis was completed (no remaining URLs to check).
*/
function analyzeAccount(options) {
// Ensure the label exists before attempting to retrieve already checked URLs.
ensureLabels([LABEL]);
const checkedUrls = getAlreadyCheckedUrls(options);
const urlChecks = [];
let didComplete = false;
try {
// If the script throws an exception, didComplete will remain false.
didComplete = checkUrls(checkedUrls, urlChecks, options);
} catch(e) {
if (e == EXCEPTIONS.QPS ||
e == EXCEPTIONS.LIMIT ||
e == EXCEPTIONS.TIMEOUT) {
console.log(`Stopped checking URLs early because: ${e}`);
console.log(`Checked URLs will still be output.`);
} else {
throw e;
}
}
return {
urlChecks: urlChecks,
didComplete: didComplete
};
}
/**
* Outputs the results to a spreadsheet and sends emails if appropriate.
*
* @param {Object} results An object with fields for the URLs checked and an
* indication if the analysis was completed (no remaining URLs to check).
* @param {Object} options Dictionary of options.
*/
function outputResults(results, options) {
const spreadsheet = SpreadsheetApp.openByUrl(SPREADSHEET_URL);
const numErrors = countErrors(results.urlChecks, options);
console.log(`Found ${numErrors} errors this execution.`);
saveUrlsToSpreadsheet(spreadsheet, results.urlChecks, options);
// Reload the status to get the total number of errors for the entire
// analysis, which is calculated by the spreadsheet.
status = loadStatus(spreadsheet);
if (results.didComplete) {
spreadsheet.getRangeByName(NAMES.DATE_COMPLETED).setValue(new Date());
console.log(`Found ${status.numErrors} errors across the entire analysis.`);
}
if (RECIPIENT_EMAILS) {
if (!results.didComplete && options.emailEachRun &&
(options.emailNonErrors || numErrors > 0)) {
sendIntermediateEmail(spreadsheet, numErrors);
}
if (results.didComplete &&
(options.emailEachRun || options.emailOnCompletion) &&
(options.emailNonErrors || status.numErrors > 0)) {
sendFinalEmail(spreadsheet, status.numErrors);
}
}
}
/**
* Loads data from a spreadsheet based on named ranges. Strings 'Yes' and 'No'
* are converted to booleans. One-dimensional ranges are converted to arrays
* with blank cells omitted. Assumes each named range exists.
*
* @param {Object} spreadsheet The spreadsheet object.
* @param {Array.<string>} names A list of named ranges that should be loaded.
* @return {Object} A dictionary with the names as keys and the values
* as the cell values from the spreadsheet.
*/
function loadDatabyName(spreadsheet, names) {
const data = {};
for (const name of names) {
const range = spreadsheet.getRangeByName(name);
if (range.getNumRows() > 1 && range.getNumColumns() > 1) {
// Name refers to a 2d range, so load it as a 2d array.
data[name] = range.getValues();
} else if (range.getNumRows() == 1 && range.getNumColumns() == 1) {
// Name refers to a single cell, so load it as a value and replace
// Yes/No with boolean true/false.
data[name] = range.getValue();
data[name] = data[name] === 'Yes' ? true : data[name];
data[name] = data[name] === 'No' ? false : data[name];
} else {
// Name refers to a 1d range, so load it as an array (regardless of
// whether the 1d range is oriented horizontally or vertically).
const isByRow = range.getNumRows() > 1;
const limit = isByRow ? range.getNumRows() : range.getNumColumns();
const cellValues = range.getValues();
data[name] = [];
for (let j = 0; j < limit; j++) {
const cellValue = isByRow ? cellValues[j][0] : cellValues[0][j];
if (cellValue) {
data[name].push(cellValue);
}
}
}
}
return data;
}
/**
* Loads options from the spreadsheet.
*
* @param {Object} spreadsheet The spreadsheet object.
* @return {Object} A dictionary of options.
*/
function loadOptions(spreadsheet) {
return loadDatabyName(spreadsheet,
[NAMES.CHECK_AD_URLS, NAMES.CHECK_KEYWORD_URLS,
NAMES.CHECK_SITELINK_URLS, NAMES.CHECK_PAUSED_ADS,
NAMES.CHECK_PAUSED_KEYWORDS, NAMES.CHECK_PAUSED_SITELINKS,
NAMES.VALID_CODES, NAMES.EMAIL_EACH_RUN,
NAMES.EMAIL_NON_ERRORS, NAMES.EMAIL_ON_COMPLETION,
NAMES.SAVE_ALL_URLS, NAMES.FREQUENCY,
NAMES.FAILURE_STRINGS, NAMES.USE_SIMPLE_FAILURE_STRINGS,
NAMES.USE_CUSTOM_VALIDATION]);
}
/**
* Loads state information from the spreadsheet.
*
* @param {Object} spreadsheet The spreadsheet object.
* @return {Object} A dictionary of status information.
*/
function loadStatus(spreadsheet) {
return loadDatabyName(spreadsheet,
[NAMES.DATE_STARTED, NAMES.DATE_COMPLETED,
NAMES.DATE_EMAILED, NAMES.NUM_ERRORS]);
}
/**
* Saves the start date to the spreadsheet and archives results of the last
* analysis to a separate sheet.
*
* @param {Object} spreadsheet The spreadsheet object.
*/
function startNewAnalysis(spreadsheet) {
console.log(`Starting a new analysis.`);
spreadsheet.getRangeByName(NAMES.DATE_STARTED).setValue(new Date());
// Helper method to get the output area on the results or archive sheets.
function getOutputRange(rangeName) {
const headers = spreadsheet.getRangeByName(rangeName);
return headers.offset(1, 0, headers.getSheet().getDataRange().getLastRow());
}
getOutputRange(NAMES.ARCHIVE_HEADERS).clearContent();
const results = getOutputRange(NAMES.RESULT_HEADERS);
results.copyTo(getOutputRange(NAMES.ARCHIVE_HEADERS));
getOutputRange(NAMES.RESULT_HEADERS).clearContent();
}
/**
* Counts the number of errors in the results.
*
* @param {Array.<Object>} urlChecks A list of URL check results.
* @param {Object} options Dictionary of options.
* @return {number} The number of errors in the results.
*/
function countErrors(urlChecks, options) {
let numErrors = 0;
for (const urlCheck of urlChecks) {
if (options.validCodes.indexOf(urlCheck.responseCode) == -1) {
numErrors++;
}
}
return numErrors;
}
/**
* Saves URLs for a particular account to the spreadsheet starting at the first
* unused row.
*
* @param {Object} spreadsheet The spreadsheet object.
* @param {Array.<Object>} urlChecks A list of URL check results.
* @param {Object} options Dictionary of options.
*/
function saveUrlsToSpreadsheet(spreadsheet, urlChecks, options) {
// Build each row of output values in the order of the columns.
const outputValues = [];
for (const urlCheck of urlChecks) {
if (options.saveAllUrls ||
options.validCodes.indexOf(urlCheck.responseCode) == -1) {
outputValues.push([
urlCheck.customerId,
new Date(urlCheck.timestamp),
urlCheck.url,
urlCheck.responseCode,
urlCheck.entityType,
urlCheck.campaign,
urlCheck.adGroup,
urlCheck.ad,
urlCheck.keyword,
urlCheck.sitelink
]);
}
}
if (outputValues.length > 0) {
// Find the first open row on the Results tab below the headers and create a
// range large enough to hold all of the output, one per row.
const headers = spreadsheet.getRangeByName(NAMES.RESULT_HEADERS);
const lastRow = headers.getSheet().getDataRange().getLastRow();
const outputRange = headers.offset(lastRow - headers.getRow() + 1,
0, outputValues.length);
outputRange.setValues(outputValues);
}
for (const email of RECIPIENT_EMAILS) {
spreadsheet.addEditor(email);
}
}
/**
* Sends an email to a list of email addresses with a link to the spreadsheet
* and the results of this execution of the script.
*
* @param {Object} spreadsheet The spreadsheet object.
* @param {boolean} numErrors The number of errors found in this execution.
*/
function sendIntermediateEmail(spreadsheet, numErrors) {
spreadsheet.getRangeByName(NAMES.DATE_EMAILED).setValue(new Date());
MailApp.sendEmail(
RECIPIENT_EMAILS.join(','), `Link Checker Results`,
`The Link Checker script found ${numErrors} URLs with errors in ` +
`an execution that just finished. See ${
spreadsheet.getUrl()} for details.`);
}
/**
* Sends an email to a list of email addresses with a link to the spreadsheet
* and the results across the entire account.
*
* @param {Object} spreadsheet The spreadsheet object.
* @param {boolean} numErrors The number of errors found in the entire account.
*/
function sendFinalEmail(spreadsheet, numErrors) {
spreadsheet.getRangeByName(NAMES.DATE_EMAILED).setValue(new Date());
MailApp.sendEmail(
RECIPIENT_EMAILS.join(','), `Link Checker Results`,
`The Link Checker script found ${numErrors} URLs with errors ` +
`across its entire analysis. See ${
spreadsheet.getUrl()} for details.`);
}
/**
* Retrieves all final URLs and mobile final URLs in the account across ads,
* keywords, and sitelinks that were checked in a previous run, as indicated by
* them having been labeled.
*
* @param {Object} options Dictionary of options.
* @return {Object} A map of previously checked URLs with the URL as the key.
*/
function getAlreadyCheckedUrls(options) {
const urlMap = {};
function addToMap(items) {
for (const item of items) {
for(const url of expandUrlModifiers(item)){
urlMap[url] = true;
}
}
}
if (options.checkAdUrls) {
addToMap(getUrlsBySelector(AdsApp.ads()
.withCondition(labelCondition(true))));
}
if (options.checkKeywordUrls) {
addToMap(getUrlsBySelector(AdsApp.keywords()
.withCondition(labelCondition(true))));
}
if (options.checkSitelinkUrls) {
addToMap(getAlreadyCheckedSitelinkUrls());
}
return urlMap;
}
/**
* Retrieves all final URLs and mobile final URLs for campaign and ad group
* sitelinks.
*
* @return {Array.<string>} An array of URLs.
*/
function getAlreadyCheckedSitelinkUrls() {
const urls = [];
// Helper method to get campaign or ad group sitelink URLs.
function addSitelinkUrls(selector) {
const iterator = selector.withCondition(labelCondition(true)).get();
for (const entity of iterator) {
const sitelinks = entity.extensions().sitelinks();
urls.push(...getUrlsBySelector(sitelinks));
}
}
addSitelinkUrls(AdsApp.campaigns());
addSitelinkUrls(AdsApp.adGroups());
return urls;
}
/**
* Retrieves all URLs in the entities specified by a selector.
*
* @param {Object} selector The selector specifying the entities to use.
* The entities should be of a type that has a urls() method.
* @return {Array.<string>} An array of URLs.
*/
function getUrlsBySelector(selector) {
const urls = [];
const entities = selector.get();
// Helper method to add the url to the list if it exists.
function addToList(url) {
if (url) {
urls.push(url);
}
}
for (const entity of entities) {
addToList(entity.urls().getFinalUrl());
addToList(entity.urls().getMobileFinalUrl());
}
return urls;
}
/**
* Retrieves all final URLs and mobile final URLs in the account across ads,
* keywords, and sitelinks, and checks their response code. Does not check
* previously checked URLs.
*
* @param {Object} checkedUrls A map of previously checked URLs with the URL as
* the key.
* @param {Array.<Object>} urlChecks An array into which the results of each URL
* check will be inserted.
* @param {Object} options Dictionary of options.
* @return {boolean} True if all URLs were checked.
*/
function checkUrls(checkedUrls, urlChecks, options) {
let didComplete = true;
// Helper method to add common conditions to ad group and keyword selectors.
function addConditionsForAds(selector, includePaused) {
const statuses = ['ENABLED'];
if (includePaused) {
statuses.push('PAUSED');
}
const predicate = ` IN (${statuses.join(',')})`;
return selector.withCondition(labelCondition(false))
.withCondition(`ad_group_ad.status${predicate}`)
.withCondition(`campaign.status${predicate}`)
.withCondition(`ad_group.status${predicate}`);
}
function addConditionsForKeywords(selector, includePaused) {
const statuses = ['ENABLED'];
if (includePaused) {
statuses.push('PAUSED');
}
const predicate = ` IN (${statuses.join(',')})`;
return selector.withCondition(labelCondition(false))
.withCondition(`ad_group_criterion.status${predicate}`)
.withCondition(`campaign.status${predicate}`)
.withCondition(`ad_group.status${predicate}`);
}
if (options.checkAdUrls) {
didComplete = didComplete && checkUrlsBySelector(checkedUrls, urlChecks,
addConditionsForAds(AdsApp.ads()
.withCondition('CreativeFinalUrls != ""'),
options.checkPausedAds), options);
}
if (options.checkKeywordUrls) {
didComplete = didComplete && checkUrlsBySelector(checkedUrls, urlChecks,
addConditionsForKeywords(AdsApp.keywords()
.withCondition('FinalUrls != ""'),
options.checkPausedKeywords), options);
}
if (options.checkSitelinkUrls) {
didComplete = didComplete && checkSitelinkUrls(checkedUrls, urlChecks,
options);
}
return didComplete;
}
/**
* Retrieves all final URLs and mobile final URLs in a selector and checks them
* for a valid response code. Does not check previously checked URLs. Labels the
* entity that it was checked, if possible.
*
* @param {Object} checkedUrls A map of previously checked URLs with the URL as
* the key.
* @param {Array.<Object>} urlChecks An array into which the results of each URL
* check will be inserted.
* @param {Object} selector The selector specifying the entities to use.
* The entities should be of a type that has a urls() method.
* @param {!Object} options Dictionary of options.
* @return {boolean} True if all URLs were checked.
*/
function checkUrlsBySelector(checkedUrls, urlChecks, selector, options) {
const customerId = AdsApp.currentAccount().getCustomerId();
const iterator = selector.get();
const entities = [];
// Helper method to check a URL.
function checkUrl(entity, url) {
if (!url) {
return;
}
const urlsToCheck = expandUrlModifiers(url);
for (const expandedUrl of urlsToCheck) {
if (checkedUrls[expandedUrl]) {
continue;
}
const entityType = entity.getEntityType();
const entityDetails = {
entityType: entityType,
campaign: entity.getCampaign ? entity.getCampaign().getName() : '',
adGroup: entity.getAdGroup ? entity.getAdGroup().getName() : '',
ad: entityType == 'Ad' ? getAdAsText(entity) : '',
keyword: entityType == 'Keyword' ? entity.getText() : '',
sitelink: entityType.indexOf('Sitelink') != -1 ?
entity.getLinkText() : ''
};
const responseCode = requestUrl(expandedUrl, options, entityDetails);
urlChecks.push({
customerId: customerId,
timestamp: new Date(),
url: expandedUrl,
responseCode: responseCode,
entityType: entityDetails.entityType,
campaign: entityDetails.campaign,
adGroup: entityDetails.adGroup,
ad: entityDetails.ad,
keyword: entityDetails.keyword,
sitelink: entityDetails.sitelink
});
checkedUrls[expandedUrl] = true;
}
}
entities.push(...iterator);
for (const entity of entities) {
checkUrl(entity, entity.urls().getFinalUrl());
checkUrl(entity, entity.urls().getMobileFinalUrl());
// Sitelinks do not have labels.
if (entity.applyLabel) {
entity.applyLabel(LABEL);
checkTimeout();
}
}
// True only if we did not breach an iterator limit.
return entities.length === iterator.totalNumEntities();
}
/**
* Retrieves a text representation of an ad, casting the ad to the appropriate
* type if necessary.
*
* @param {Ad} ad The ad object.
* @return {string} The text representation.
*/
function getAdAsText(ad) {
// There is no AdTypeSpace method for textAd
if (ad.getType() === 'TEXT_AD') {
return ad.getHeadline();
} else if (ad.isType().expandedTextAd()) {
const eta = ad.asType().expandedTextAd();
return eta.getHeadlinePart1() + ' - ' + eta.getHeadlinePart2();
} else if (ad.isType().gmailImageAd()) {
return ad.asType().gmailImageAd().getName();
} else if (ad.isType().gmailMultiProductAd()) {
return ad.asType().gmailMultiProductAd().getHeadline();
} else if (ad.isType().gmailSinglePromotionAd()) {
return ad.asType().gmailSinglePromotionAd().getHeadline();
} else if (ad.isType().html5Ad()) {
return ad.asType().html5Ad().getName();
} else if (ad.isType().imageAd()) {
return ad.asType().imageAd().getName();
} else if (ad.isType().responsiveDisplayAd()) {
return ad.asType().responsiveDisplayAd().getLongHeadline();
} else if (ad.isType().responsiveSearchAd()) {
return ad.asType()
.responsiveSearchAd()
.getHeadlines()
.map(h => h.text)
.join(', ');
}
return 'N/A';
}
/**
* Retrieves all final URLs and mobile final URLs for campaign and ad group
* sitelinks and checks them for a valid response code. Does not check
* previously checked URLs. Labels the containing campaign or ad group that it
* has been checked.
*
* @param {Object} checkedUrls A map of previously checked URLs with the URL as
* the key.
* @param {Array.<Object>} urlChecks An array into which the results of each URL
* check will be inserted.
* @param {Object} options Dictionary of options.
* @return {boolean} True if all URLs were checked.
*/
function checkSitelinkUrls(checkedUrls, urlChecks, options) {
let didComplete = true;
// Helper method to check URLs for sitelinks in a campaign or ad group
// selector.
function checkSitelinkUrls(selector) {
const iterator = selector.withCondition(labelCondition(false)).get();
const entities = [];
for (const iteratorElement of iterator) {
entities.push(iteratorElement);
}
for (const entity of entities) {
const sitelinks = entity.extensions().sitelinks();
if (sitelinks.get().hasNext()) {
didComplete = didComplete &&
checkUrlsBySelector(checkedUrls, urlChecks, sitelinks, options);
entity.applyLabel(LABEL);
checkTimeout();
}
}
// True only if we did not breach an iterator limit.
didComplete = didComplete &&
entities.length === iterator.totalNumEntities();
}
const statuses = ['ENABLED'];
if (options.checkPausedSitelinks) {
statuses.push('PAUSED');
}
const predicate = ` IN (${statuses.join(',')})`;
checkSitelinkUrls(AdsApp.campaigns()
.withCondition(`campaign.status${predicate}`));
checkSitelinkUrls(AdsApp.adGroups()
.withCondition(`ad_group.status${predicate}`)
.withCondition(`campaign.status${predicate}`));
return didComplete;
}
/**
* Expands a URL that contains ValueTrack parameters such as {ifmobile:mobile}
* to all the combinations, and returns as an array. The following pairs of
* ValueTrack parameters are currently expanded:
* 1. {ifmobile:<...>} and {ifnotmobile:<...>} to produce URLs simulating
* clicks from either mobile or non-mobile devices.
* 2. {ifsearch:<...>} and {ifcontent:<...>} to produce URLs simulating
* clicks on either the search or display networks.
* Any other ValueTrack parameters or customer parameters are stripped out from
* the URL entirely.
*
* @param {string} url The URL which may contain ValueTrack parameters.
* @return {!Array.<string>} An array of one or more expanded URLs.
*/
function expandUrlModifiers(url) {
const ifRegex = /({(if\w+):([^}]+)})/gi;
const modifiers = {};
let matches;
let modifiedUrls;
while (matches = ifRegex.exec(url)) {
// Tags are case-insensitive, e.g. IfMobile is valid.
modifiers[matches[2].toLowerCase()] = {
substitute: matches[0],
replacement: matches[3]
};
}
if (Object.keys(modifiers).length) {
let mobileCombinations;
if (modifiers.ifmobile || modifiers.ifnotmobile) {
mobileCombinations =
pairedUrlModifierReplace(modifiers, 'ifmobile', 'ifnotmobile', url);
} else {
mobileCombinations = [url];
}
// Store in a map on the offchance that there are duplicates.
const combinations = {};
for (const url of mobileCombinations) {
if (modifiers.ifsearch || modifiers.ifcontent) {
for (const modifiedUrl of
pairedUrlModifierReplace(modifiers, 'ifsearch', 'ifcontent', url)) {
combinations[modifiedUrl] = true;
}
} else {
combinations[url] = true;
}
}
modifiedUrls = Object.keys(combinations);
} else {
modifiedUrls = [url];
}
// Remove any custom parameters
return modifiedUrls.map(url => url.replace(/{[\w_+:]+}/g, ''));
}
/**
* Return a pair of URLs, where each of the two modifiers is mutually exclusive,
* one for each combination. e.g. Evaluating ifmobile and ifnotmobile for a
* mobile and a non-mobile scenario.
*
* @param {Object} modifiers A map of ValueTrack modifiers.
* @param {string} modifier1 The modifier to honour in the URL.
* @param {string} modifier2 The modifier to remove from the URL.
* @param {string} url The URL potentially containing ValueTrack parameters.
* @return {Array.<string>} A pair of URLs, as a list.
*/
function pairedUrlModifierReplace(modifiers, modifier1, modifier2, url) {
return [
urlModifierReplace(modifiers, modifier1, modifier2, url),
urlModifierReplace(modifiers, modifier2, modifier1, url)
];
}
/**
* Produces a URL where the first {if...} modifier is set, and the second is
* deleted.
*
* @param {Object} mods A map of ValueTrack modifiers.
* @param {string} mod1 The modifier to honour in the URL.
* @param {string} mod2 The modifier to remove from the URL.
* @param {string} url The URL potentially containing ValueTrack parameters.
* @return {string} The resulting URL with substitions.
*/
function urlModifierReplace(mods, mod1, mod2, url) {
const modUrl = mods[mod1] ?
url.replace(mods[mod1].substitute, mods[mod1].replacement) :
url;
return mods[mod2] ? modUrl.replace(mods[mod2].substitute, '') : modUrl;
}
/**
* Requests a given URL. Retries if the UrlFetchApp QPS limit was reached,
* exponentially backing off on each retry. Throws an exception if it reaches
* the maximum number of retries. Throws an exception if the UrlFetchApp daily
* quota limit was reached.
*
* @param {string} url The URL to test.
* @param {!Object} options The options loaded from the configuration sheet.
* @param {!Object} entityDetails Details of the entity, e.g. type, name etc.
* @return {number|string} The response code received when requesting the URL,
* or an error message.
*/
function requestUrl(url, options, entityDetails) {
let responseCode;
let sleepTimeMillis = QUOTA_CONFIG.INIT_SLEEP_TIME_MILLIS;
let numTries = 0;
while (numTries < QUOTA_CONFIG.MAX_TRIES && !responseCode) {
try {
// If UrlFetchApp.fetch() throws an exception, responseCode will remain
// undefined.
const response = UrlFetchApp.fetch(url, {muteHttpExceptions: true});
responseCode = response.getResponseCode();
if (options.validCodes.indexOf(responseCode) !== -1) {
if (options.useSimpleFailureStrings &&
bodyContainsFailureStrings(response, options.failureStrings)) {
responseCode = 'Failure string detected';
} else if (options.useCustomValidation && !isValidResponse(url,
response, options, entityDetails)) {
responseCode = "Custom validation failed";
}
}
if (THROTTLE_SECONDS > 0) {
Utilities.sleep(THROTTLE_SECONDS * MILLISECONDS_PER_SECOND);
}
} catch(e) {
if (e.message.indexOf('Service invoked too many times in a short time:')
!= -1) {
Utilities.sleep(sleepTimeMillis);
sleepTimeMillis *= QUOTA_CONFIG.BACKOFF_FACTOR;
} else if (e.message.indexOf('Service invoked too many times:') != -1) {
throw EXCEPTIONS.LIMIT;
} else {
return e.message;
}
}
numTries++;
}
if (!responseCode) {
throw EXCEPTIONS.QPS;
} else {
return responseCode;
}
}
/**
* Searches the body of a HTTP response for any occurrence of a "failure string"
* as defined in the configuration spreadsheet. For example, "Out of stock".
*
* @param {!HTTPResponse} response The response from the UrlFetchApp request.
* @param {!Array.<string>} failureStrings A list of failure strings.
* @return {boolean} Returns true if at least one failure string found.
*/
function bodyContainsFailureStrings(response, failureStrings) {
const contentText = response.getContentText() || '';
// Whilst searching for each separate failure string across the body text
// separately may not be the most efficient, it is simple, and tests suggest
// it is not overly poor performance-wise.
return failureStrings.some(
failureString => contentText.indexOf(failureString) !== -1);
}
/**
* Throws an exception if the script is close to timing out.
*/
function checkTimeout() {
if (AdsApp.getExecutionInfo().getRemainingTime() < TIMEOUT_BUFFER_SECONDS) {
throw EXCEPTIONS.TIMEOUT;
}
}
/**
* Returns the number of days between two dates.
*
* @param {Object} from The older Date object.
* @param {Object} to The newer (more recent) Date object.
* @return {number} The number of days between the given dates (possibly
* fractional).
*/
function dayDifference(from, to) {
return (to.getTime() - from.getTime()) / (24 * 3600 * 1000);
}
/**
* Builds a string to be used for withCondition() filtering for whether the
* label is present or not.
*
* @param {boolean} hasLabel True if the label should be present, false if the
* label should not be present.
* @return {string} A condition that can be used in withCondition().
*/
function labelCondition(hasLabel) {
return `LabelNames ${(hasLabel ? `CONTAINS_ANY` : `CONTAINS_NONE`)}` +
` ["${LABEL}"]`;
}
/**
* Retrieves an entity by name.
*
* @param {Object} selector A selector for an entity type with a Name field.
* @param {string} name The name to retrieve the entity by.
* @return {Object} The entity, if it exists, or null otherwise.
*/
function getEntityByName(selector, name) {
const entities = selector.withCondition(`Name = "${name}"`).get();
if (entities.hasNext()) {
return entities.next();
} else {
return null;
}
}
/**
* Retrieves a Label object by name.
*
* @param {string} labelName The label name to retrieve.
* @return {Object} The Label object, if it exists, or null otherwise.
*/
function getLabel(labelName) {
return getEntityByName(AdsApp.labels(), labelName);
}
/**
* Retrieves an AccountLabel object by name.
*
* @param {string} labelName The label name to retrieve.
* @return {Object} The AccountLabel object, if it exists, or null otherwise.
*/
function getAccountLabel(labelName) {
return getEntityByName(AdsManagerApp.accountLabels(), labelName);
}
/**
* Checks that the account has all provided labels and creates any that are
* missing. Since labels cannot be created in preview mode, throws an exception
* if a label is missing.
*
* @param {Array.<string>} labelNames An array of label names.
*/
function ensureLabels(labelNames) {
for (const labelName of labelNames) {
const label = getLabel(labelName);
if (!label) {
if (!AdsApp.getExecutionInfo().isPreview()) {
AdsApp.createLabel(labelName);
} else {
throw `Label ${labelName} is missing and cannot be created in ` +
`preview mode. Please run the script or create the label manually.`;
}
}
}
}
/**
* Checks that the account has all provided account labels and creates any that
* are missing. Since labels cannot be created in preview mode, throws an
* exception if a label is missing.
*
* @param {Array.<string>} labelNames An array of label names.
*/
function ensureAccountLabels(labelNames) {
for (const labelName of labelNames) {
const label = getLabel(labelName);
if (!label) {
if (!AdsApp.getExecutionInfo().isPreview()) {
AdsManagerApp.createAccountLabel(labelName);
} else {
throw `Account label ${labelName} is missing and cannot be ` +
`created in preview mode. Please run the script or create the ` +
`label manually.`;
}
}
}
}
/**
* Removes all provided labels from the account. Since labels cannot be removed
* in preview mode, throws an exception in preview mode.
*
* @param {Array.<string>} labelNames An array of label names.
*/
function removeLabels(labelNames) {
if (AdsApp.getExecutionInfo().isPreview()) {
throw 'Cannot remove labels in preview mode. Please run the script or ' +
'remove the labels manually.';
}
for (const labelName of labelNames) {
const label = getLabel(labelName);
if (label) {
label.remove();
}
}
}
/**
* Removes all provided account labels from the account. Since labels cannot be
* removed in preview mode, throws an exception in preview mode.
*
* @param {Array.<string>} labelNames An array of label names.
*/
function removeAccountLabels(labelNames) {
if (AdsApp.getExecutionInfo().isPreview()) {
throw 'Cannot remove account labels in preview mode. Please run the ' +
'script or remove the labels manually.';
}
for (const labelName of labelNames) {
const label = getLabel(labelName);
if (label) {
label.remove();
}
}
}
/**
* 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);
}
/**
* Validates the provided email address to make sure it's not the default.
* Throws a descriptive error message if validation fails.
*
* @throws {Error} If the list of email addresses is still the default
*/
function validateEmailAddresses() {
if (RECIPIENT_EMAILS && RECIPIENT_EMAILS[0] == 'YOUR_EMAIL_HERE') {
throw new Error('Please either specify a valid email address or clear' +
' the RECIPIENT_EMAILS field.');
}
}