Phân tích

API Truy vấn Phân tích cho phép bạn truy vấn các chỉ số trải nghiệm tổng hợp theo khoảng thời gian. API này hỗ trợ:

• Truy vấn số lượng người dùng hoạt động hàng ngày (DAU), doanh thu, tỷ lệ giữ chân và các chỉ số khác cho trải nghiệm của bạn.
• Lọc và nhóm kết quả theo các kích thước như nền tảng, quốc gia, và nhóm tuổi.
• Tự động xử lý các truy vấn chậm dưới dạng các tác vụ dài hạn mà bạn có thể kiểm tra kết quả.

Trước khi sử dụng API này, bạn phải tạo một khóa API cho trải nghiệm của mình. Khi tạo khóa, hãy thêm trải nghiệm của bạn vào Quyền truy cập và cấp quyền truy cập cho thao tác universe.analytics:read trong hệ thống universe-analytics. Bao gồm khóa trong tiêu đề yêu cầu x-api-key trong mỗi yêu cầu.

Tất cả các điểm cuối sử dụng ID vũ trụ của bạn, mà bạn có thể tìm thấy trên Bảng điều khiển Nhà sáng tạo bằng cách chọn trải nghiệm của bạn và sao chép ID Vũ trụ từ trang tổng quan.

Truy vấn một chỉ số

Để truy vấn một chỉ số cho trải nghiệm của bạn:

1. Sao chép khóa API vào tiêu đề yêu cầu x-api-key.
2. Thay thế ${UniverseId} trong URL bằng ID vũ trụ của trải nghiệm của bạn.
3. Đặt metric là chỉ số bạn muốn truy vấn, chẳng hạn như DailyActiveUsers.
4. Đặt granularity thành kích thước bucket thời gian được hỗ trợ, như OneDay. Xem Tùy chọn granularity.
5. Đặt startTime và endTime thành khoảng thời gian bạn muốn, sử dụng dấu thời gian RFC 3339 UTC.
6. Gửi yêu cầu.

Truy vấn số người dùng hoạt động hàng ngày
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Hầu hết các truy vấn hoàn thành ngay lập tức và trả về 200 OK:

Phản hồi (200 OK)
{
  "path": "v1/universes/1234567890/operations/metrics/abc123",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "breakdowns": [],
        "dataPoints": [
          { "time": "2026-01-01T00:00:00Z", "value": 10000 },
          { "time": "2026-01-02T00:00:00Z", "value": 10500 }
        ]
      }
    ]
  }
}

Đối với các khoảng thời gian lớn, API có thể trả về 202 Accepted với "done": false. Xem Các tác vụ dài hạn.

Các trường trong thân yêu cầu

Thời gian bắt đầu startTime sớm nhất bạn có thể sử dụng phụ thuộc vào loại chỉ số:

• Các chỉ số tiêu chuẩn (tương tác, kiếm tiền, thu hút, giữ chân): lên tới 4 năm lịch sử.
• Các chỉ số hiệu suất (tỷ lệ sự cố, tỷ lệ khung hình, v.v.): lên tới 28 ngày lịch sử.

Truy vấn ngoài khoảng thời gian lưu giữ sẽ trả về lỗi 400 với mã 2001.

Các tác vụ dài hạn

Hầu hết các truy vấn hoàn thành ngay lập tức và trả về 200 OK với "done": true. Đối với các truy vấn với các khoảng thời gian lớn hoặc nhiều series phân đoạn, API trả về 202 Accepted với "done": false và một path để kiểm tra.

Đang chờ (202):

{
  "path": "path/to/poll",
  "done": false,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  }
}

Khi done là false, gửi yêu cầu GET đến https://apis.roblox.com/analytics-query-api/{path} — thay thế {path} bằng giá trị path từ phản hồi — sử dụng cùng một tiêu đề x-api-key. Lặp lại cho đến khi done là true.

Hoàn thành (200):

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "breakdowns": [],
        "dataPoints": [
          {
            "time": "2026-01-01T00:00:00Z",
            "value": 10000
          }
        ]
      }
    ]
  }
}

Một mảng breakdowns trống cho biết rằng không có phân đoạn nào được yêu cầu. Khi một phân đoạn được sử dụng, mỗi mục trong response.values tương ứng với một giá trị kích thước. Xem Sử dụng phân đoạn.

Khi thao tác không thành công, thân yêu cầu chứa error thay vì response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "Tỷ lệ granularity được yêu cầu không được hỗ trợ cho chỉ số này."
  }
}

Mỗi mục trong response.values đại diện cho một series, một cho mỗi giá trị kích thước khi sử dụng phân đoạn, hoặc một mục duy nhất với breakdowns: [] khi không có phân đoạn nào được yêu cầu. Mỗi điểm dữ liệu trong dataPoints có:

