Dịch vụ trò chơi của Play dành cho C++

Sau khi ngừng cung cấp API Đăng nhập bằng Google, chúng tôi sẽ xoá SDK games phiên bản 1 vào năm 2026. Sau tháng 2 năm 2025, bạn sẽ không thể xuất bản các trò chơi vừa tích hợp với SDK của games phiên bản 1 trên Google Play. Bạn nên sử dụng SDK của phiên bản 2.
Mặc dù các ứng dụng/trò chơi hiện có có tích hợp trò chơi phiên bản 1 trước đó vẫn tiếp tục hoạt động trong vài năm nữa, nhưng bạn nên di chuyển sang phiên bản 2 kể từ tháng 6 năm 2025.
Hướng dẫn này dành cho việc sử dụng SDK Dịch vụ trò chơi của Play phiên bản 1. SDK C++ cho Dịch vụ trò chơi của Play phiên bản 2 hiện chưa có.

SDK C++ trong Dịch vụ trò chơi của Google Play cung cấp một API C++ để sử dụng với các dịch vụ của Google Play Games, đồng thời dành cho những nhà phát triển đã triển khai C++ cho trò chơi của họ.

Hiện tại, SDK triển khai các dịch vụ sau:

  • Uỷ quyền
  • Thành tích
  • Bảng xếp hạng
  • Sự kiện
  • Trò chơi đã lưu
  • Kết nối lân cận (chỉ dành cho Android)
  • Số liệu thống kê về người chơi

Khái niệm

Nhìn chung, bạn sử dụng SDK bằng cách làm theo các bước sau:

  1. Thiết lập cấu hình nền tảng cho Android.
  2. Sử dụng GameServices::Builder để định cấu hình và tạo một đối tượng GameServices. Đối tượng GameServices sẽ tự động tìm cách đăng nhập và trả về kết quả thông qua lệnh gọi lại OnAuthActionFinished(). Ghi lại kết quả do lệnh gọi lại trả về. Nếu không đăng nhập tự động được, bạn có thể hiển thị một nút để người dùng đăng nhập.

  3. Sau khi nhận được kết quả OnAuthActionFinished(), bạn có thể sử dụng đối tượng GameServices và Trình quản lý con của đối tượng này để thực hiện các lệnh gọi đến Dịch vụ trò chơi của Play, bao gồm:

    • Đăng nhập (sau khi uỷ quyền không thành công): StartAuthorizationUI()
    • Mở khoá thành tích: Achievements().Unlock()
    • Hiển thị thành tích bằng giao diện người dùng tích hợp sẵn: Achievements().ShowAllUI()
    • Gửi điểm cao: Leaderboards().SubmitScore()
    • Đăng xuất: SignOut()

  4. Khi bạn dùng xong đối tượng GameServices, hãy đặt lại hoặc huỷ đối tượng đó.

Ở cấp độ chi tiết hơn:

  1. Khởi chạy cấu hình nền tảng: Đây là một đối tượng chứa thông tin khởi chạy dành riêng cho nền tảng. Trên Android, cấu hình nền tảng chứa Java VM và một con trỏ đến Activity hiện tại:

    // In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);

  2. Tạo một đối tượng GameServices: Đối tượng này là điểm truy cập chính cho chức năng của Dịch vụ trò chơi của Google Play. Các thực thể GameServices được tạo bằng GameServices::Builder.

    Trong hầu hết các hoạt động triển khai, một đối tượng GameServices nhất định sẽ duy trì miễn là môi trường C của bạn còn tồn tại; bạn không cần khởi động lại đối tượng đó khi Activity Android của bạn tạm dừng và tiếp tục.

    // Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
        .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
        .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
            is_auth_in_progress_ = true;
            started_callback(op);
        })
        .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                     gpg::AuthStatus status) {
            LOGI("Sign in finished with a result of %d", status);
            is_auth_in_progress_ = false;
            finished_callback(op, status);
        })
        .Create(pc);

  3. Sử dụng các lớp Trình quản lý để quản lý đối tượng GameServices. Các trình quản lý được truy cập từ một thực thể GameServices và nhóm các chức năng liên quan với nhau. Ví dụ về các đối tượng này bao gồm Trình quản lý thành tích và Trình quản lý bảng xếp hạng. Bản thân các đối tượng này không chứa trạng thái mà người dùng có thể thấy. Các trình quản lý được trả về theo tham chiếu và phiên bản GameServices chứa các trình quản lý này sẽ kiểm soát vòng đời của chúng. Ứng dụng của bạn không bao giờ được giữ lại một tham chiếu đến Manager. Thay vào đó, ứng dụng của bạn nên giữ lại thực thể GameServices.

    Trình quản lý trả về dữ liệu thông qua các đối tượng kiểu giá trị không thể thay đổi. Các giá trị này phản ánh một chế độ xem nhất quán về dữ liệu cơ bản tại thời điểm truy vấn được thực hiện.

    // Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);

// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();

  4. Khi bạn sử dụng xong đối tượng GameServices, hãy dọn dẹp bằng cách gọi reset() trên unique_ptr sở hữu đối tượng đó hoặc bằng cách cho phép unique_ptr tự động huỷ đối tượng khi ra khỏi phạm vi.

Mô hình luồng

Trừ phi có lưu ý khác, tất cả các phương thức GameServices và Trình quản lý đều có các phương thức triển khai không đồng bộ, an toàn cho luồng. Bạn có thể gọi các lệnh này trên bất kỳ luồng nào mà không cần khoá ngoài và các lệnh sẽ thực thi theo thứ tự nhất quán với thứ tự gọi.

Các phương thức truy cập (những phương thức đọc trạng thái) có 2 biến thể chính. Loại phương thức đầu tiên (có tên như FetchProperty()) cung cấp kết quả của nó một cách không đồng bộ cho một lệnh gọi lại được cung cấp; loại thứ hai (có tên như FetchPropertyBlocking()) trả về kết quả của nó một cách đồng bộ cho luồng gọi.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Tất cả các lệnh gọi lại của người dùng đều được gọi trên một luồng gọi lại chuyên dụng. Luồng này có thể khác biệt so với mọi khái niệm của nền tảng về "luồng chính" hoặc "luồng giao diện người dùng". Bạn cũng nên cố gắng đảm bảo rằng các lệnh gọi lại của người dùng thực thi nhanh chóng; một luồng lệnh gọi lại bị tạm dừng có thể gây ra các vấn đề mà người dùng nhìn thấy (ví dụ: yêu cầu đăng xuất hoàn tất muộn).

Thông tin dành riêng cho từng nền tảng

Để bắt đầu sử dụng Play Games C++ SDK trên Android, hãy chuyển đến hướng dẫn bắt đầu nhanh.

Tài liệu đọc thêm

Hãy nhớ đọc tài liệu về lớp có trong SDK C++ của Dịch vụ trò chơi của Google Play để biết thêm thông tin chi tiết và xem các mẫu minh hoạ cách sử dụng SDK.

Nếu trò chơi của bạn sử dụng máy chủ phụ trợ, hãy xem bài viết Bật quyền truy cập phía máy chủ vào Dịch vụ trò chơi của Google Play.