Google의 새로운 태그 플랫폼 문서를 미리 확인해 주셔서 감사합니다. 이 사이트는 공개 베타 버전입니다 (의견 보내기).

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google 태그 API 참조

Google 태그(gtag.js) API는 다음 문법과 함께 단일 함수 gtag()로 구성됩니다.

gtag(<command>, <command parameters>);

<command>는 다음 명령어 중 하나입니다.
- config
- get
- set
- event
- consent
<command parameters>는 gtag()에 전달할 수 있는 매개변수입니다. 명령어 매개변수는 명령어에 따라 다르며, 아래의 명령어 참조를 참고하세요.

명령어가 Google 태그 스니펫 아래에 표시된다면 페이지 어디서나 gtag() 명령어를 호출할 수 있습니다. 페이지에 스니펫을 추가하는 방법을 알아보려면 설치 가이드를 참고하세요.

`config`

대상에 구성 정보를 부가적으로 추가할 수 있습니다. 일반적으로 제품의 제품별 구성이지만, Google Ads와 Google 애널리틱스를 모두 사용하는 경우 한 번만 구성하면 됩니다.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID>는 Google 애널리틱스 속성 또는 Google Ads 계정과 같은 조회 대상을 고유하게 식별하는 식별자입니다. <additional_config_info>는 하나 이상의 매개변수-값 쌍입니다.

이 예시에서는 Google Ads 계정으로 데이터를 보내도록 다음과 같이 태그를 구성합니다.

gtag('config', 'TAG_ID');

여기서 'TAG_ID'는 Google 태그의 태그 ID입니다.

다음 예시에서는 추가 구성 정보를 전송하는 방법을 보여주며, false 값을 전달하는 send_page_view 매개변수와 'agency' 값을 전달하는 groups 매개변수를 통해 태그를 구성하여 데이터를 애널리틱스 계정으로 전송합니다.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

`get`

set 명령어로 설정한 값을 비롯해 gtag.js에서 다양한 값을 가져올 수 있습니다.

gtag('get', '<target>', '<field_name>', callback)

인수	유형	예	설명
<target>	`string`	G-XXXXXXXXXX	값을 가져올 대상입니다.
<field_name>	FieldName	client_id	가져올 필드의 이름입니다.
콜백	`Function`	`(field) => console.log(field)`	요청된 필드를 사용해 호출될 함수이거나, `undefined`(설정되지 않은 경우)입니다.

FieldName

필드 이름은 gtag('set') 명령어로 설정한 맞춤 필드의 이름이거나 다음 값 중 하나일 수 있습니다.

필드 이름	지원되는 대상
client_id	Google 애널리틱스 4 Google 애널리틱스 유니버설 애널리틱스
session_id	Google 애널리틱스 4
gclid	Google Ads 플러드라이트

예

프로미스로 값 가져오기

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

측정 프로토콜에 이벤트 전송하기

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

설정한 값 가져오기

gtag('set', {currency: 'USD'});

gtag('get', 'G-XXXXXXXXXX', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

`set`

페이지의 모든 후속 gtag() 호출에서 지속되는 값을 설정할 수 있습니다.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

<parameter-value-pair>는 키 이름이자 gtag() 호출 전반에서 유지될 값입니다. 예를 들어 아래 코드는 페이지의 모든 후속 이벤트에 대해 country 값을 'US'로, currency 값을 'USD'로 설정합니다.

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

set 명령어를 사용하는 일은 값을 event 명령어에 직접 전달하는 일과 다릅니다. 값을 event 명령어에 직접 전달하면 이러한 값은 실행되는 이벤트에만 적용됩니다. 그러나 set를 사용하면 값이 현재 페이지에 유지되며 모든 후속 이벤트와 함께 전달됩니다. 다음 두 예시를 통해 대조해 보세요.

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

다음 URL은

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

첫 번째 예시에서는 login 이벤트가 'Google'의 method 값과 함께 전달되고, share 이벤트는 어떠한 매개변수도 없이 전달됩니다. 두 번째 예시에서는 login 및 share 모두 'Google'의 method 값과 함께 전달됩니다.

`event`

event 명령어를 사용하여 이벤트 데이터를 전송합니다.

gtag('event', '<event_name>', {<event_params>});

<event_name>은 다음 중 하나입니다.

추천 이벤트. 각 추천 이벤트는 추천 매개변수를 사용할 수 있습니다.
맞춤 이벤트. 맞춤 이벤트는 임의의(즉, 맞춤) 매개변수를 통해 구성되는 임의의 이벤트 이름입니다. Google 애널리틱스에서 맞춤 이벤트가 사용되는 방법을 참고하세요.

<event_params>는 하나 이상의 매개변수-값 쌍이며, 각 쌍은 쉼표로 구분됩니다.

다음 event 명령어는 두 매개변수(app_name 및 screen_name)를 사용하여 추천 이벤트 screen_view를 실행합니다.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

`consent`

consent 명령어를 사용하여 동의를 구성합니다.

gtag('consent', {<consent_arg>}, {<consent_params>});

이러한 매개변수가 구성하는 동작에 대한 자세한 내용은 고객센터의 동의 페이지를 참고하세요.

<consent_arg>는 'default' 또는 'update' 중 하나입니다. 'default'는 사용해야 하는 기본 동의 매개변수를 설정하는 데 사용되고, 'update'는 사용자가 동의를 표시한 후 이러한 매개변수를 업데이트하는 데 사용됩니다.

지원되는 <consent_params>는 다음과 같습니다.

필드 이름	허용되는 값	설명
`ad_storage`	`'granted'` \| `'denied'`	광고와 관련된 쿠키 (웹) 또는 기기 식별자 (앱)와 같은 저장을 사용 설정합니다.
`ad_user_data`	`'granted'` \| `'denied'`	광고 목적으로 사용자 데이터를 Google에 전송하는 데 대한 동의를 설정합니다.
`ad_personalization`	`'granted'` \| `'denied'`	개인 맞춤 광고에 대한 동의를 설정합니다.
`analytics_storage`	`'granted'` \| `'denied'`	방문 시간 등 분석과 관련된 쿠키 (웹) 또는 앱 식별자 (앱)를 저장할 수 있도록 합니다.
`wait_for_update`	모든 양의 정수	동의 업데이트 호출을 기다릴 시간을 밀리초 단위로 설정합니다.

매개변수 범위

매개변수 값의 범위를 개별 이벤트, 특정 <TARGET_ID>로 전송되는 모든 이벤트 또는 모든 이벤트에 전체적으로 지정할 수 있습니다. 범위를 지정하려면 event, config, set 명령어를 사용합니다.

한 범위에 설정된 매개변수 값은 다른 범위에 있는 동일한 매개변수에 설정된 값을 수정하지 않습니다. 아래 예시에서 config 명령어는 이전에 set 명령어를 통해 할당된 currency의 전체 값을 수정하지 않습니다. 두 명령어를 모두 실행한 후에도 currency의 전체 값은 여전히 'EUR'입니다.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

매개변수 우선순위

다양한 범위에서 각기 다른 값이 동일한 매개변수에 할당되면 이벤트가 처리될 때 하나의 값만 사용됩니다. event로 범위가 지정된 매개변수 값은 config로 범위가 지정된 매개변수보다 우선되며, config 매개변수는 set를 통해 전체 범위가 지정된 매개변수보다 우선됩니다.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });