이 페이지는 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() 명령어를 호출할 수 있습니다. 페이지에 스니펫을 추가하는 방법을 알아보려면 설치 가이드를 참고하세요.

매개변수 범위

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

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

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

매개변수 우선순위

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

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// 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>' });

`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
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', {campaign_name: 'Spring_Sale'});

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

`set`

set 명령어를 사용하면 페이지의 모든 후속 이벤트와 연결되는 매개변수를 정의할 수 있습니다.

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

예를 들어 캠페인 매개변수를 공유하여 동일한 페이지의 여러 태그에서 액세스할 수 있도록 할 수 있습니다.

아래 예는 블랙 프라이데이 쇼핑 이벤트의 캠페인 이름과 ID를 설정하는 방법을 보여줍니다. set를 사용했으므로 GA4 이벤트 태그 또는 Google Ads 리마케팅 태그와 같은 다른 모든 태그가 이 데이터에 액세스할 수 있습니다.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`event`

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

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

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

추천 이벤트. 각 추천 이벤트는 추천 매개변수를 사용할 수 있습니다.
맞춤 이벤트. 맞춤 이벤트는 임의의 매개변수를 통해 구성되는 임의의 이벤트 이름입니다. 자세한 내용은 이벤트 설정하기를 참고하세요.

<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`	모든 양의 정수	동의 업데이트 호출을 기다리는 시간을 밀리초 단위로 설정합니다.