Các chỉ số có giá trị văn bản

Hầu hết các chỉ số là số và báo cáo kết quả của chúng trong value. Một vài chỉ số mô tả thay vào đó mỗi điểm dữ liệu bằng văn bản thay vì số. Đối với những chỉ số này, dữ liệu được trả về trong một mảng stringValues và value không có nghĩa. Trường stringValues hoàn toàn bị loại bỏ đối với các chỉ số số.

Chẳng hạn, ThumbnailWinningSegments báo cáo các phân đoạn thumbnail chiến thắng cho mỗi bucket thời gian dưới dạng danh sách các chuỗi:

{
  "time": "2026-01-01T00:00:00Z",
  "value": 0,
  "stringValues": ["TopEngagement", "HighCTR"]
}

Trạng thái điểm dữ liệu

Tùy chọn granularity

Trường granularity kiểm soát kích thước của mỗi bucket thời gian trong phản hồi. Ranh giới bucket được căn chỉnh theo UTC. Ví dụ, các bucket OneDay chạy từ nửa đêm UTC đến nửa đêm UTC, vì vậy bất kỳ độ lệch UTC nào trong startTime hoặc endTime sẽ được chuẩn hóa thành UTC trước khi nhóm.

Không phải tất cả các chỉ số đều hỗ trợ mọi granularity. Xem Các chỉ số được hỗ trợ để biết thêm chi tiết.

Sử dụng phân đoạn

Không phải tất cả các chỉ số đều hỗ trợ mọi phân đoạn. Xem Các chỉ số được hỗ trợ để biết các phân đoạn nào có sẵn cho mỗi chỉ số.

Các phân đoạn nhóm kết quả chỉ số theo một kích thước, trả về một series cho mỗi giá trị kích thước duy nhất. Thêm một mảng breakdown với một hoặc nhiều tên kích thước vào yêu cầu của bạn.

Truy vấn doanh thu được phân đoạn theo nền tảng
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyRevenue",
    "granularity": "OneDay",
    "breakdown": ["Platform"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Mỗi mục trong response.values bao gồm một mảng breakdowns xác định giá trị kích thước cho series đó:

{
  "response": {
    "values": [
      {
        "breakdowns": [{ "dimension": "Platform", "value": "Computer" }],
        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 8200 }]
      },
      {
        "breakdowns": [{ "dimension": "Platform", "value": "Phone" }],
        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 3400 }]
      }
    ]
  }
}

Mỗi đối tượng trong breakdowns có:

Lọc kết quả

Các bộ lọc thu hẹp kết quả truy vấn theo các giá trị kích thước cụ thể. Thêm một mảng filter vào yêu cầu của bạn, trong đó mỗi mục chỉ định một dimension, các values cần khớp, và operation để áp dụng.

Truy vấn DAU chỉ cho các thiết bị di động
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "filter": [
        {
            "dimension": "Platform",
            "values": ["Phone", "Tablet"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Các thao tác bộ lọc

Bạn có thể kết hợp các bộ lọc với các phân đoạn trong cùng một yêu cầu.

Khám phá giá trị kích thước

Điểm cuối giá trị kích thước liệt kê các giá trị có sẵn cho một hoặc nhiều kích thước của một chỉ số trong một khoảng thời gian, mà không tính toán chỉ số đó. Sử dụng nó để khám phá các giá trị hợp lệ cho các truy vấn filter và breakdown — chẳng hạn như, quốc gia, ID sản phẩm, hoặc ID bước phễu.

Để truy vấn các giá trị kích thước cho trải nghiệm của bạn:

1. Sao chép khóa API vào tiêu đề yêu cầu x-api-key.
2. Thay thế ${UniverseId} trong URL bằng ID vũ trụ của trải nghiệm của bạn.
3. Đặt metric là chỉ số cung cấp ngữ cảnh cho các kích thước.
4. Đặt dimensions thành các tên kích thước mà bạn muốn lấy giá trị.
5. Đặt startTime và endTime thành khoảng thời gian bạn muốn, sử dụng dấu thời gian RFC 3339 UTC.
6. Gửi yêu cầu.

Khám phá các giá trị quốc gia cho DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/dimension-values' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "dimensions": ["Country"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Các trường trong thân yêu cầu

Hầu hết các truy vấn hoàn thành ngay lập tức và trả về 200 OK với "done": true. Đối với các truy vấn với các khoảng thời gian lớn, API trả về 202 Accepted với "done": false và một path để kiểm tra. Xem Các tác vụ dài hạn để biết quy trình kiểm tra. Khi kiểm tra, hãy sử dụng giá trị path từ phản hồi — nó trỏ đến v1/universes/{universeId}/operations/dimension-values/{operationId}, khác với đường dẫn kiểm tra chỉ số.

Hoàn thành (200):

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "dimension": "Country",
        "values": [{ "value": "US" }, { "value": "GB" }]
      }
    ]
  }
}

