API ของแท็ก Google (gtag.js) ประกอบด้วยฟังก์ชันเดียว (gtag()
) ซึ่งมีไวยากรณ์ต่อไปนี้
gtag(<command>, <command parameters>);
<command>
คือคำสั่งใดคำสั่งหนึ่งต่อไปนี้<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)
อาร์กิวเมนต์ | Type | ตัวอย่าง | คำอธิบาย |
---|---|---|---|
<target> | string |
G-XXXXXXXXXX |
เป้าหมายที่จะดึงข้อมูลค่า |
<ชื่อช่อง> | 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...
})
ส่งเหตุการณ์ไปยัง 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 จะช่วยให้คุณกำหนดพารามิเตอร์ที่จะเชื่อมโยงกับเหตุการณ์ที่ตามมาทั้งหมดในหน้าเว็บ
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
เช่น คุณแชร์พารามิเตอร์ campaign เพื่อให้แท็กหลายแท็กในหน้าเดียวกันเข้าถึงได้
ตัวอย่างด้านล่างแสดงการตั้งค่าชื่อและรหัสแคมเปญสำหรับกิจกรรมช็อปปิ้งแบล็คฟรายเดย์ เนื่องจากคุณใช้ 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'
});
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 |
จำนวนเต็มบวกใดก็ได้ | ตั้งเวลาเป็นมิลลิวินาทีเพื่อรอการโทรอัปเดตความยินยอม |