Trang này được dịch bởi Cloud Translation API.

Tích hợp thành tích

Tài liệu này giải thích cách tích hợp thành tích vào trò chơi bằng Google Play Console hoặc các lệnh gọi API. Tài liệu này đề cập đến các phần tử và trạng thái thiết yếu của thành tích, đồng thời mô tả cách tạo, nhập và quản lý các thành tích đó.

Trước khi bắt đầu

Xem nguyên tắc thiết kế thành tích chất lượng cao.
Xem các thuật ngữ trong phần kiến thức cơ bản về thành tích.

Tạo hoặc nhập thành tích mới

Để triển khai thành tích từ đầu, hãy làm theo các bước sau:

Thêm thành tích

Bạn có thể tạo thành tích lần đầu tiên bằng Google Play Console theo hai cách:

Tạo thành tích: Thêm định nghĩa và siêu dữ liệu cho từng thành tích.
Nhập thành tích: Nhập định nghĩa và siêu dữ liệu khác cho nhiều thành tích cùng một lúc.

Tạo thành tích

Để tạo thành tích cho trò chơi mới và chưa được phát hành, hãy hoàn tất các bước sau:

Trong Google Play Console, hãy chọn một trò chơi.
Trên trang Dịch vụ trò chơi của Play – Thành tích (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích), hãy chọn Tạo thành tích.
Trên trang Thêm thành tích, hãy hoàn thiện biểu mẫu.
Nhấp vào Lưu dưới dạng bản nháp.
Sau khi tạo thành tích, bạn cần phát hành thành tích.

Nhập thành tích

Để thêm nhiều thành tích vào trò chơi cùng một lúc, hãy làm theo các bước sau:

Tạo một tệp zip chứa các thành tích của bạn.
Tải tệp lên.

Để biết thêm thông tin về tệp zip, hãy xem Nguyên tắc đối với tệp zip.

Cách nhập thành tích:

Trong Google Play Console, hãy chọn một trò chơi.
Trên trang Dịch vụ trò chơi của Play – Thành tích (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích), hãy chọn Nhập thành tích.
Trên trang Nhập thành tích, hãy nhấp vào Tải lên.
Chọn tệp zip để tải lên.
Nhấp vào Lưu dưới dạng bản nháp.
Sau khi nhập thành tích, bạn cần phát hành trò chơi.

Nguyên tắc đối với tệp zip

Bạn có thể nhập nhiều thành tích cùng lúc bằng tệp zip. Hãy tham khảo bảng để biết tên tệp chính xác cần sử dụng trong tệp zip:

Tên tệp	Bắt buộc hoặc tuỳ chọn	Các giá trị được chấp nhận
Tên tệp	Bắt buộc hoặc tuỳ chọn	Các giá trị được chấp nhận	`AchievementsMetadata.csv`	Bắt buộc	Siêu dữ liệu cho từng thành tích. Xem phần Thuộc tính.
`AchievementsLocalizations.csv`	Không bắt buộc	Cung cấp bản dịch cho tên và nội dung mô tả thành tích.
`AchievementsIconMappings.csv`	Không bắt buộc	Liên kết thành tích với tệp biểu tượng của thành tích đó.
Tệp biểu tượng	Không bắt buộc	Biểu tượng ở định dạng PNG, JPEG hoặc JPG.

Yêu cầu đối với tệp zip:

Không có thư mục con.
Tên tệp khác biệt.
Chỉ tệp CSV, PNG, JPEG hoặc JPG.
Tệp CSV không được có hàng tiêu đề.
Mỗi tệp phải có kích thước dưới 1 MB.
Tệp zip không được chứa quá 203 tệp.
Tổng kích thước tệp ZIP phải dưới 200 MB.

Định dạng AchievementsMetadata.csv

Tệp AchievementsMetadata.csv chứa siêu dữ liệu cho từng thành tích. Tệp này phải bao gồm thông tin dưới dạng giá trị được phân tách bằng dấu phẩy theo thứ tự sau:

    Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order

Các trường này được mô tả trong bảng sau:

Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Các giá trị được chấp nhận
Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Các giá trị được chấp nhận	Tên	Bắt buộc	Tối đa 100 ký tự
Mô tả	Không bắt buộc	Tối đa 500 ký tự
Giá trị gia tăng	Không bắt buộc	`True` hoặc `False`
Số bước cần thiết	Bắt buộc nếu `Incremental Value` là `True.`	Số (không có phân số hoặc số thập phân)
Trạng thái ban đầu	Bắt buộc	`Hidden` hoặc `Revealed`
Điểm	Bắt buộc	Số chia hết cho 5 và giá trị phải nằm trong khoảng từ 5 đến 200
Thứ tự trong danh sách	Không bắt buộc	Số (không có phân số hoặc số thập phân và lớn hơn 0)