Mỗi mục trong response.values đại diện cho một kích thước được yêu cầu. Mỗi đối tượng trong values có:

Các lỗi sử dụng cùng một done: true và vỏ error như điểm cuối chỉ số. Một kích thước không được hỗ trợ cho chỉ số được chỉ định trả về 400 với mã 2001. Xem Các lỗi phổ biến.

Các truy vấn phổ biến

Các ví dụ sau đây cho thấy các truy vấn phổ biến, bao gồm các chỉ số có sẵn trên trang phân tích Bảng điều khiển Nhà sáng tạo.

Doanh thu

Truy vấn doanh thu hàng ngày bằng Robux
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyRevenue",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Tỷ lệ giữ chân D1

Truy vấn tỷ lệ giữ chân D1
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "ForwardD1Retention",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Người dùng mới so với người dùng quay lại

Truy vấn DAU chia theo mới và quay lại
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "breakdown": ["IsNewUser"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Tập hợp hàng tuần

Sử dụng độ granularity thô hơn để có cái nhìn dài hơn với ít điểm dữ liệu hơn. Ở granularity OneWeek, mỗi bucket đếm số người dùng duy nhất trên toàn bộ khoảng thời gian bảy ngày — không phải là tổng số giá trị hàng ngày.

Truy vấn DAU với độ granularity hàng tuần
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneWeek",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-04-01T00:00:00Z"
}'

Phân đoạn Top-N

Để xếp hạng theo một chỉ số và hiển thị một chỉ số khác cho cùng một tập hợp giá trị, hãy sử dụng hai yêu cầu. Ví dụ, để xem tỷ lệ chuyển đổi người dùng trả tiền cho 5 quốc gia hàng đầu theo DAU:

Bước 1: Khám phá 5 giá trị kích thước hàng đầu. Sử dụng granularity: "None" để nhận một kết quả tổng hợp duy nhất và limit để giới hạn số lượng series được trả về:

Khám phá 5 quốc gia hàng đầu theo DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "None",
    "breakdown": ["Country"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z",
    "limit": 5
}'

Bước 2: Truy vấn chỉ số hiển thị, được lọc để giá trị trả về trong bước 1:

Tỷ lệ chuyển đổi người dùng trả tiền cho 5 quốc gia hàng đầu
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "PayingUsersCVR",
    "granularity": "OneDay",
    "breakdown": ["Country"],
    "filter": [
        {
            "dimension": "Country",
            "values": ["US", "GB", "PH", "VN", "DE"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Các bước phễu

Các phễu cho thấy cách người dùng tiến triển qua một chuỗi bước được xác định trong trải nghiệm của bạn. Truy vấn các chỉ số phễu yêu cầu hai yêu cầu, vì các ID bước là động.

Bước 1: Khám phá các bước phễu. Một bước phễu chỉ xuất hiện trong kết quả cho những ngày mà ít nhất một người dùng đã đạt đến bước đó. Sử dụng một khoảng thời gian dài hơn (90 ngày là mặc định an toàn) để đảm bảo các bước ít được đạt đến vẫn xuất hiện trong phản hồi khám phá. Sử dụng granularity: "None" để có một kết quả tổng hợp duy nhất cho mỗi bước:

Khám phá các bước phễu cho phễu Levels
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "FunnelUserTotalCount",
    "granularity": "None",
    "breakdown": ["FunnelStep"],
    "filter": [
        {
            "dimension": "FunnelName",
            "values": ["Levels"],
            "operation": "In"
        }
    ],
    "startTime": "2025-11-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Bước 2: Truy vấn chỉ số phễu cho mỗi bước, được lọc theo các ID bước trả về trong bước 1:

Tỷ lệ bỏ người dùng theo bước cho phễu Levels
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "FunnelUserChurnRate",
    "granularity": "None",
    "breakdown": ["FunnelStep"],
    "filter": [
        {
            "dimension": "FunnelStep",
            "values": ["1", "2", "3", "4", "5"],
            "operation": "In"
        },
        {
            "dimension": "FunnelName",
            "values": ["Levels"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Các lỗi phổ biến

Hầu hết các lỗi được trả về dưới dạng lỗi thao tác truy vấn: thân phản hồi bao gồm "done": true và một đối tượng error với mã số code và chuỗi message. Các lỗi xác thực và tài nguyên (401, 404) là các phản hồi HTTP đơn giản mà không có thân, đó là lý do tại sao bảng dưới đây hiển thị — cho mã lỗi của chúng.