Nâng tầm trò chơi bằng SDK Play Games dành cho máy tính

và khởi động Play Games SDK cho máy tính vào cả dự án trò chơi Native C++ và Unity C#. keywords_public: android,games,playgames,native-pc,setup,sdk,c++,c#,initialization,google play games for pc

Với Play Games PC SDK, bạn có thể truy cập vào Dịch vụ Google Play để tạo và kiếm tiền từ trò chơi của mình trên máy tính. Bán nội dung kỹ thuật số bằng Play Billing, đăng nhập liền mạch bằng Play Games và xác minh rằng người dùng có quyền hợp lệ đối với ứng dụng của bạn bằng Play Integrity.

Bạn đã sẵn sàng bắt đầu?

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

• Tạo một mục nhập ứng dụng trong Play Console và xác nhận quyền sở hữu tên gói Play.

• Tải xuống và cài đặt Google Play Games cho máy tính rồi đăng nhập bằng Tài khoản Google của bạn.

Bước 1: Thêm SDK vào dự án của bạn

Bước 2: Thêm tệp kê khai

Trước khi có thể sử dụng SDK trong trò chơi, bạn cần liên kết tệp thực thi trò chơi với tên gói Play mà bạn đã xác nhận quyền sở hữu trong Play Console. Bạn có thể thực hiện việc này bằng cách thêm một tệp manifest.xml vào cùng thư mục với tệp thực thi của trò chơi.

Ví dụ về nội dung manifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<?Manifest version="1">
   <?Application>
     <?PackageName>com.example.package<?/PackageName>
   <?/Application>
<?/Manifest>

Ví dụ về vị trí manifest.xml:

C:\Program Files
└───Example Game
    ├───Game.exe
    └───manifest.xml

Bước 3: Ký số cho trò chơi

Trước khi trò chơi có thể sử dụng SDK, tệp thực thi của trò chơi phải được ký điện tử bằng Chữ ký số Authenticode. Để biết hướng dẫn về cách ký một tệp thực thi, hãy xem tài liệu về SignTool .

Sau khi hoàn tất quy trình ký số cho trò chơi, hãy gửi thông tin chứng chỉ cho người đại diện của Google để họ định cấu hình.

Bước 4: Khởi chạy SDK

Khởi chạy SDK trong trình tự khởi động của trò chơi. Việc này phải được thực hiện tự động mà không cần bất kỳ lượt tương tác nào của người dùng và bạn nên xác minh quá trình khởi tạo thành công trước khi hiển thị cửa sổ trò chơi. Điều này mang lại trải nghiệm người dùng tốt nhất bằng cách hiển thị và giải quyết lỗi trong thời gian sớm nhất có thể, đồng thời tránh trường hợp cửa sổ trò chơi của bạn xuất hiện trong thời gian ngắn khi quy trình trò chơi cần thoát.

