Google 태그(gtag.js) API는 다음 문법과 함께 단일 함수 gtag()
로 구성됩니다.
gtag(<command>, <command parameters>);
<command>
는 다음 명령어 중 하나입니다.<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) |
요청된 필드를 사용해 호출될 함수이거나,
|
FieldName
필드 이름은 gtag('set')
명령어로 설정한 맞춤 필드의 이름이거나 다음 값 중
하나일 수 있습니다.
필드 이름 | 지원되는 대상 |
---|---|
client_id |
|
session_id |
|
gclid |
|
예시
프로미스로 값 가져오기
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>
은 다음 중 하나입니다.
- 추천 이벤트. 각 추천 이벤트는 추천 매개변수를 사용할 수 있습니다.
- 맞춤 이벤트. 맞춤 이벤트는 임의의(즉, 맞춤) 매개변수를 통해 구성되는 임의의 이벤트 이름입니다. 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 |
모든 양의 정수 | 동의 업데이트 호출을 기다릴 시간을 밀리초 단위로 설정합니다. |