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

Các mã nhận dạng và tham số bắt buộc đối với yêu cầu Measurement Protocol phụ thuộc vào việc bạn đang gửi sự kiện đến Luồng dữ liệu web hay Luồng dữ liệu ứng dụng.

  • Đối với Luồng dữ liệu web (thường được đo lường bằng gtag.js hoặc Trình quản lý thẻ của Google), bạn sử dụng measurement_id trong URL yêu cầu và client_id trong nội dung JSON để xác định thực thể người dùng. client_id phải khớp với mã nhận dạng do thẻ Google Analytics tạo trên trang web của bạn.
  • Đối với Luồng ứng dụng (được gắn mã theo dõi bằng Firebase SDK), bạn sử dụng firebase_app_id trong URL yêu cầu và app_instance_id trong nội dung JSON do Google Analytics cho Firebase SDK cung cấp.

Hướng dẫn này cung cấp ví dụ cho cả hai trường hợp.

Các thành phần chính của yêu cầu theo loại luồng

Thành phần Luồng dữ liệu web (gtag.js/GTM) Luồng dữ liệu ứng dụng (Firebase)
Tham số URL luồng dữ liệu measurement_id firebase_app_id
Tham số URL mã thông báo bí mật cho API Bắt buộc Bắt buộc
Trường nội dung JSON mã thiết bị client_id app_instance_id

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

Thẻ này hướng dẫn cách gửi các sự kiện từ máy chủ của bạn tương quan với hoạt động của người dùng trong Luồng dữ liệu ứng dụng bằng SDK Google Analytics cho Firebase. Xin lưu ý rằng các yêu cầu này sử dụng firebase_app_id và app_instance_id.

Điều kiện tiên quyết

Để gửi sự kiện bằng Measurement Protocol, bạn cần có các mã nhận dạng cụ thể từ tài sản Google Analytics hoặc dự án Firebase.

Mã thông báo bí mật cho API

api_secret được dùng để xác thực các yêu cầu của bạn. Bạn cần phải giữ bí mật này.

Cách tạo một mã thông báo bí mật mới:

  1. Chuyển đến Google Analytics rồi chuyển đến tài khoản và tài sản của bạn.
  2. Nhấp vào Quản trị ở dưới cùng bên trái.
  3. Trong mục Thu thập và sửa đổi dữ liệu, hãy nhấp vào Luồng dữ liệu.
  4. Chọn luồng dữ liệu Web hoặc Ứng dụng.
  5. Nhấp vào Mã thông báo bí mật cho API Measurement Protocol.
  6. Nhấp vào Tạo.
  7. Nhập biệt hiệu cho mã thông báo bí mật rồi nhấp vào Tạo.

  8. Sao chép Giá trị của mã thông báo bí mật.

Mã ứng dụng Firebase

firebase_app_id xác định ứng dụng Firebase của bạn. Mã này khác với app_instance_id.

Cách tìm mã ứng dụng Firebase:

  1. Mở dự án của bạn trong bảng điều khiển của Firebase.
  2. Nhấp vào biểu tượng bánh răng cài đặt bên cạnh Tổng quan về dự án rồi chọn Cài đặt dự án.
  3. Trong thẻ Chung, hãy chuyển đến phần Ứng dụng của bạn.
  4. Chọn ứng dụng iOS hoặc Android cụ thể.
  5. Sao chép giá trị Mã ứng dụng.

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

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?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

Bạn phải cung cấp những thông tin sau trong các tham số truy vấn URL yêu cầu (xem Điều kiện tiên quyết để biết thông tin chi tiết về cách tìm hoặc tạo các giá trị này):

  • api_secret: Mã thông báo bí mật cho API để xác thực yêu cầu.
  • firebase_app_id: Mã ứng dụng Firebase của ứng dụng.

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

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

Bạn phải cung cấp app_instance_id trong nội dung yêu cầu để xác định một lượt cài đặt duy nhất của ứng dụng di động. Xin lưu ý rằng mã này khác với firebase_app_id xác định chính ứng dụng. Để biết thêm thông tin về app_instance_id và cách truy xuất mã này bằng Firebase SDK, hãy xem tài liệu tham khảo về mã thực thể ứng dụng.

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 phiên mới mà không cần gửi session_start. Tìm hiểu cách tính số phiên được.

Dùng thử

Dưới đây là ví dụ mà 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 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"
    }
  })
});

Định dạng của firebase_app_id là dành riêng cho nền tảng. Xem Mã ứng dụng trong Tệp và đối tượng cấu hình Firebase.

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 từng 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 mà 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ả cá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 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ể lùi ngày cho các sự kiện và thuộc tính người dùng tối đa 72 giờ. Nếu giá trị timestamp_micros sớm hơn 72 giờ trước, 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 validation_behavior không được đặt hoặc được đặt thành RELAXED, Measurement Protocol 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 người dùng thành 72 giờ trước.
  • Nếu validation_behavior được đặt thành ENFORCE_RECOMMENDATIONS, Measurement Protocol sẽ từ chối sự kiện hoặc thuộc tính người dùng.

Các sự kiện được gửi bằng Measurement Protocol nhằm mục đích được kết hợp hoặc xử lý cùng với các sự kiện được thu thập bằng SDK Google Analytics cho Firebase hoặc gtag.js phải được Google Analytics nhận trong vòng 48 giờ kể từ dấu thời gian sự kiện ban đầu ở phía máy khách. Các sự kiện nhận được muộn hơn thời gian này có thể không được xử lý như mong đợi, đặc biệt là đối với các mục đích như phân bổ lượt chuyển đổi.

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

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

  • Bạn có thể gửi tối đa 100 triệu yêu cầu không phải lượt chuyển đổi mỗi giờ cho mỗi tài sản. Một yêu cầu là yêu cầu không phải lượt chuyển đổi nếu không có sự kiện nào trong yêu cầu là sự kiện quan trọng mà có lượt chuyển đổi trong Google Ads. Nếu bạn vượt quá giới hạn này, Measurement Protocol sẽ tự động bỏ qua tất cả các yêu cầu không phải lượt chuyển đổi cho tài sản trong phần còn lại của giờ.

  • 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ố (bao gồm 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.

    Giới hạn này không áp dụng cho các tham số session_id và session_number khi các giá trị của tham số này được cung cấp bởi các biến tích hợp tương ứng là Mã phiên Analytics và Số phiên Analytics trong Trình quản lý thẻ của Google.

  • Tham số mục có thể có tối đa 10 tham số tuỳ chỉnh.

  • Nội dung bài đăng phải nhỏ hơn 130 kB.

  • Các sự kiện trong Measurement Protocol đượ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.

  • Một số tên sự kiện, tham số và thuộc tính người dùng được dành riêng và không thể sử dụng. Xem phần Tên dành riêng để biết thông tin chi tiết.

Tên dành riêng

Measurement Protocol có một số tên dành riêng mà bạn không thể sử dụng cho sự kiện, tham số hoặc thuộc tính người dùng.

Các tên sự kiện sau đây thường gây nhầm lẫn:

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