Yêu cầu đối với tệp AchievementsMetadata.csv:

Mỗi hàng phải có 7 giá trị. Nếu bạn muốn bỏ qua một giá trị, hãy để trống giá trị đó.
Các trường Name và Description được dùng làm ngôn ngữ mặc định.
Trường Name phải khác biệt giữa các thành tích.
Các trường sau đây không được chứa dấu phẩy: Name và Description.

Tệp AchievementsMetadata.csv mẫu:

  Achievement1,Achievement One,True,100,Hidden,5,20
  Achievement2,Achievement Two,False,,Revealed,10,30

Định dạng AchievementsLocalizations.csv

Tệp AchievementsLocalizations.csv là một tệp không bắt buộc, thiết lập tất cả dữ liệu cần thiết để mô tả từng thành tích cho người dùng ở nhiều ngôn ngữ. Bảng thành tích được dịch cho phù hợp với ngôn ngữ đã chỉ định cho trò chơi.

Tệp này phải bao gồm thông tin dưới dạng giá trị được phân tách bằng dấu phẩy theo thứ tự sau:

   Name, Localized name, Localized description, locale

Các trường này được mô tả trong bảng sau:

Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Mô tả	Các giá trị được chấp nhận
Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Mô tả	Các giá trị được chấp nhận	Tên	Bắt buộc	Phải khớp với cột `Name` trong `AchievementsMetadata.csv`.	Tối đa 100 ký tự
Tên được bản địa hoá	Bắt buộc	Tên đã bản địa hoá của thành tích.	Tối đa 100 ký tự
Nội dung mô tả được bản địa hoá	Không bắt buộc	Nội dung mô tả được bản địa hoá cho thành tích theo ngôn ngữ đã chỉ định.	Tối đa 500 ký tự
Ngôn ngữ	Bắt buộc	Mã ngôn ngữ (chẳng hạn như `en-US`).	Thêm bản dịch cho trò chơi trước khi chỉ định ngôn ngữ. Xin lưu ý rằng bạn không thể chỉ định ngôn ngữ mặc định. Bạn có thể tìm thấy mã ngôn ngữ được hỗ trợ trong danh sách ngôn ngữ được hỗ trợ.

Yêu cầu đối với tệp AchievementsLocalizations.csv:

Tên thành tích trong một trò chơi phải khác biệt theo từng ngôn ngữ.
Ví dụ: nếu một trò chơi hỗ trợ cả ngôn ngữ en-US và fr-FR, thì thành tích có tên "Achievement1" cho en-US cũng có thể được đặt tên là "Achievement1" cho fr-FR.
Mỗi hàng phải có 4 giá trị. Nếu bạn muốn bỏ qua giá trị Nội dung mô tả được bản địa hoá, hãy để trống giá trị này.

Tệp AchievementsLocalizations.csv mẫu:

Achievement1,Achievement One,This is the description of achievement one in English.,en-US
Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR
Achievement2,Achievement Two,Description of achievement two.,en-US
Achievement2,Logro Dos,Descripción del logro dos.,es-ES
Achievement3,Achievement Three,,en-US
Achievement3,Erfolg Drei,,de-DE

Định dạng AchievementsIconMappings.csv

Tệp AchievementsIconMappings.csv là tệp không bắt buộc dùng để liên kết thành tích của bạn với biểu tượng đã cho. Tệp này phải bao gồm thông tin dưới dạng giá trị được phân tách bằng dấu phẩy theo thứ tự sau:

Name, icon filename

Các trường này được mô tả trong bảng sau

Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Mô tả
Tiêu đề cột CSV	Bắt buộc hoặc tuỳ chọn	Mô tả	Tên	Bắt buộc	Phải khớp với cột `Name` trong `AchievementsMetadata.csv`.
Tên tệp biểu tượng	Bắt buộc	Tên tệp biểu tượng của bạn.

Yêu cầu đối với tệp AchievementsIconMappings.csv:

Mỗi hàng phải có hai giá trị.
Tệp biểu tượng chỉ có thể ở định dạng PNG hoặc JPEG.

Tệp AchievementsIconMappings.csv mẫu:

Valid Achievement,valid-achievement-icon.png
Incremental Achievement,incremental-achievement-icon.jpeg
No Description,no-description-icon.png
Hidden Initial State,hidden-initial-state-icon.png
Large Point Value,large-point-value-icon.jpeg

