เอกสารอ้างอิง 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)

FieldName

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

ตัวอย่าง

รับค่าใน Promise

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

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

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