서버 측 맞춤 템플릿 권한

이 문서에서는 서버 측 맞춤 템플릿에 대한 권한을 간략히 설명합니다.

---

각 권한에 대한 설명은 다음과 같습니다.

• 해당 권한이 필요한 API에서 확인됩니다.
• 사용된 API를 기반으로, 샌드박스 처리된 JavaScript에서 자동 감지됩니다. 이러한 상황은 빠른 피드백 루프를 위해 맞춤 템플릿 편집기에서 템플릿이 수정되고 올바른 권한이 적용되었는지 확인하기 위해 코드가 컴파일될 때 발생합니다.
• 맞춤 템플릿 편집기에서 더 구체적으로 수정할 수 있습니다.
• queryPermission API를 통해 샌드박스 처리된 자바스크립트에서 쿼리할 수 있습니다.

access_bigquery

표시 이름: BigQuery 액세스

설명: Google Cloud Platform에서 BigQuery에 대한 액세스를 허용합니다.

구성: 지정된 프로젝트, 데이터 세트, 테이블 조합을 BigQuery에서 사용할 수 있는 옵션입니다. GOOGLE_CLOUD_PROJECT의 프로젝트 ID 구성을 설정하면, projectId가 BigQuery API parameter에서 제외된 경우 GOOGLE_CLOUD_PROJECT 환경 변수를 프로젝트 ID로 사용할 수 있습니다.

요청자: BigQuery

쿼리 서명: queryPermission('access_bigquery', <operation>, <options>)

참고: <operation>은 문자열이며 다음 값을 포함할 수 있습니다.

• write

<options>는 다음 항목을 포함하는 객체입니다.

{
  'projectId': <project_id>,
  'datasetId': <dataset_id>,
  'tableId': <table_id>
}

예시 코드

const BigQuery = require('BigQuery');
const queryPermission = require('queryPermission');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

if (queryPermission('access_bigquery', 'write', connectionInfo)) {
  const rows = [{
    'column1': 'String1',
    'column2': 1234,
  }];
  const options = {
    'ignoreUnknownValues': true,
    'skipInvalidRows': false,
  };

  BigQuery.insert(connectionInfo, rows, options)
      .then(data.gtmOnSuccess, data.gtmOnFailure);
}

access_firestore

표시 이름: Google Firestore 액세스

설명: Google Firestore에 대한 액세스를 허용합니다.

구성: 지정된 프로젝트 및 경로(와일드 카드 구문 지원) 조합을 Firestore에서 사용할 수 있는 옵션입니다. GOOGLE_CLOUD_PROJECT의 프로젝트 ID 구성을 설정하면, projectId가 Firestore API parameter에서 제외된 경우 GOOGLE_CLOUD_PROJECT 환경 변수를 프로젝트 ID로 사용할 수 있습니다.

요청자: Firestore

쿼리 서명: queryPermission('access_firestore', <operation>, <options>)

참고: <operation>은 문자열이며 다음 값을 포함할 수 있습니다.

• read - API를 읽고 쿼리할 수 있는 액세스 권한 부여
• write - API를 쓸 수 있는 액세스 권한 부여
• read_write - API를 읽고 쓰고 쿼리할 수 있는 액세스 권한 부여

<options>는 다음 항목을 포함하는 객체입니다.

{
  'projectId': <project_id>,
  'path': <path>
}

예시 코드

const Firestore = require('Firestore');
const queryPermission = require('queryPermission');

const options = {
  'projectId': 'gcp-cloud-project-id',
  'path': 'collection/document',
};

if (queryPermission('access_firestore', 'read', options)) {
  Firestore.read('collection/document', {
    projectId: 'gcp-cloud-project-id',
  }).then(data.gtmOnSuccess, data.gtmOnFailure);
}

access_response

표시 이름: 응답 액세스

설명: 응답 본문, 헤더 또는 상태에 액세스합니다.

구성: 다양한 하위 구성요소에 대한 액세스를 제어하기 위한 하위 옵션으로, 임의 또는 특정 액세스를 허용하는 옵션입니다.

요청자: setPixelResponse, setResponseBody, setResponseHeader, setResponseStatus

쿼리 서명: queryPermission('access_response', 'write', <component>[, <optional component name>])

참고: 발신 HTTP 응답 구성요소에 액세스할 수 있는지 여부를 지정합니다.

예시 코드

const queryPermission = require('queryPermission');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
if (queryPermission('access_response', 'write', 'header', 'Content-Type')) {
  setResponseHeader('Content-Type', 'text/plain');
}
if (queryPermission('access_response', 'write', 'body')) {
  setResponseBody('Not Found');
}
if (queryPermission('access_response', 'write', 'status')) {
  setResponseStatus(404);
}

access_template_storage

표시 이름: 템플릿 스토리지 액세스

