Số liệu thống kê trò chơi là số liệu thống kê tích luỹ về trò chơi của bạn mà người chơi có thể xem trên Hồ sơ người chơi của họ. Những số liệu thống kê này giúp người chơi theo dõi tiến trình từ trước đến nay, xem các thành tích nổi bật và so sánh với những người chơi khác, đồng thời làm nền tảng cho các tính năng của Google Play như Nhiệm vụ, Thử thách cộng đồng và nhiều tính năng khác trong tương lai.
Số liệu thống kê trò chơi phải:
- Không yêu cầu mua hàng (Ví dụ: mua đá quý), tức là không được cập nhật do bất kỳ giao dịch mua hàng trong ứng dụng (IAP) nào.
- Không yêu cầu xem quảng cáo, tức là không được cập nhật do xem quảng cáo.
- Không phải là cách sử dụng chung chung của trò chơi (Ví dụ: mở trò chơi; sử dụng chế độ cài đặt).
- Không chứa Dữ liệu cá nhân và nhạy cảm của người dùng, theo định nghĩa trong Chính sách của Play, bao gồm cả mã nhận dạng người dùng, mật khẩu, dữ liệu vị trí chính xác hoặc dữ liệu sức khoẻ, hay bất kỳ nội dung nào mang tính xúc phạm, thô tục, khiêu dâm, bạo lực hoặc kích động thù địch.
- Dành cho tất cả người dùng (Ví dụ: không phải là hành động dành riêng cho nhóm hoặc chỉ dành cho người dùng ở một cấp độ nhất định hoặc chỉ dành cho hoạt động trực tiếp trong thời gian có hạn, v.v.)
Hình ảnh này cho thấy Số liệu thống kê trò chơi trong Hồ sơ người chơi trên thẻ Bạn. Giao diện người dùng (UI) này trong thẻ Bạn chỉ dành cho mục đích thử nghiệm. Giao diện người dùng của Số liệu thống kê trò chơi sẽ ra mắt vào tháng 9 năm 2026.
Loại tổng hợp
Loại tổng hợp cho Google Play biết cách tính số liệu thống kê từ các giá trị theo sự kiện mà bạn gửi:
- SUM: Dùng cho số liệu thống kê tích luỹ (chẳng hạn như tổng số xu thu thập được, tổng sát thương gây ra). Trò chơi phải gửi số tiền riêng biệt kiếm được trong mỗi phiên bản sự kiện.
- COUNT: Dùng cho số liệu thống kê thể hiện số lần xảy ra của một sự kiện (chẳng hạn như số trò chơi đã chơi, số trò chơi đã thắng). Trò chơi phải gửi các phiên bản xảy ra sự kiện riêng biệt.
- MAX: Chỉ sử dụng cho thành tích cao nhất trong một lần chơi (chẳng hạn như điểm số cao nhất trong một lần chơi, chuỗi kết hợp tối đa hoặc sát thương cao nhất trong một trận đấu). Đừng sử dụng hàm MAX làm giải pháp thay thế để hiển thị tổng giá trị vòng đời từ các giá trị đang chạy được tính toán trước.
Yêu cầu triển khai quan trọng đối với số liệu thống kê lặp lại
- Gửi giá trị theo sự kiện: Đối với mỗi sự kiện, chỉ gửi những gì đã xảy ra trong sự kiện đó, chẳng hạn như số xu thu thập được trong một lần chạy. Sau đó, hãy đặt một loại tổng hợp, chẳng hạn như SUM hoặc COUNT, trong cấu hình số liệu thống kê. Điều này đảm bảo rằng các số liệu thống kê lặp lại có thể sử dụng lại trên các cơ chế tương tác và cho phép Google Play tạo ra trải nghiệm phù hợp cho người chơi.
- Đừng gửi tổng số tiền trong suốt thời gian hoạt động: Ví dụ: đừng theo dõi tổng số xu mà người chơi đã thu thập được trên máy khách hoặc máy chủ trò chơi của bạn và gửi tổng số đó bằng phương thức tổng hợp MAX. Những số liệu thống kê như vậy sẽ tiếp tục xuất hiện trên giao diện người dùng của Hồ sơ người chơi, nhưng Google Play sẽ không thể sử dụng những số liệu đó để hỗ trợ các tính năng trao thưởng như giải đấu, nhiệm vụ và cuộc đua nước rút nhằm cải thiện trải nghiệm của người chơi và tăng mức độ tác động cho trò chơi của bạn.
Để biết hướng dẫn và ví dụ về cách lập mô hình sự kiện chính xác, hãy xem phần Sự kiện của người chơi và Định cấu hình số liệu thống kê.
Các bước tích hợp
Gửi dữ liệu bằng API Số liệu thống kê trò chơi dưới dạng sự kiện của người chơi cho số liệu thống kê lặp lại và một sự kiện được xác định trước progressUpdate cho số liệu thống kê về tiến trình. Bạn cũng cần định cấu hình logic để tính toán số liệu thống kê sẽ xuất hiện trên hồ sơ người chơi và thông tin hiển thị của họ.
Sự kiện của người chơi đại diện cho các khoảnh khắc riêng biệt trong trò chơi, hoàn thành vòng lặp trò chơi hoặc các mốc tiến trình.
Sự kiện của người chơi được xác định và mô hình hoá như sau:
- Sự kiện được thể hiện bằng một hành động cụ thể của người chơi, chẳng hạn như hoàn thành một trận đấu, hoàn thành một lượt chơi, mở khoá rương hoặc lưu tiến trình trong một khu vực.
- Mỗi hành động đều dẫn đến một số kết quả nhất định hoặc có một số đặc điểm nhất định xác định hành động đó. Các thuộc tính này được mô hình hoá dưới dạng thuộc tính sự kiện, cung cấp bối cảnh về sự kiện và kết quả cụ thể của sự kiện (ví dụ: loại trận đấu, số xu thu thập được trong lượt chơi đó, kết quả trận đấu hoặc số lần bắn trúng đầu).
Quá trình tích hợp bao gồm các bước sau:
- Khai báo giản đồ dữ liệu thô: Xác định các sự kiện của người chơi bằng cách tải tệp CSV lên Play Console. Xem phần Tạo sự kiện.
- Tích hợp với API số liệu thống kê trò chơi: Gửi dữ liệu thô của người chơi theo định dạng đã khai báo cho các sự kiện của người chơi và sự kiện
progressUpdate.- Gửi tất cả sự kiện đã xác định bằng cách sử dụng chế độ tích hợp phía máy khách hoặc phía máy chủ.
Để biết thêm thông tin, hãy xem các ví dụ về Sự kiện của trình phát và sự kiện
progressUpdate.
- Gửi tất cả sự kiện đã xác định bằng cách sử dụng chế độ tích hợp phía máy khách hoặc phía máy chủ.
Để biết thêm thông tin, hãy xem các ví dụ về Sự kiện của trình phát và sự kiện
- Tải tệp ZIP lên: Cung cấp 3 tệp CSV và tất cả tệp hình ảnh biểu tượng
xác định 5 chỉ số lặp lại và 1 cấp độ tiến trình của người chơi.
Để biết thêm thông tin, hãy xem Nguyên tắc đối với tệp ZIP.
Cung cấp các thông tin chi tiết sau:
- Tệp CSV cho số liệu thống kê lặp lại:
- Mã nhận dạng duy nhất của số liệu thống kê.
- Chỉ định nhãn sự kiện sẽ được dùng để tính toán số liệu thống kê. Bạn không thể sử dụng nhãn sự kiện
progressUpdatetại đây.- Chỉ định nhãn tài sản sẽ được dùng để tính toán số liệu thống kê. Đây phải là một thuộc tính của sự kiện được chỉ định.
- Chỉ định loại tổng hợp (SUM, MAX, MIN hoặc COUNT) để xác định cách tính số liệu thống kê trên nhãn thuộc tính đã chọn.
- Chỉ định một điều kiện lọc không bắt buộc để chỉ tính toán logic khi điều kiện được đáp ứng. Xác định thuộc tính và nhãn sự kiện, toán tử (=, <, <=, >= hoặc >) và giá trị ngưỡng.
- Thêm một cờ boolean để cho biết liệu chỉ số này có thể dùng cho các tính năng cạnh tranh hay không.
- Nếu tính năng này có thể dùng cho các tính năng cạnh tranh, thì giới hạn tối thiểu và tối đa hằng giờ cho một người chơi thực sự. Chúng tôi sẽ sử dụng thông tin này để xác định những người chơi có thể đang sử dụng sai mục đích khi tham gia các tính năng như giải đấu và thử thách cộng đồng.
- Cung cấp tên hiển thị riêng biệt cho số liệu thống kê mà người chơi nhìn thấy.
- Cung cấp văn bản riêng biệt mô tả số liệu thống kê. Nội dung mô tả này phải cung cấp thông tin chi tiết về cách người chơi đạt được số liệu thống kê đó và sẽ hiển thị cho người chơi trong giao diện người dùng Hồ sơ người chơi.
- Cung cấp một biểu tượng riêng biệt đại diện cho số liệu thống kê bằng cách nhập chính xác tên tệp biểu tượng vào tệp CSV.
- Cung cấp thông tin đầu vào không bắt buộc về việc giá trị tăng hay giảm là tốt cho người chơi. Thông tin này sẽ được dùng để ăn mừng các động tác của cầu thủ.
- Cung cấp đơn vị đo lường không bắt buộc cho số liệu thống kê, chẳng hạn như km, dặm và giây.
- Tệp CSV cho số liệu thống kê về tiến trình của người chơi:
- Cung cấp tên hiển thị riêng biệt cho tiến trình của người chơi mà người chơi nhìn thấy.
- Hãy cung cấp một biểu tượng riêng biệt đại diện cho số liệu thống kê.
- Cung cấp nội dung mô tả cho số liệu thống kê về tiến trình.
- Cung cấp dữ liệu đầu vào không bắt buộc cho biết giá trị tăng hay giá trị giảm là tốt cho người chơi. Thông tin đầu vào này sẽ chỉ được dùng để tôn vinh các chuyển động của người chơi khi thuộc tính
currentProgressthuộc loại INT. - Cung cấp đơn vị đo lường không bắt buộc cho số liệu thống kê, chẳng hạn như km, dặm, giây.
- Tệp CSV để bản địa hoá: Cung cấp tên hiển thị được bản địa hoá cho tất cả số liệu thống kê.
- Thêm một hàng cho mỗi bản địa hoá.
- Sử dụng chuỗi tên hiển thị của số liệu thống kê như đã thêm trong tệp CSV trước đó để xác định riêng số liệu thống kê mà bản dịch đang được thêm vào.
- Chỉ định ngôn ngữ trong danh sách mã ngôn ngữ.
- Thêm bản dịch cho tên hiển thị bằng ngôn ngữ được chỉ định.
- Thêm bản dịch cho nội dung mô tả số liệu thống kê bằng ngôn ngữ đã chỉ định.
- Tệp CSV cho số liệu thống kê lặp lại:
Lập kế hoạch cho giản đồ
Bạn có thể gửi hai loại dữ liệu bằng API Số liệu thống kê trò chơi: sự kiện của người chơi và sự kiện được xác định trước cho số liệu thống kê về tiến trình của người chơi.
Các ví dụ sau đây minh hoạ cách sự kiện của người chơi xuất hiện trên nhiều loại trò chơi:
Sự kiện của người chơi
Sự kiện của người chơi được xác định theo các khoảnh khắc riêng biệt trong trò chơi, việc hoàn thành vòng lặp trò chơi hoặc các mốc tiến trình.
- Xác định sự kiện là các khoảnh khắc cụ thể trong trò chơi, hoàn thành vòng lặp trò chơi hoặc
các mốc tiến trình:
- Số lần hoàn thành vòng lặp trò chơi, chẳng hạn như một trận đấu hoặc lượt chơi đã hoàn thành.
- Các mốc tiến trình, chẳng hạn như tiến trình khám phá khu vực đã lưu hoặc một cấp độ đã hoàn thành.
- Vì số liệu thống kê lặp lại phải thực sự thể hiện các hành động lặp lại của người chơi, nên các sự kiện được xác định phải liên kết với lối chơi cốt lõi.
- Thêm thuộc tính để cung cấp bối cảnh về sự kiện và kết quả của sự kiện, chẳng hạn như số cấp, loại trận đấu, loại vũ khí, số lượng vũ khí, số lần bắn trúng đầu, số xu thu thập được, kết quả trận đấu, thời gian hoàn thành vòng đua hoặc loại xe.
- Gửi sự kiện trong phiên chơi ngay khi sự kiện xảy ra. Ví dụ: gửi sự kiện hoàn thành vòng lặp trò chơi ngay sau khi vòng lặp hoàn tất.
Ví dụ
| Loại trò chơi | Nhãn sự kiện | Khoảnh khắc trong trò chơi / Hoàn thành sự kiện tiến trình / Hoàn thành vòng lặp trò chơi | Kết quả | Đặc điểm |
|---|---|---|---|---|
| Trò chơi giải đố độc lập có tiến trình tuyến tính | chapter_completed | Hoàn thành sự kiện tiến trình | Không áp dụng | Số chương, Tên chương, Số lần thử, số màn hình, số lượt di chuyển, nội dung chương |
| screen_completed | Hoàn thành sự kiện tiến trình | Số chương, Tên chương, Số lần thử, số lượt di chuyển, nội dung chương | ||
| Trò chơi chạy vô tận 3D | run_completed | Hoàn thành vòng lặp trò chơi | Số xu thu thập được, điểm số | Thời gian chạy, số xu thu thập được từ động cơ phản lực, số lần dùng bộ tăng tốc khi bắt đầu chạy, số lần dùng ván lướt sóng, số lần dùng nam châm, số lần dùng giày nhảy, số lần dùng động cơ phản lực |
| Game nhập vai hành động thế giới mở | areaExplorationProgress | Hoàn thành sự kiện tiến trình | Kẻ địch bị hạ, bình thuốc thu thập được | Số khu vực, Tên khu vực, Tiến trình theo tỷ lệ phần trăm |
| questCompleted | Hoàn thành vòng lặp trò chơi | Không áp dụng | Tên nhiệm vụ | |
| weaponUnlocked | Khoảnh khắc trong trò chơi | Không áp dụng | Tên vũ khí, Cấp vũ khí | |
| chestUnlocked | Khoảnh khắc trong trò chơi | Đã thu thập quặng cường hoá | ||
| Trò chơi giải đố phổ thông có yếu tố trang trí | puzzleCompleted | Hoàn thành vòng lặp trò chơi / Hoàn thành sự kiện tiến trình | Số xu đã thu thập, Số vật phẩm tăng tốc đã thu thập | Số lượt di chuyển, Đã dùng quà của Butler?, Loại cấp độ, Số cấp độ, số lần tăng cường màu sắc đã dùng, số lần dùng thuốc nổ |
| cardsCollected | Khoảnh khắc trong trò chơi | Thẻ 1 sao, thẻ 2 sao, thẻ 3 sao, tổng số thẻ | Số album, Tên album | |
| Đua xe arcade | raceCompleted | Hoàn thành vòng lặp trò chơi | Rank, NOS used, race_time | Loại cuộc đua, điểm xếp hạng, xe_đã_dùng |
| carUpgraded | Khoảnh khắc trong trò chơi | Đặc điểm xe được nâng cấp, cấp / giá trị cũ, cấp / giá trị mới | Loại xe, cấp độ hiện tại của gara | |
| Trò chơi bắn súng sinh tồn góc nhìn thứ ba | matchCompleted | Hoàn thành vòng lặp trò chơi | Số lần hạ gục, Số lần bắn trúng đầu, Giá trị danh dự | Kiểu trận đấu, thời gian sinh tồn |
| Mô phỏng quản lý thể thao điện tử | matchCompleted | Hoàn thành vòng lặp trò chơi | Kết quả, bàn thắng, bàn thắng | Tên đội đối thủ, tên đội đang thi đấu |
| trainingCompleted | Khoảnh khắc trong trò chơi | Drills done, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
progressUpdate sự kiện
Nếu trò chơi của bạn có cơ chế tiến trình chính, hãy sử dụng sự kiện này để gửi tiến trình hiện tại của người chơi. Sự kiện này có một thuộc tính được xác định trước có tên là "currentProgress" thuộc loại INT hoặc STRING. Bạn nên gửi giá trị hiện tại của tiến trình của người chơi trong cơ chế tiến trình chính bằng thuộc tính này. Nếu bạn sử dụng sự kiện này, thì thuộc tính "currentProgress" được xác định trước phải xuất hiện và bạn phải xác định số liệu thống kê về tiến trình bằng thuộc tính này.
Bạn có thể gửi giá trị hiện tại cho các hệ thống tiến trình khác trong trò chơi của mình như lifetime highest score hoặc current coin balance dưới dạng các thuộc tính khác của sự kiện này.
Vì người chơi có thể so sánh hồ sơ của họ theo tiến trình hiện tại trong trò chơi, nên bạn cần đảm bảo không có độ trễ khi nhận giá trị tiến trình hiện tại sau lần tích hợp đầu tiên. Để thể hiện chính xác tiến trình hiện tại cho người chơi, bạn nên gửi sự kiện progressUpdate khi bắt đầu mỗi phiên trò chơi cũng như bất cứ khi nào có thông tin cập nhật về tiến trình hiện tại.
Ví dụ
| Loại trò chơi | thuộc tính currentProgress của sự kiện `progressUpdate` |
|---|---|
| Trò chơi giải đố theo tiến trình tuyến tính | Số chương hoặc số cấp hiện tại |
| 3d Endless Runner | Điểm cao, Số dư vật phẩm tăng sức mạnh hiện tại |
| Giải đố phổ thông | Số cấp hiện tại, số lần thắng ngay lần thử đầu tiên, số khu vực đã hoàn thành, số bộ sưu tập đã hoàn thành |
| Đua xe arcade | Cấp hiện tại, Số dư tiền tệ |
| Game nhập vai hành động thế giới mở | Cấp bậc hiện tại của nhân vật, Số cấp hiện tại |
| Bắn súng góc nhìn thứ ba | Số cấp hiện tại |
| Mô phỏng thể thao điện tử | Cấp người quản lý, Cấp câu lạc bộ |
Định cấu hình số liệu thống kê
Bạn cần định cấu hình số liệu thống kê lặp lại và số liệu thống kê tiến trình bằng cách xác định logic tính toán và hiển thị thông tin về từng số liệu thống kê. Dưới đây là ví dụ về số liệu thống kê lặp lại của các thể loại trò chơi khác nhau. Số liệu thống kê lặp lại thường là số liệu thống kê cập nhật liên tục cho bất kỳ người chơi nào trong một vài (3-4) phiên chơi và liên kết với vòng lặp trò chơi cốt lõi.
Để tìm hiểu thời điểm sử dụng SUM, COUNT hoặc MAX, hãy xem bài viết Chọn đúng loại tổng hợp.
| Tên trò chơi | Tên hiển thị của số liệu thống kê trò chơi | Thuộc tính sự kiện | Logic tính toán [aggregation] | Bộ lọc |
|---|---|---|---|---|
| 3D Endless Runner | Số lần chạy đã hoàn tất | Bất kỳ thuộc tính nào của sự kiện run_completed | Số lượng | Tất cả giá trị [Không dùng] |
| Số xu đã thu thập | Thuộc tính Coins_collected của sự kiện run_completed | Tổng | Không áp dụng | |
| Số chìa khoá đã thu thập | Thuộc tính Keys_collected của sự kiện run_completed | Tổng | Không áp dụng | |
| Điểm số cao nhất trong một lượt chạy | Thuộc tính score của sự kiện run_completed | Tối đa | Không áp dụng | |
| Số lượt chạy hoàn thành có nhiều xu | Thuộc tính Coins_collected của sự kiện run_completed | Số lượng | Giá trị > 5000 | |
| Trò chơi giải đố theo tiến trình tuyến tính | Số chương đã hoàn thành | Bất kỳ thuộc tính nào của sự kiện chapter_completed | Số lượng | Tất cả giá trị [Không dùng] |
| Số màn hình đã hoàn tất | Bất kỳ thuộc tính nào của sự kiện screen_completed | Số lượng | Tất cả giá trị [Không dùng] | |
| Số chương hoàn thành trong lần thử đầu tiên | Thuộc tính num_try của sự kiện chapter_completed | Số lượng | Num_try = 1 | |
| Số màn hình hoàn thành trong lần thử đầu tiên | Thuộc tính num_try của sự kiện screen_completed | Số lượng | Num_try = 1 | |
| Game nhập vai hành động thế giới mở | Nhiệm vụ đã hoàn thành | Bất kỳ thuộc tính nào của sự kiện quest_completed | Số lượng | Tất cả giá trị [Không dùng] |
| Khu vực đã khám phá | Thuộc tính perc_progress của sự kiện area_exploration_progress | Số lượng | Giá trị = 100 | |
| Đã mở khoá kiếm | Thuộc tính Weapon_type của sự kiện weapon_unlocked | Số lượng | Giá trị = "kiếm" | |
| Kẻ địch đã bị hạ gục | Thuộc tính Enemies_defeated của sự kiện area_exploration_progress | Tổng | Không áp dụng | |
| Bình máu đã thu thập | Thuộc tính Enhancement_ores của sự kiện chest_unlocked | Tổng | Không áp dụng | |
| Giải đố phổ thông | Số màn đã vượt qua | Bất kỳ thuộc tính nào của sự kiện level_completed | Số lượng | Tất cả giá trị [Không dùng] |
| Số màn vượt qua ngay lần thử đầu tiên | Thuộc tính num_try của sự kiện level_completed | Số lượng | Giá trị = 1 | |
| Số lần dùng vật phẩm tăng cường màu | Thuộc tính Color_booster_used của sự kiện level_completed | Tổng | Không áp dụng | |
| Số lần dùng vật phẩm tăng cường bom | Thuộc tính Bomb_booster_used của sự kiện level_completed | Tổng | Không áp dụng | |
| Thẻ đã thu thập | Thuộc tính total_cards của sự kiện cards_collected | Tổng | Không áp dụng | |
| Đua xe arcade | CĐ thắng | Thuộc tính rank của sự kiện race_completed | Số lượng | Giá trị = 1 |
| Cuộc đua nhanh nhất | thuộc tính race_time của sự kiện race_completed | Phút | Không áp dụng | |
| NOS đã dùng | Thuộc tính NOS_used của sự kiện race_completed | Tổng | Không áp dụng | |
| Số cuộc đua đã hoàn thành bằng xe Mustang | Thuộc tính car_type của sự kiện race_completed | Số lượng | Giá trị = "Mustang" | |
| Nâng cấp xe | Bất kỳ thuộc tính nào của sự kiện car_upgraded | Số lượng | Tất cả giá trị [Không dùng] | |
| Trò chơi bắn súng sinh tồn góc nhìn thứ ba | Số trận thắng | Bất kỳ thuộc tính nào của sự kiện match_completed | Số lượng | Match_result = TRUE |
| Tổng số trận đấu loại | Thuộc tính Eliminations của sự kiện match_completed | Tổng | Không áp dụng | |
| Thời gian sống sót lâu nhất | Thuộc tính survival_time của sự kiện match_completed | Tối đa | Không áp dụng | |
| Tổng số cú bắn trúng đầu | Thuộc tính Headshots của sự kiện match_completed | Tổng | Không áp dụng | |
| Tổng giá trị kỹ năng | Thuộc tính Skill_value của sự kiện match_completed | Tổng | Không áp dụng | |
| Mô phỏng quản lý thể thao điện tử | Số trận thắng | Thuộc tính kết quả của sự kiện match_completed | Số lượng | Result = "Won" |
| Tổng số bàn thắng | Thuộc tính goals_scored của sự kiện match_completed | Tổng | Không áp dụng | |
| Số trận thắng ở cấp độ khó | Thuộc tính kết quả của sự kiện hard_match_completed | Số lượng | Result = "Won" | |
| Đội có hiệu số bàn thắng bại cao nhất sẽ thắng | Thuộc tính Goal_difference của sự kiện match_completed | Tối đa | Result = "Won" | |
| Tổng số bài tập huấn luyện | Thuộc tính Drills_done của sự kiện training_completed | Tổng | Không áp dụng | |
| Tổng số khoá đào tạo đã hoàn thành | Bất kỳ thuộc tính nào của sự kiện training_completed | Số lượng | Không áp dụng |
Thông tin chi tiết về nội dung tích hợp
Phần này trình bày cách tạo sự kiện và gửi sự kiện trong cả quá trình tích hợp phía máy khách và phía máy chủ.
Trường hợp nên gửi dữ liệu
Sự kiện của người chơi thể hiện các hành động trong trò chơi liên quan đến việc hoàn thành vòng lặp trò chơi hoặc các khoảnh khắc cụ thể trong trò chơi. Gửi những sự kiện này ngay khi chúng xảy ra. Ví dụ: gửi sự kiện hoàn thành vòng lặp trò chơi ngay khi vòng lặp hoàn tất.
progressUpdate Sự kiện biểu thị cấp độ tiến trình hiện tại của người chơi.
Dữ liệu cho chỉ số tiến trình phải được gửi bằng sự kiện này trong các trường hợp sau:
- Bất cứ khi nào có thông tin cập nhật về tiến trình hiện tại, hãy gửi ngay giá trị mới nhất
- Bất cứ khi nào người chơi khởi chạy trò chơi để đảm bảo luôn có số liệu thống kê này cho người chơi.
Các cách tích hợp
Có hai cách tích hợp: phía máy khách và từ máy chủ đến máy chủ.
Tích hợp máy chủ đến máy chủ
Điểm cuối API công khai cho phép bạn gửi sự kiện trong tải trọng yêu cầu bằng cách sử dụng các cấu hình sau:
Yêu cầu HTTP
POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats:
batchRecordEvents
Tham số đường dẫn
| Tham số | Loại dữ liệu | Mô tả |
|---|---|---|
| playerId | Chuỗi | Mã PGS của người chơi. |
Uỷ quyền và xác thực
Các lệnh gọi API từ máy chủ đến máy chủ tuân theo nguyên tắc chuẩn về Quyền truy cập phía máy chủ vào Dịch vụ trò chơi của Play bằng OAuth 2.0. Yêu cầu phải bao gồm một mã thông báo truy cập được uỷ quyền trong phạm vi https://www.googleapis.com/auth/games.
Sự kiện: Nội dung yêu cầu
API phụ trợ có các giới hạn xác thực cấu trúc nghiêm ngặt:
- Kích thước lô: Tối đa 30 sự kiện cho mỗi
BatchRecordEventsRequest. - Số lượng thuộc tính: Tối đa 25 thuộc tính tuỳ chỉnh cho mỗi
PlayerGameEvent. - Giới hạn về độ dài: Tên sự kiện (tối đa 100 ký tự), khoá thuộc tính (tối đa 100 ký tự) và giá trị chuỗi thuộc tính (tối đa 1024 ký tự).
- Mã sự kiện: Phải là một chuỗi UUID hợp lệ gồm 36 ký tự.
- Thử lại và lưu vào bộ nhớ đệm: Tránh lưu vào bộ nhớ đệm hoặc tích luỹ quá nhiều sự kiện trên thiết bị nếu API không hoạt động, vì các lần thử lại theo lô vượt quá 30 sự kiện sẽ bị từ chối. Luôn chia nhỏ các lần thử lại để tuân thủ giới hạn kích thước lô.
BatchRecordEventsRequest
Hãy xem BatchRecordEventsRequest.
{ "packageName": string, "requestTime": string, "events": [ { object (PlayerGameEvent) } ] }
PlayerGameEvent
{ "eventId": string, "eventName": string, "eventProperties": { // keys (e.g., "matchId", "score") "" : { object (PropertyValue) } }, "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z"). }
PropertyValue
// ONE of the following fields will be present: { // 64-bit integer formatted as a string to prevent data loss "intValue": "string", // Double-precision floating point number. "doubleValue": number, // Standard UTF-8 text string. "stringValue": "string", // Boolean value (true or false). "boolValue": boolean, // Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s"). "durationValue": "string" }
Sự kiện progressUpdate: Nội dung yêu cầu
BatchRecordEventsRequest
{ "packageName": string, "requestTime": string, "events": [ { object (PlayerGameEvent) } ] }
PlayerGameEvent – progressUpdate
{ "eventId": string, "eventName": "progressUpdate", "eventProperties": { "" : { object (PropertyValue) // Must have at least one property "currentProgress" of type INT or STRING } }, "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z") }
Nội dung phản hồi
Nếu thành công, phương thức này sẽ trả về trạng thái HTTP 200 OK kèm theo một đối tượng JSON trống.
Nội dung yêu cầu mẫu
Sự kiện: PlayerGameEvent
{ "packageName": "com.example.awesomegame",//Your package name "requestTime": "2026-05-09T00:44:44Z", "events": [ { "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency "eventName": "matchCompleted", "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z"). "eventProperties": { "matchId": { "stringValue": "Match_A" }, "gameMode": { "stringValue": "Battle_B" }, "locationId": { "stringValue": "Location_XYZ" }, "playerElimination": { "intValue": 2 }, "isWinner": { "boolValue": true } } } ] }
Sự kiện progressUpdate
{ "packageName": "com.example.awesomegame",//Your package name "requestTime": "2026-05-09T00:44:44Z", "events": [ { "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID "eventName": "progressUpdate", "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z"). "eventProperties": { "currentProgress": { "intValue": 52 }, //Add more properties as per your requirement } } ] }
Triển khai dịch vụ
Để tìm hiểu về cách triển khai ứng dụng Số liệu thống kê trò chơi cho nền tảng của bạn, vui lòng xem các tài nguyên sau:
Mốc quan trọng
| Ngày | Tích hợp API số liệu thống kê trò chơi | Cấu hình số liệu thống kê trò chơi |
| Tháng 9 năm 2026 | Không áp dụng | Người chơi bắt đầu thấy số liệu thống kê trò chơi trên hồ sơ người chơi của họ. |