เอกสารอ้างอิง API ของแท็ก Google

API ของแท็ก Google (gtag.js) ประกอบด้วยฟังก์ชันเดียว ซึ่งก็คือ gtag() ที่มี ไวยากรณ์ต่อไปนี้

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

• <command> เป็นคำสั่งอย่างใดอย่างหนึ่งต่อไปนี้
  • config
  • get
  • set
  • event
  • consent
• <command parameters> คือพารามิเตอร์ที่คุณส่งไปยัง gtag() ได้ คำสั่ง พารามิเตอร์จะแตกต่างกันไปตามคำสั่ง อ้างอิงถึงการอ้างอิงคำสั่ง ที่ด้านล่าง

คุณจะเรียกใช้คำสั่ง gtag() ที่ตำแหน่งใดก็ได้ในหน้าเว็บ ตราบใดที่คำสั่งของคุณ ปรากฏใต้ข้อมูลโค้ดแท็ก Google หากต้องการทราบวิธีเพิ่มข้อมูลโค้ดลงใน โปรดดูที่คู่มือการติดตั้ง

ขอบเขตของพารามิเตอร์

คุณสามารถกําหนดขอบเขตของค่าพารามิเตอร์เป็นแต่ละเหตุการณ์ ทุกเหตุการณ์ที่ส่งไปยัง <TARGET_ID> เฉพาะ หรือทั่วโลกสำหรับทุกเหตุการณ์ ซึ่งทำได้โดยการใช้ คำสั่ง event, config และ set

ค่าพารามิเตอร์ที่กำหนดไว้ในขอบเขตหนึ่งจะไม่แก้ไขค่าที่ตั้งไว้สำหรับขอบเขตเดียวกัน ในขอบเขตอื่น ในตัวอย่างด้านล่าง คำสั่ง config ไม่แก้ไขค่าร่วมสำหรับ campaign_id ที่ก่อนหน้านี้กำหนดด้วย set คำสั่ง หลังจากเรียกใช้ทั้ง 2 คำสั่ง ค่าส่วนกลางของ 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 Analytics

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

<TARGET_ID> คือตัวระบุที่ระบุเป้าหมายสำหรับ Hit ได้โดยไม่ซ้ำกัน เช่น พร็อพเพอร์ตี้ Google Analytics หรือบัญชี Google Ads <additional_config_info> คือคู่พารามิเตอร์-ค่าอย่างน้อย 1 คู่

ตัวอย่างนี้กําหนดค่าแท็กให้ส่งข้อมูลไปยังบัญชี Google Ads

gtag('config', 'TAG_ID');

ที่ไหน "TAG_ID" คือรหัสแท็กของแท็ก Google

ในการสาธิตวิธีส่งข้อมูลการกำหนดค่าเพิ่มเติม ลองดูตัวอย่างต่อไปนี้ ที่กำหนดค่าแท็กให้ส่งข้อมูลไปยังบัญชี Analytics พร้อมด้วย พารามิเตอร์ send_page_view ที่ส่งค่า false และ groups พารามิเตอร์ที่ส่งค่า 'agency'

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

get

ช่วยให้คุณได้รับค่าต่างๆ จาก gtag.js รวมถึงค่าที่ตั้งไว้ด้วย คำสั่ง set

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

อาร์กิวเมนต์	ประเภท	ตัวอย่าง	คำอธิบาย
<target>	string	G-XXXXXXXXXX	เป้าหมายที่จะดึงข้อมูลค่า
<field_name>	FieldName	client_id	ชื่อช่องที่จะดึงข้อมูล
Callback	Function	(field) => console.log(field)	ฟังก์ชันที่จะเรียกใช้ด้วยฟิลด์ที่ขอ หรือ undefinedหากไม่ได้ตั้งค่าไว้

FieldName

ชื่อช่องอาจเป็นชื่อของช่องที่กำหนดเองซึ่งคุณตั้งค่าด้วย gtag('set') หรือค่าใดค่าหนึ่งต่อไปนี้

ชื่อช่อง	เป้าหมายที่รองรับ
client_id	Google Analytics 4 Universal Analytics ของ Google Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

หมายเหตุ: หากใช้คำสั่ง set กับชื่อช่องเหล่านี้ ค่าที่คุณกำหนด จะมีความสำคัญเหนือกว่า

ตัวอย่าง

สร้างมูลค่าด้วยคำสัญญา

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

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

ส่งเหตุการณ์ไปยัง Measurement Protocol

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 ให้คุณกำหนดพารามิเตอร์ที่จะเชื่อมโยงกับทุกๆ เหตุการณ์ต่อมาบนหน้าเว็บ

หมายเหตุ: เราขอแนะนำให้ใช้คำสั่ง config หรือ event หากเป็นไปได้

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

เช่น คุณสามารถแชร์แคมเปญ พารามิเตอร์เพื่อให้เข้าถึงได้ง่ายโดยแท็กหลายแท็กในหน้าเดียวกัน

ตัวอย่างด้านล่างแสดงการตั้งชื่อและรหัสแคมเปญสำหรับแบล็คฟรายเดย์ เหตุการณ์ช็อปปิ้ง เนื่องจากคุณใช้แท็ก 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 Analytics

<event_params> คือคู่พารามิเตอร์-ค่าอย่างน้อย 1 คู่ แต่ละคู่คั่นด้วย คอมมา

คำสั่ง event ต่อไปนี้ทำให้เหตุการณ์ screen_view ที่แนะนำเริ่มทำงานด้วย 2 รายการ พารามิเตอร์: app_name และ screen_name

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

สำคัญ: ข้อมูลโค้ดแท็ก Google ต้องปรากฏในหน้าเดียวกัน โดยอยู่ด้านบน event คำสั่ง ไม่เช่นนั้นระบบจะไม่ส่งข้อมูลของคุณ

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	จำนวนเต็มบวกใดก็ได้	ตั้งเวลาเป็นมิลลิวินาทีเพื่อรอการเรียกใช้การอัปเดตความยินยอม