Bắt đầu sử dụng SDK bằng cách gọi GooglePlayInitialize (C++) / GooglePlayInitialization.InitializeAsync (C#) để khởi chạy API. Thao tác này sẽ thiết lập trạng thái chung, kết nối với thời gian chạy SDK và xác minh rằng ứng dụng đã khởi động đúng cách. Bạn PHẢI gọi và hoàn tất lệnh gọi lại tiếp tục bằng InitializeResult::ok() (C++) / Result.IsOk (C#) bằng true trước khi có thể sử dụng bất kỳ API nào khác.

  // Initialize the SDK as part of the startup sequence of your application.
  auto promise = std::make_shared<std::promise<InitializeResult>>();
  GooglePlayInitialize(
    [promise](InitializeResult result) {
      promise->set_value(std::move(result));
    });

  auto initialize_result = promise->get_future().get();
  if (initialize_result.ok()) {
    // The SDK succeeded with initialization. Continue with the startup sequence
    // of the game.
    // ...
  } else if (initialize_result.code() == InitializationError::kActionRequiredShutdownClientProcess) {
    // The SDK failed to initialize and has requested that your game process exit
    // as soon as possible.
    exit(1);
  } else {
    // The SDK failed to initialize for an alternative reason. It is still
    // generally recommended that you exit the game process as soon as possible,
    // because it won't be possible to access any APIs in the SDK. Critical
    // operations such as verifying the user owns a valid license to your game
    // won't be possible.
    // ...
  }

  // SDK Clients
  private BillingClient _billingClient;
  private IntegrityClient _integrityClient;

  // Stored product information
  private string _offerToken;

  private async void InitializeSDK()
  {
      // The factory provides the necessary handler for initialization.
      var initializationHandler = PlayPcSdkFactory.InitializationHandler;
      var result = await GooglePlayInitialization.InitializeAsync(initializationHandler);

      if (result.IsOk)
      {
          // Use the factory to get Unity-compatible instances of the clients
          _billingClient = PlayPcSdkFactory.CreateBillingClient();
          _integrityClient = PlayPcSdkFactory.CreateIntegrityClient();

          // SDK is ready for use
      }
      else
      {
          // Handle specific, actionable errors
          if (result.Code == InitializationError.ActionRequiredShutdownClientProcess)
          {
              Log("This game must be launched through the Google Play Games client. Please exit all game processes immediately, GPG will relaunch the game safely.");
              Application.Quit();
          }
      }
  }

Nếu quá trình khởi chạy không thành công với mã kActionRequiredShutdownClientProcess (C++) / InitializationError.ActionRequiredShutdownClientProcess (C#), hãy thoát khỏi quy trình trò chơi càng sớm càng tốt. Thời gian chạy của SDK sẽ cố gắng hỗ trợ người dùng mà không yêu cầu trò chơi của bạn làm gì thêm. Ví dụ: nếu người dùng không có giấy phép hợp lệ để chơi trò chơi, Google Play Games sẽ nhắc người dùng mua một bản sao. Đối với các lỗi khác, bạn cũng nên thoát khỏi quy trình trò chơi vì bạn sẽ không thể dùng SDK để thực hiện các thao tác quan trọng, chẳng hạn như xác minh xem người dùng có giấy phép hợp lệ cho trò chơi của bạn hay không.

Phản hồi không thành công có thể cho biết một trong các điều kiện sau:

• Thời gian chạy SDK chưa được cài đặt, không chạy trên thiết bị hoặc là phiên bản cũ không tương thích với SDK được tích hợp vào trò chơi của bạn.

• Thời gian chạy SDK không xác minh được danh tính ứng dụng của trò chơi. Nguyên nhân có thể là do manifest.xml không hợp lệ hoặc sử dụng SDK mà không bật chế độ nhà phát triển khi phát triển. Nếu không có khoá này, tệp thực thi của trò chơi phải được ký bằng chứng chỉ số đã đăng ký cho tên gói của bạn trên Play.

• Tệp thực thi trò chơi không được khởi chạy thông qua ứng dụng Google Play Games.

• Người dùng đang hoạt động trong Google Play Games không có giấy phép cho ứng dụng.

Bước 5: (Không bắt buộc) Hỗ trợ nhiều quy trình trò chơi

Hoàn tất các bước tích hợp bổ sung này nếu trò chơi của bạn sử dụng nhiều quy trình và Play Games PC SDK được một quy trình khác sử dụng so với quy trình do Google Play Games trên máy tính khởi chạy. Ví dụ: nếu Google Play Games trên máy tính khởi chạy trình chạy của trò chơi, thì trình chạy sẽ bắt đầu quy trình trò chơi tương tác với SDK.

1. Quy trình do Google Play Games dành cho máy tính trực tiếp khởi chạy phải xác minh quá trình khởi chạy SDK Play Games dành cho máy tính thành công.

   Điều này mang lại trải nghiệm người dùng tốt nhất bằng cách hiển thị lỗi sớm nhất có thể. Xin lưu ý rằng quy trình con sử dụng SDK cũng phải thực hiện quá trình khởi tạo ngoài quy trình được khởi chạy trực tiếp.

2. Để sử dụng Play Games PC SDK trong một quy trình con, hãy chuyển tiếp các tham số dòng lệnh đến quy trình con được tạo.

   Ví dụ về việc chuyển tiếp tham số dòng lệnh:

   Processes hierarchy tree:
   
   GooglePlayGames.exe
   └───YourGameLauncher.exe --gpg_args=abc --your_args=123
       └───YourGame.exe --gpg_args=abc --your_args=123
   

   Trong ví dụ này, chúng ta thấy một hệ thống phân cấp quy trình trong đó Google Play Games dành cho máy tính (GooglePlayGames.exe) khởi chạy trò chơi (YourGameLauncher.exe) với một số tham số ví dụ (--gpg_args=abc --your_args=123). Sau đó, trò chơi sẽ tạo một quy trình con (YourGame.exe) sử dụng Play Games PC SDK. Để cho phép điều này, quy trình trò chơi do Google Play Games trên máy tính khởi chạy sẽ chuyển tiếp các tham số dòng lệnh đã được cung cấp cho quy trình con.

3. Thoát khỏi tất cả các quy trình khi trò chơi ngừng chạy.

   Khi người dùng đóng trò chơi của bạn hoặc trò chơi thoát do lỗi khởi tạo SDK, chẳng hạn như kActionRequiredShutdownClientProcess, hãy đóng tất cả các quy trình mà trò chơi của bạn đã tạo. Điều này đảm bảo rằng vào lần tiếp theo khi trò chơi của bạn được ứng dụng Google Play Games cho máy tính khởi chạy, những thay đổi mới (chẳng hạn như chuyển sang một tài khoản đang hoạt động khác) sẽ có hiệu lực.

Bước 6: Bật tính năng Tự động phát khi cài đặt trò chơi gốc trên máy tính

Google Play Games trên máy tính (GPG) cho phép nhà phát triển bật tính năng "tự động phát". Tính năng này sẽ tự động khởi chạy trò chơi của bạn ngay sau khi quá trình cài đặt hoàn tất. Tính năng này mang đến trải nghiệm liền mạch cho người dùng bằng cách chuyển người chơi trực tiếp vào trò chơi, được xác thực hoàn toàn trong hệ sinh thái GPG.

Cách hoạt động

Khi bạn bật tính năng này, GPG sẽ truyền mã thông báo phiên GPG đến quy trình cài đặt của bên thứ ba (3P) thông qua các đối số dòng lệnh. Sau đó, trình cài đặt của bạn sẽ chịu trách nhiệm trích xuất mã thông báo này và dùng mã thông báo đó để chạy tệp thực thi trò chơi trong một bối cảnh đã xác thực.

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

Để sử dụng tính năng này, trình cài đặt bên thứ ba phải có khả năng xử lý các đối số dòng lệnh.

Các bước triển khai

1. Bật tính năng Tự động phát trong Cấu hình xuất bản

   Để chọn sử dụng tính năng này, hãy thêm thuộc tính acceptsCommandLineArguments vào phần tử <installer> trong play_publishing_config.xml.

   Ví dụ về nội dung manifest.xml:

   <installer requiresElevation="true" acceptsCommandLineArguments="true">
     <path>path/to/installer.exe</path>
     <installation-path-registry-location>
       <key-name>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\key</key-name>
       <value-name>InstallPath</value-name>
     </installation-path-registry-location>
   </installer>
   

   • Thuộc tính: acceptsCommandLineArguments
   • Loại: Boolean
   • Mặc định: false
   • Hành vi: Khi bạn đặt giá trị này thành true, GPG sẽ thêm mã thông báo phiên vào đối số dòng lệnh khi thực thi trình cài đặt.

2. Xử lý mã thông báo phiên trong trình cài đặt

   Khi ứng dụng GPG khởi chạy trình cài đặt của bạn, trình cài đặt đó sẽ nhận được mã thông báo phiên dưới dạng đối số dòng lệnh.

   • Định dạng đối số: --g_session_token=<TOKEN>

   Những việc bạn phải làm:

   • Trích xuất: Trình cài đặt phải phân tích cú pháp các đối số dòng lệnh để truy xuất chuỗi mã thông báo.
   • Truyền tải: Nếu quy trình cài đặt của bạn liên quan đến việc chạy một quy trình trình chạy hoặc trò chơi phụ, thì trình cài đặt của bạn chịu trách nhiệm truyền mã thông báo phiên một cách an toàn đến quy trình trò chơi cuối cùng sử dụng SDK.
   • Khởi chạy: Sử dụng mã thông báo phiên được cung cấp để khởi động tệp thực thi trò chơi. Điều này đảm bảo trò chơi chạy trong một ngữ cảnh GPG đã xác thực. Nếu không, InitializeSDK sẽ không thành công và người chơi sẽ cần khởi động lại trò chơi.

3. Xử lý lỗi và dự phòng

• Truy xuất mã thông báo: Nếu vì bất kỳ lý do nào mà GPG không thể tạo hoặc truyền mã thông báo phiên (ví dụ: không tạo được mã thông báo), thì quy trình cài đặt vẫn sẽ tiếp tục. Tuy nhiên, trình cài đặt của bạn sẽ được khởi chạy mà không có đối số --g_session_token.
• Tính ổn định: Trình cài đặt của bạn phải được thiết kế để xử lý các trường hợp không có mã thông báo phiên. Trong những trường hợp như vậy, trình cài đặt sẽ tiến hành cài đặt tiêu chuẩn; bạn không nên kích hoạt tính năng khởi chạy trò chơi tự động vì InitializeSDK sẽ không thành công.
• Lỗi trình cài đặt: Bạn chịu trách nhiệm về độ ổn định và khả năng xử lý lỗi của trình cài đặt cũng như trình tự khởi chạy trò chơi mà trình cài đặt đó khởi tạo. GPG không kiểm soát các quy trình diễn ra trong trình cài đặt sau khi trình cài đặt được khởi chạy.

Các bước tiếp theo

Sử dụng SDK trong khi phát triển trong IDE:

• Bật chế độ nhà phát triển

Thêm các tính năng của Google Play trên máy tính vào ứng dụng:

• Bán hàng hoá kỹ thuật số bằng Play Billing
• Đo lường hoạt động tiếp thị bằng Play Install Referrer
• Bảo vệ trò chơi của bạn bằng Play Integrity cho máy tính