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

คู่มือนี้จะอธิบายวิธีส่ง Google Analytics Measurement Protocol เหตุการณ์สตรีมเว็บและสตรีมแอป ไปยังเซิร์ฟเวอร์ Google Analytics เพื่อให้คุณดูเหตุการณ์ Measurement Protocol ใน รายงาน Google Analyticsได้

ตัวระบุและพารามิเตอร์ที่จำเป็นสำหรับคำขอ Measurement Protocol จะขึ้นอยู่กับว่าคุณส่งเหตุการณ์ไปยังสตรีมเว็บ หรือสตรีมแอป

• สําหรับสตรีมเว็บ (โดยปกติจะใช้ gtag.js หรือ Google Tag Manager) คุณจะใช้ measurement_id ใน URL ของคําขอและ client_id ในเนื้อหา JSON เพื่อระบุอินสแตนซ์ของผู้ใช้ client_id ควรตรงกับรหัสที่แท็ก Google Analytics สร้างขึ้นในเว็บไซต์
• สําหรับสตรีมแอป (ใช้ Firebase SDK) คุณจะใช้ firebase_app_id ใน URL ของคําขอและ app_instance_id ในเนื้อหา JSON ซึ่ง SDK ของ Google Analytics สําหรับ Firebase จะเป็นผู้ระบุ

คู่มือนี้มีตัวอย่างสําหรับทั้ง 2 สถานการณ์

คอมโพเนนต์หลักของคําขอตามประเภทสตรีม

เลือกแพลตฟอร์มที่ต้องการดูในคู่มือนี้

แท็บนี้แสดงวิธีการส่งเหตุการณ์จากเซิร์ฟเวอร์ที่สัมพันธ์กับกิจกรรมของผู้ใช้ในสตรีมแอป โดยใช้ SDK ของ Google Analytics สําหรับ Firebase โปรดทราบว่าคําขอเหล่านี้ใช้ firebase_app_id และ app_instance_id

ข้อกำหนดเบื้องต้น

หากต้องการส่งเหตุการณ์โดยใช้ Measurement Protocol คุณต้องมีตัวระบุที่เฉพาะเจาะจงจากพร็อพเพอร์ตี้ Google Analytics หรือโปรเจ็กต์ Firebase

API Secret

ระบบจะใช้ api_secret เพื่อตรวจสอบสิทธิ์คําขอ คุณต้องเก็บข้อมูลลับนี้ไว้เป็นความลับ

วิธีสร้างข้อมูลลับใหม่

1. ไปที่ Google Analytics แล้วไปยัง บัญชีและพร็อพเพอร์ตี้
2. คลิกผู้ดูแลระบบ ที่ด้านซ้ายล่าง
3. ในส่วนการเก็บรวบรวมข้อมูลและการแก้ไขข้อมูล ให้คลิกสตรีมข้อมูล
4. เลือกสตรีมข้อมูลเว็บหรือแอป
5. คลิก API Secret สำหรับ Measurement Protocol
6. คลิกสร้าง
7. ป้อนชื่อเล่นสําหรับข้อมูลลับ แล้วคลิกสร้าง

8. คัดลอกค่าข้อมูลลับ

รหัสแอป Firebase

firebase_app_id จะระบุแอป Firebase ของคุณ โดยไม่เหมือนกับ app_instance_id

วิธีค้นหารหัสแอป Firebase

1. เปิดโปรเจ็กต์ใน คอนโซล Firebase
2. คลิกไอคอนรูปเฟืองการตั้งค่าข้างภาพรวมโปรเจ็กต์ แล้วเลือกการตั้งค่าโปรเจ็กต์
3. ในแท็บทั่วไป ให้ไปที่ส่วนแอปของคุณ
4. เลือกแอป iOS หรือ Android ที่ต้องการ
5. คัดลอกค่า App ID

จัดรูปแบบคำขอ

Measurement Protocol ของ Google Analytics รองรับเฉพาะคําขอ HTTP POST

หากต้องการส่งเหตุการณ์ ให้ใช้รูปแบบต่อไปนี้

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

คุณต้องระบุข้อมูลต่อไปนี้ในพารามิเตอร์การค้นหาของ URL ที่ขอ (ดู ข้อกำหนดเบื้องต้นสำหรับรายละเอียดเกี่ยวกับวิธีค้นหาหรือสร้างค่าเหล่านี้ )

• api_secret: API Secret เพื่อตรวจสอบสิทธิ์คําขอ
• firebase_app_id: รหัสแอป Firebase ของแอปพลิเคชัน

คุณต้องระบุเนื้อหาของคําขอในรูปแบบเนื้อหา JSON POST สําหรับ Measurement Protocol ตัวอย่าง

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