설명: 서버 측 절차를 진행하는 내내 지속 가능한 템플릿에 사용되는 임시 스토리지에 대한 액세스를 허용합니다.

구성: 없음

요청자: templateDataStorage

쿼리 서명: queryPermission('access_template_storage')

예시 코드

const queryPermission = require('queryPermission');
const templateDataStorage = require('templateDataStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateDataStorage.getItemCopy(key);
}

get_cookies

표시 이름: 쿠키 값을 읽습니다.

설명: 지정된 이름을 가진 쿠키의 값을 읽습니다.

구성: 읽을 수 있는 쿠키 이름 목록입니다.

요청자: getCookieValues

쿼리 서명: queryPermission('get_cookies', <name>)

참고: 이름에 따라 쿠키를 읽을 수 있는지 여부를 지정합니다.

예시 코드

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

logging

표시 이름: 콘솔에 로깅

설명: 개발자 콘솔 및 태그 관리자의 미리보기 모드에 로깅합니다.

구성: 프로덕션에서 로깅을 사용 설정하는 옵션입니다. 기본값은 디버그/미리보기에서만 로깅을 사용 설정하는 것입니다. 권한이 거부되는 경우 logToConsole에서 오류가 발생하지는 않지만 로그 메시지를 차단합니다.

요청자: logToConsole

쿼리 서명: queryPermission('logging')

참고: 맞춤 템플릿에서 개발자 콘솔에 로깅할 수 있는지 여부를 관리합니다.

예시 코드

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

use_message

표시 이름: 메시지 사용

설명: addMessageListener 또는 sendMessage API를 사용하여 메시지를 보내거나 받습니다.

구성: 메시지 유형, 그리고 템플릿에서 수신 대기, 전송 또는 둘 다 가능한지 여부를 지정하는 옵션입니다.

요청자: addMessageListener, sendMessage

쿼리 서명: queryPermission('use_message', <usage>, <message type>)

참고: Usage는 listen, send 또는 listen_and_send 중 하나일 수 있습니다.

예시 코드

const queryPermission = require('queryPermission');
const sendMessage = require('sendMessage');
if (queryPermission('use_message', 'send', 'set_cookie')) {
  sendMessage('set_cookie', {name: 'foo', value: 'bar'});
}

read_container_data

표시 이름: 컨테이너 데이터를 읽습니다.

설명: 컨테이너에 대한 데이터를 읽습니다.

구성: 없음

요청자: getClientName, getContainerVersion

쿼리 서명: queryPermission('read_container_data')

참고: 맞춤 템플릿이 컨테이너 데이터를 읽을 수 있는지 여부를 관리합니다.

예시 코드

const getContainerVersion = require('getContainerVersion');
const queryPermission = require('queryPermission');
if (queryPermission('read_container_data')) {
  return getContainerVersion();
}

read_event_data

표시 이름: 이벤트 데이터 읽기

설명: 이벤트에서 데이터를 읽습니다.

구성: 모든 액세스 또는 허용된 키 경로 목록에 의해 제어되는 특정 액세스를 허용하는 옵션입니다(와일드 카드 구문 지원).

요청자: getAllEventData, getEventData

쿼리 서명: queryPermission('read_event_data'[, <optional key>])

참고: 맞춤 템플릿이 지정된 키 경로에서 이벤트 데이터를 읽을 수 있는지(또는 키 경로가 제공되지 않은 경우 모든 이벤트 데이터) 여부를 관리합니다.

예시 코드

const getAllEventData = require('getAllEventData');
const queryPermission = require('queryPermission');
if (queryPermission('read_event_data')) {
  return getAllEventData();
}

const getEventData = require('getEventData');
const queryPermission = require('queryPermission');
const keyPath = 'parentField.childField';
if (queryPermission('read_event_data', keyPath)) {
  return getEventData(keyPath);
}

read_event_metadata

표시 이름: 이벤트 메타데이터를 읽습니다.

설명: 이벤트 콜백의 이벤트 메타데이터를 읽습니다.

구성: 없음

요청자: addEventCallback

쿼리 서명: queryPermission('read_event_metadata')

참고: 맞춤 템플릿이 콜백의 이벤트 메타데이터를 읽도록 허용할지를 관리합니다.

예시 코드

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_request

표시 이름: HTTP 요청 읽기

설명: 요청 헤더, 쿼리 매개변수, 본문, 경로 또는 원격 IP 주소를 읽습니다.

구성: 다양한 하위 구성요소에 대한 액세스를 제어하기 위한 하위 옵션으로, 임의 또는 특정 액세스를 허용하는 옵션입니다.

요청자: extractEventsFromMpv1, extractEventsFromMpv2, getRemoteAddress, getRequestBody, getRequestHeader, getRequestPath, getRequestQueryParameter, getRequestQueryParameters, getRequestQueryString

