Gửi các sự kiện Measurement Protocol đến Google Analytics

Hướng dẫn này giải thích cách bạn có thể gửi sự kiện luồng dữ liệu web và ứng dụng Measurement Protocol của Google Analytics đến một máy chủ Google Analytics để bạn có thể xem các sự kiện Measurement Protocol trong báo cáo Google Analytics.

Chọn nền tảng bạn muốn xem trong hướng dẫn này:

Firebase gtag.js

Định dạng yêu cầu

Nền tảng Measurement Protocol của Google Analytics chỉ hỗ trợ các yêu cầu HTTP POST.

Để gửi một sự kiện, hãy sử dụng định dạng sau:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

Lưu ý: Nếu bạn muốn dữ liệu của mình được thu thập ở Liên minh Châu Âu, hãy thay đổi HOST trong ví dụ thành region1.google-analytics.com.

Bạn phải cung cấp những thông tin sau trong URL yêu cầu:

• api_secret: MÃ THÔNG BÁO BÍ MẬT CHO API được tạo trong giao diện người dùng Google Analytics.

  Để tạo một khoá bí mật mới, hãy chuyển đến mục Quản trị > Thu thập và sửa đổi dữ liệu > Luồng dữ liệu > chọn luồng của bạn > Khoá bí mật API Measurement Protocol > Tạo.

• measurement_id: Mã đo lường được liên kết với một luồng, có trong giao diện người dùng Google Analytics ở mục Quản trị > Luồng dữ liệu > chọn luồng của bạn > Mã đo lường.

  measurement_id không phải là Mã luồng của bạn.

Bạn phải cung cấp một nội dung yêu cầu ở định dạng nội dung POST JSON cho Measurement Protocol. Ví dụ:

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

Mặc dù session_start là một tên sự kiện được dành riêng, việc tạo session_id mới sẽ tạo ra một phiên mới mà không cần gửi session_start. Tìm hiểu cách tính số phiên.

Dùng thử

Dưới đây là ví dụ bạn có thể dùng để gửi nhiều sự kiện cùng một lúc. Ví dụ này gửi sự kiện tutorial_begin và sự kiện join_group đến máy chủ Google Analytics của bạn, bao gồm thông tin địa lý bằng cách sử dụng trường user_location và bao gồm thông tin thiết bị bằng cách sử dụng trường device.

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

Ghi đè dấu thời gian

Measurement Protocol sử dụng dấu thời gian đầu tiên mà giao thức này tìm thấy trong danh sách sau cho mỗi sự kiện và thuộc tính người dùng trong yêu cầu:

1. timestamp_micros của sự kiện hoặc thuộc tính người dùng.
2. timestamp_micros của yêu cầu.
3. Thời gian Measurement Protocol nhận được yêu cầu.

Ví dụ sau đây gửi dấu thời gian ở cấp yêu cầu áp dụng cho tất cả sự kiện và thuộc tính người dùng trong yêu cầu. Do đó, Measurement Protocol sẽ chỉ định dấu thời gian requestUnixEpochTimeInMicros cho các sự kiện tutorial_begin và join_group cũng như thuộc tính người dùng customer_tier.

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

Ví dụ sau đây sẽ gửi dấu thời gian ở cấp yêu cầu, dấu thời gian ở cấp sự kiện và dấu thời gian ở cấp thuộc tính người dùng. Do đó, Measurement Protocol sẽ chỉ định các dấu thời gian sau:

• tutorialBeginUnixEpochTimeInMicros cho sự kiện tutorial_begin
• customerTierUnixEpochTimeInMicros cho thuộc tính người dùng customer_tier
• requestUnixEpochTimeInMicros cho sự kiện join_group và thuộc tính người dùng 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"
    }
  }
}

Hành vi xác thực đối với các sự kiện và thuộc tính người dùng trong quá khứ

Bạn có thể đặt ngày cho sự kiện và thuộc tính người dùng trong khoảng thời gian tối đa là 72 giờ. Nếu giá trị timestamp_micros sớm hơn 72 giờ trước, thì Measurement Protocol sẽ chấp nhận hoặc từ chối sự kiện hoặc thuộc tính người dùng như sau:

• Nếu bạn không đặt hoặc đặt validation_behavior thành RELAXED, thì Giao thức đo lường sẽ chấp nhận sự kiện hoặc thuộc tính người dùng nhưng ghi đè dấu thời gian của sự kiện hoặc thuộc tính đó thành 72 giờ trước.
• Nếu validation_behavior được đặt thành ENFORCE_RECOMMENDATIONS, thì Measurement Protocol sẽ từ chối sự kiện hoặc thuộc tính người dùng.

Các điểm hạn chế

Các giới hạn sau đây áp dụng cho việc gửi sự kiện Measurement Protocol đến Google Analytics:

Lưu ý: Để biết thông tin về các hạn chế của tính năng 360, hãy xem bài viết Google Analytics 360.

• Các yêu cầu có thể có tối đa 25 sự kiện.
• Sự kiện có thể có tối đa 25 thông số.
• Sự kiện có thể có tối đa 25 thuộc tính người dùng.
• Tên thuộc tính người dùng chỉ được có tối đa 24 ký tự.
• Giá trị thuộc tính người dùng chỉ được có tối đa 36 ký tự.
• Tên sự kiện chỉ được có tối đa 40 ký tự, chỉ được chứa các ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
• Tên thông số (bao gồm cả thông số mục) chỉ được có tối đa 40 ký tự, chỉ được chứa ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
• Giá trị tham số (kể cả giá trị tham số của mặt hàng) chỉ được có tối đa 100 ký tự đối với tài sản Google Analytics chuẩn và tối đa 500 ký tự đối với tài sản Google Analytics 360.
• Thông số mặt hàng có thể có tối đa 10 thông số tuỳ chỉnh.
• Nội dung bài đăng phải nhỏ hơn 130 kB.
• Dấu thời gian phải trong vòng 72 giờ qua. Hãy xem phần Hành vi xác thực cho các sự kiện trước đây để biết thông tin chi tiết.
• Các sự kiện Measurement Protocol của ứng dụng được gửi đến Google Analytics không điền sẵn đối tượng Tìm kiếm trong Google Ads cho người dùng ứng dụng.

Để biết các yêu cầu bổ sung của từng trường hợp sử dụng, hãy xem các trường hợp sử dụng phổ biến.