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 web và ứng dụng Measurement Protocol của Google Analytics đến máy chủ Google Analytics để có thể xem các sự kiện Measurement Protocol trong báo cáo Google Analytics.

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

Firebase gtag.js

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

Measurement Protocol của Google Analytics chỉ hỗ trợ các yêu cầu POST HTTP.

Để 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>

Mẹo: Nếu bạn muốn dữ liệu của mình được xử lý ở 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 khoá bí mật mới, hãy chuyển đến mục Quản trị > Luồng dữ liệu > chọn luồng của bạn > 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.

Hãy xem tham số truy vấn để biết toàn bộ thông tin tham khảo.

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

• client_id: Giá trị nhận dạng riêng biệt cho một ứng dụng khách. Điều này khác với app_instance_id Firebase. Sử dụng gtag.js('get').

• user_id: Không bắt buộc. Giá trị nhận dạng riêng biệt cho một người dùng. Chỉ được chứa các ký tự UTF-8. Hãy xem bài viết User-ID để có dữ liệu phân tích trên nhiều nền tảng để biết thêm thông tin về giá trị nhận dạng này.

• consent: Không bắt buộc. Tìm hiểu cách đặt chế độ cài đặt về sự đồng ý.

• user_location: Không bắt buộc. Thông tin địa lý cho các sự kiện trong yêu cầu.

• ip_override: Không bắt buộc. Địa chỉ IP mà Google Analytics sẽ lấy thông tin địa lý cho các sự kiện trong yêu cầu.

  Google Analytics sẽ bỏ qua trường này nếu yêu cầu cũng bao gồm user_location.

• timestamp_micros: Không bắt buộc. Khoảng thời gian Unix, tính bằng micro giây, cho các sự kiện và thuộc tính người dùng trong yêu cầu. Nếu không được chỉ định, mặc định là thời gian của yêu cầu.

• events: Một mảng các mục sự kiện. Một yêu cầu có thể bao gồm nhiều sự kiện.

  Để hoạt động của người dùng hiển thị trong các báo cáo như Theo thời gian thực, bạn phải cung cấp engagement_time_msec và session_id như một phần của params cho event. Tham số engagement_time_msec phải phản ánh thời gian tương tác của sự kiện tính bằng mili giây.

  Ví dụ:

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

Mặc dù session_start là tên sự kiện được dành riêng, như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 hoạt động.

Dùng thử

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

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    }
  })
});

Ghi đè dấu thời gian

Measurement Protocol sử dụng dấu thời gian đầu tiên mà nó tìm thấy trong danh sách sau đây cho mỗi sự kiện trong yêu cầu:

1. timestamp_micros của sự kiện.
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 sẽ gửi dấu thời gian cấp yêu cầu áp dụng cho tất cả các sự kiện trong yêu cầu. Do đó, Measurement Protocol gán dấu thời gian requestUnixEpochTimeInMicros cho cả sự kiện tutorial_begin và join_group.

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

Ví dụ sau đây gửi cả dấu thời gian cấp yêu cầu và dấu thời gian cấp sự kiện. Do đó, Measurement Protocol sẽ gán dấu thời gian tutorialBeginUnixEpochTimeInMicros cho sự kiện tutorial_begin và dấu thời gian requestUnixEpochTimeInMicros cho sự kiện join_group.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

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 các tính năng 360, hãy xem bài viết Google Analytics 360.

• 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ặt hàng) 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) phải có tối đa 100 ký tự đối với tài sản Google Analytics chuẩn và 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.
• Các sự kiện Measurement Protocol của ứng dụng được gửi đến Google Analytics sẽ 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 khác 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.