쿼리 서명: queryPermission('read_request', <component>[, <optional component name>])

참고: 수신 HTTP 응답 구성요소에 액세스할 수 있는지 여부를 지정합니다.

예시 코드

const queryPermission = require('queryPermission');
const getRequestBody = require('getRequestBody');
const getRequestHeader = require('getRequestHeader');
let body, contentType;
if (queryPermission('read_request', 'body')) {
  body = getRequestBody();
}
if (queryPermission('read_request', 'header', 'content-type')) {
  contentType = getRequestHeader('content-type');
}
if (body && contentType == 'application/json') { ... }

return_response

표시 이름: 응답 반환

설명: 발신자에게 응답을 반환합니다.

구성: 없음

요청자: returnResponse

쿼리 서명: queryPermission('return_response')

참고: 이 권한은 범위를 좁힐 수 있는 필드를 제공하지 않으며, 일반적으로 쿼리되지 않습니다.

run_container

표시 이름: 컨테이너 실행

설명: 이벤트가 포함된 컨테이너를 실행합니다.

구성: 없음

요청자: runContainer

쿼리 서명: queryPermission('run_container')

참고: 이 권한은 범위를 좁힐 수 있는 필드를 제공하지 않으며, 일반적으로 쿼리되지 않습니다.

send_http

표시 이름: HTTP 요청 보내기

설명: 지정된 URL에 HTTP 요청을 보냅니다.

요청자: getGoogleScript, sendEventToGoogleAnalytics, sendHttpGet, sendHttpRequest

쿼리 서명: queryPermission('send_http', <url>)

참고: URL에 따라 HTTP 요청 가능 여부를 지정합니다. 보안 연결을 보장하기 위해 보안 (HTTPS) URL만 허용됩니다.

예시 코드

const queryPermission = require('queryPermission');
const sendHttpGet = require('sendHttpGet');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_http', url)) {
  sendHttpGet(url);
}

send_pixel_from_browser

표시 이름: 브라우저에서 픽셀 보내기

설명: 브라우저에서 지정된 URL에 GET 요청을 보냅니다.

요청자: sendPixelFromBrowser

쿼리 서명: queryPermission('send_pixel_from_browser', <url>)

참고: URL에 따라 브라우저에서 요청을 보낼 수 있는지 여부를 지정합니다.

예시 코드

const queryPermission = require('queryPermission');
const sendPixelFromBrowser = require('sendPixelFromBrowser');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_pixel_from_browser', url)) {
  sendPixelFromBrowser(url);
}

set_cookies

표시 이름: 쿠키를 설정합니다.

설명: 지정된 이름 및 매개변수로 쿠키를 설정합니다.

구성: 허용된 쿠키 이름(이름마다 제한사항이 있을 수 있음), 도메인, 경로, secure 속성 및 만료를 나타내는 표입니다.

요청자: setCookie

쿼리 서명: queryPermission('set_cookies', <name>, <options>)

참고: 쿠키 이름, 도메인, 경로, secure 속성, 만료에 따라 지정된 'Set-Cookie' 헤더를 응답에 추가할 수 있는지 여부를 지정합니다.

예시 코드

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

use_custom_private_keys

표시 이름: 맞춤 비공개 키 사용

설명: 암호화 작업에 JSON 키 파일의 비공개 키를 사용합니다.

구성: 허용된 키 ID 목록입니다. ID는 서버의 SGTM_CREDENTIALS 환경 변수에서 참조하는 JSON 키 파일의 키와 일치해야 합니다.

요청자: hmacSha256

쿼리 서명: queryPermission('use_custom_private_keys', <key id>)

참고: 허용된 비공개 키 목록을 지정합니다.

예시 코드

const hmacSha256= require('hmacSha256');
const queryPermission = require('queryPermission');
const keyId = 'key1';

let result;
if (queryPermission('use_custom_private_keys', keyId)) {
  result = hmacSha256('my_data', keyId);
}

use_google_credentials

표시 이름: Google 애플리케이션 기본 사용자 인증 정보 사용

설명: Google 기본 사용자 인증 정보를 사용하여 Google API를 호출합니다.

구성: 허용된 Google OAuth 2.0 범위 목록입니다.

요청자: getGoogleAuth

쿼리 서명: queryPermission('use_google_credentials', <scopes>)

참고: Google API와 함께 사용할 수 있는 허용된 Google OAuth 2.0 범위를 제한합니다.

예시 코드

const getGoogleAuth = require('getGoogleAuth');
const queryPermission = require('queryPermission');

const scopes = [
  'https://www.googleapis.com/auth/datastore'
];

let auth;
if (queryPermission('use_google_credentials', scopes)) {
  auth = getGoogleAuth(scopes);
}