Hướng dẫn về biểu tượng

Biểu tượng phải được tạo dưới dạng tệp PNG, JPEG hoặc JPG có tỷ lệ 512 x 512. Bạn chỉ cần cung cấp cho chúng tôi biểu tượng của thành tích đã mở khoá. Chúng tôi sẽ tự động tạo một phiên bản thang màu xám cho biểu tượng đã được công khai. Do đó, bạn nên sử dụng biểu tượng thành tích có nhiều màu sắc để người dùng có thể dễ dàng phân biệt giữa các thành tích đã mở khoá và được công khai.

Khi một biểu tượng thành tích xuất hiện trong [thông báo nhanh][a] trên Android, biểu tượng đó sẽ có lớp phủ vòng tròn và các góc bên ngoài bị ẩn. Hãy đảm bảo biểu tượng của bạn vẫn đẹp mắt trong những trường hợp như thế.

Tất cả các ngôn ngữ đều sử dụng cùng một biểu tượng, do đó bạn nên tránh thêm bất kỳ nội dung hoặc văn bản nào đã được bản địa hóa vào một biểu tượng.

Tệp biểu tượng

Các biểu tượng mà bạn tham chiếu trong tệp AchievementsIconMappings.csv phải tồn tại trong tệp lưu trữ zip hiện tại mà bạn nhập.

Cập nhật trò chơi có thành tích hiện tại

Bạn có thể thêm nhiều thành tích vào một trò chơi và cập nhật các thành tích hiện có trong Google Play Console.

Thêm thành tích khác

Nếu bạn đã có các thành tích hiện tại và muốn thêm thành tích khác:

Trong Google Play Console, hãy chọn một trò chơi.
Trên trang Dịch vụ trò chơi của Play – Thành tích (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích), hãy chọn Thêm thành tích.

Chỉnh sửa thành tích

Nếu bạn đã có các thành tích hiện tại và muốn chỉnh sửa:

Trong Google Play Console, hãy chọn một trò chơi.
Trên trang Dịch vụ trò chơi của Play – Thành tích (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích), hãy chọn một thành tích.
Bạn có thể chỉnh sửa bất kỳ trường nào.
Nhấp vào Lưu dưới dạng bản nháp.
Trên trang Dịch vụ trò chơi của Play – Thành tích, thành tích đã chỉnh sửa sẽ ở trạng thái "Có sẵn cho người kiểm thử".
Sau khi bạn kiểm thử thành tích, hãy nhấp vào Xem lại và xuất bản.
Thao tác này sẽ phát hành lại trò chơi của bạn (cùng với tất cả thành tích đã được cập nhật).

Xóa thành tích

Một khi đã phát hành, bạn không thể xóa các bảng thành tích đó. Bạn chỉ có thể xoá thành tích ở trạng thái trước khi phát hành

Trên trang Dịch vụ trò chơi của Play – Thành tích, hãy chọn một thành tích.
Để xoá thành tích, hãy nhấp vào xoá thành tích.

Đặt lại thành tích

Bạn chỉ có thể đặt lại dữ liệu tiến trình của người chơi cho các bảng thành tích nháp mà thôi.

Trên trang Dịch vụ trò chơi của Play – Thành tích, hãy chọn một thành tích.
Để đặt lại thành tích, hãy nhấp vào Đặt lại tiến trình.
Để đặt lại dữ liệu thành tích theo phương thức lập trình, hãy gọi phương thức Achievements của API Quản lý.

Thêm bản dịch cho các thành tích

Bạn có thể chỉ định bản dịch riêng cho các bảng thành tích liên kết với trò chơi của mình. Trước khi làm như vậy, đầu tiên bạn phải nhớ hoàn thành các bước như mô tả trong nội dung bài viết Thêm bản dịch cho trò chơi của bạn.

Bạn có thể thêm bản dịch cho trò chơi theo hai cách:

Bạn có thể sử dụng lựa chọn nhập thành tích để tải bản dịch cho nhiều thành tích mới lên cùng một lúc. Bạn không thể sử dụng lựa chọn này để tải bản dịch lên cho thành tích hiện có.
Bạn có thể thêm bản dịch cho từng thành tích trong trò chơi. Cách thêm bản dịch riêng cho từng thành tích:
1. Trong Google Play Console, hãy mở thẻ Thành tích cho trò chơi của bạn, sau đó chọn một thành tích hiện có.
2. Trên trang chi tiết của bảng thành tích, hãy chọn thẻ cho ngôn ngữ mà bạn đã thêm trước đó ở thẻ Thông tin trò chơi.
3. Trên trang thông tin chi tiết về thành tích của ngôn ngữ đó, hãy chỉnh sửa biểu mẫu bằng bản dịch của bạn cho thành tích đó.
4. Nhấp vào Lưu để lưu trữ thông tin chi tiết về bản dịch của thành tích.