คุณต้องระบุ app_instance_id ในเนื้อหาของคําขอเพื่อระบุการติดตั้งแอปบนอุปกรณ์เคลื่อนที่ที่ไม่ซ้ำกัน โปรดทราบว่ารหัสนี้แตกต่างจาก firebase_app_id ซึ่งระบุแอปเอง ดูข้อมูลเพิ่มเติมเกี่ยวกับ app_instance_id และวิธีดึงข้อมูลโดยใช้ Firebase SDK ได้ใน เอกสารประกอบอ้างอิง app_instance_id

แม้ session_start จะเป็น ชื่อเหตุการณ์ที่สงวนไว้ แต่การสร้าง session_id ใหม่เป็นการสร้างเซสชันใหม่โดยไม่ต้องส่ง session_start ทำความเข้าใจวิธีคํานวณเซสชัน

ลองใช้

ตัวอย่างที่คุณใช้ส่งเหตุการณ์หลายรายการพร้อมกันได้มีดังนี้ ตัวอย่างนี้ จะส่งเหตุการณ์ tutorial_begin และเหตุการณ์ join_group ไปยังเซิร์ฟเวอร์ Google Analytics รวมถึงข้อมูลทางภูมิศาสตร์โดยใช้ช่อง user_location และข้อมูลอุปกรณ์ โดยใช้ช่อง device

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

รูปแบบของ firebase_app_id จะขึ้นอยู่กับแพลตฟอร์ม ดูรหัสแอปพลิเคชัน ในไฟล์และการกำหนดค่า Firebase

ลบล้างการประทับเวลา

Measurement Protocol จะใช้การประทับเวลา แรก ที่พบในรายการต่อไปนี้สําหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้แต่ละรายการในคําขอ

1. timestamp_micros ของเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้
2. timestamp_micros ของคําขอ
3. เวลาที่ Measurement Protocol ได้รับคําขอ

ตัวอย่างต่อไปนี้จะส่งการประทับเวลาระดับคําขอซึ่งมีผลกับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ทั้งหมดในคําขอ ด้วยเหตุนี้ Measurement Protocol จึงกําหนดการประทับเวลา requestUnixEpochTimeInMicros ให้กับเหตุการณ์ tutorial_begin และ join_group รวมถึงพร็อพเพอร์ตี้ผู้ใช้ customer_tier

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

ตัวอย่างต่อไปนี้จะส่งการประทับเวลาระดับคําขอ การประทับเวลาระดับเหตุการณ์ และการประทับเวลาระดับพร็อพเพอร์ตี้ผู้ใช้ ด้วยเหตุนี้ Measurement Protocol จึงกําหนดการประทับเวลาต่อไปนี้

• tutorialBeginUnixEpochTimeInMicros สําหรับเหตุการณ์ tutorial_begin
• customerTierUnixEpochTimeInMicros สําหรับพร็อพเพอร์ตี้ผู้ใช้ customer_tier
• requestUnixEpochTimeInMicros สําหรับเหตุการณ์ join_group และพร็อพเพอร์ตี้ผู้ใช้ newsletter_reader

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

ลักษณะการทํางานของการตรวจสอบสําหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ที่ผ่านมา

คุณสามารถระบุวันที่ย้อนหลังสําหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 72 ชั่วโมง หากค่า timestamp_micros เก่ากว่า 72 ชั่วโมงที่ผ่านมา Measurement Protocol จะยอมรับหรือปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ดังนี้

• หากไม่ได้ตั้งค่า validation_behavior หรือตั้งค่าเป็น RELAXED Measurement Protocol จะยอมรับเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ แต่จะลบล้างการประทับเวลาเป็น 72 ชั่วโมงที่ผ่านมา
• หากตั้งค่า validation_behavior เป็น ENFORCE_RECOMMENDATIONS Measurement Protocol จะปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้

Google Analytics ควรได้รับเหตุการณ์ที่ส่งโดยใช้ Measurement Protocol ซึ่งมีไว้เพื่อเข้าร่วมหรือประมวลผลร่วมกับเหตุการณ์ที่รวบรวมโดย SDK ของ Google Analytics สําหรับ Firebase หรือ gtag.js ภายใน 48 ชั่วโมง นับจากการประทับเวลาเหตุการณ์ฝั่งไคลเอ็นต์เดิม ระบบอาจไม่ประมวลผลเหตุการณ์ที่ได้รับหลังจากช่วงเวลานี้ตามที่คาดไว้ โดยเฉพาะอย่างยิ่งสําหรับวัตถุประสงค์ต่างๆ เช่น การระบุแหล่งที่มาของ Conversion

ข้อจำกัด

ข้อจํากัดต่อไปนี้มีผลกับการส่งเหตุการณ์ Measurement Protocol ไปยัง Google Analytics