Triển khai ứng dụng

Để tìm hiểu cách triển khai bảng thành tích cho nền tảng của bạn, vui lòng xem các tài nguyên sau:

Kiểm thử thành tích

Để xác minh rằng các thành tích hoạt động như dự kiến, hãy làm theo các bước sau để kiểm thử:

Thiết lập kênh kiểm thử nội bộ.
Thêm tài khoản thử nghiệm vào dự án trò chơi cho người kiểm thử.
Tạo hồ sơ Dịch vụ trò chơi của Play cho một trong các tài khoản kiểm thử bằng Ứng dụng Play Games.
Mở trò chơi bằng chính tài khoản kiểm thử mà bạn đã dùng để tạo hồ sơ Dịch vụ trò chơi của Play.
Xác minh rằng "Thông báo chào mừng" của Dịch vụ trò chơi của Play xuất hiện trên màn hình để xác nhận việc xác thực tự động thành công khi khởi chạy trò chơi.
Chơi trò chơi và hoàn tất các bước cần thiết để mở khoá thành tích.
Cách xác minh thành tích:
- Xác minh rằng cửa sổ bật lên "đã mở khoá thành tích" xuất hiện trên màn hình khi người chơi hoàn thành thành tích.
- Mở ứng dụng Cửa hàng Play và xác minh rằng phần thành tích trên Thẻ Bạn cho thấy cả thành tích đã hoàn thành và thành tích đang thực hiện (kèm theo thông tin chi tiết về tiến trình).

Theo dõi hiệu suất của thành tích trong Play Console

Dưới đây là cách tìm số liệu thống kê nhanh về thành tích cá nhân:

Trong Google Play Console.
Chuyển đến phần Cài đặt> Dự án trò chơi.
Chọn một trò chơi.
Trên trình đơn bên trái, hãy nhấp vào Thành tích.
Trên trang Thành tích, bạn có thể tìm thấy số liệu thống kê để biết liệu người chơi có đang mở khoá thành tích hay không. Đối với những người chơi không ẩn thành tích, bạn có thể xem tỷ lệ phần trăm người chơi đạt được thành tích. Đối với các thành tích ở giai đoạn đầu, tỷ lệ mở khoá thường gần với 100%.

Bạn cũng có thể theo dõi hiệu suất theo chuỗi thời gian của thành tích trên trang Phát triển > Dịch vụ trò chơi của Play > Số liệu thống kê về trò chơi.

Xuất bản thành tích

Sau khi hoàn tất kiểm thử, bạn phải phát hành trò chơi. Tất cả thành tích của trò chơi sẽ được phát hành cùng với trò chơi đó. Xuất bản thành tích là bước bắt buộc để thành tích hoạt động đúng cách.

Để xuất bản, hãy làm theo các bước sau:

Trong Google Play Console, hãy chọn một trò chơi.
Trên trang Dịch vụ trò chơi của Play – Thành tích (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích), hãy nhấp vào Xem xét và xuất bản.
Trên trang Dịch vụ trò chơi của Play – Phát hành (Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Phát hành), hãy xem xét các hành động và khắc phục vấn đề.
Nhấp vào Xuất bản.
Tất cả thành tích của trò chơi sẽ được phát hành.

Sai lầm phổ biến cần tránh

Những điểm này nêu bật những lỗi thường gặp cần tránh khi triển khai thành tích trong một trò chơi. Các nguyên tắc này nhấn mạnh tầm quan trọng của:

Trong Play Console, hãy chuyển đến mục Phát triển > Dịch vụ trò chơi của Play > Thiết lập và quản lý > Thành tích.
- Trước khi xuất bản, hãy xác minh rằng những thành tích được định cấu hình trong Play Console không ở trạng thái "Bản nháp".
- Đừng thêm các giá trị mã nhận dạng thành tích từ Play Console vào mã trò chơi. Thay vào đó, hãy sử dụng các quy trình triển khai ứng dụng.
Đảm bảo rằng bạn cũng đã triển khai logic mở khoá trên ứng dụng.
- Người chơi không thể bỏ qua bước kích hoạt nơi gọi API mở khoá. Ví dụ: hoàn thành hướng dẫn là một thành tích, nhưng người chơi có thể bỏ qua chính hướng dẫn đó.