Улучшите свою игру с помощью Play Games PC SDK

и инициализация SDK Play Games PC в игровых проектах на Native C++ и Unity C#. keywords_public: android, games, playgames, native-pc, setup, sdk, c++, c#, initialization, google play games for pc

С помощью Play Games PC SDK вы можете получить доступ к сервисам Google Play для создания и монетизации своей игры на ПК. Продавайте цифровой контент с помощью Play Billing, беспрепятственно входите в систему через Play Games и проверяйте наличие у пользователей действительных прав доступа к вашему приложению с помощью Play Integrity.

Готовы начать?

Предварительные требования

• Создайте запись о приложении в Play Console и укажите имя пакета Play.

• Скачайте и установите Google Play Games для ПК и войдите в свою учетную запись Google.

Шаг 1 : Добавьте SDK в свой проект.

Шаг 2 : Добавьте файл манифеста

Прежде чем использовать SDK в своей игре, вам необходимо связать исполняемый файл игры с именем пакета Play, которое вы указали в Play Console. Это делается путем добавления файла manifest.xml в ту же директорию, что и исполняемый файл игры.

Пример содержимого файла manifest.xml :

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

Пример размещения manifest.xml :

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

Шаг 3 : Подпишите свою игру цифровой подписью.

Прежде чем ваша игра сможет использовать SDK, исполняемый файл игры должен быть подписан цифровой подписью Authenticode . Инструкции по подписанию исполняемого файла см. в документации SignTool .

После завершения процесса цифровой подписи вашей игры отправьте информацию о сертификате представителю Google для настройки.

Шаг 4 : Инициализация SDK

Инициализируйте SDK во время запуска игры. Это должно происходить автоматически, без участия пользователя, и рекомендуется проверять успешную инициализацию перед отображением игрового окна. Это обеспечивает наилучшее взаимодействие с пользователем, поскольку ошибки выявляются и устраняются как можно быстрее, а также предотвращает кратковременное появление игрового окна в случаях, когда процесс игры должен завершиться.

Для начала использования SDK вызовите метод GooglePlayInitialize (C++) / GooglePlayInitialization.InitializeAsync (C#) для инициализации API. Это позволит настроить глобальное состояние, установить соединение со средой выполнения SDK и проверить корректность запуска приложения. Перед использованием любого другого API НЕОБХОДИМО вызвать этот метод, и в результате выполнения метода InitializeResult::ok() (C++) / Result.IsOk (C#) должно быть установлено значение true .

  // 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();
          }
      }
  }

Если инициализация завершается с ошибкой kActionRequiredShutdownClientProcess (C++) / InitializationError.ActionRequiredShutdownClientProcess (C#), завершите игровой процесс как можно скорее . Среда выполнения SDK попытается помочь пользователю, не требуя от игры никаких дополнительных действий. Например, если у пользователя нет действующей лицензии на игру, Google Play Games предложит ему приобрести копию. При других ошибках также следует завершить игровой процесс, поскольку вы не сможете использовать SDK для выполнения критически важных операций, таких как проверка наличия у пользователя действующей лицензии на вашу игру.

Неудачный ответ может указывать на одно из следующих условий:

• Среда выполнения SDK не установлена, не запущена на устройстве или является более старой версией, несовместимой с SDK, интегрированным в вашу игру.

• Среда выполнения SDK не смогла проверить подлинность приложения игры. Это может быть связано с некорректным файлом manifest.xml или использованием SDK без включения режима разработчика при разработке. Без этого исполняемый файл вашей игры должен быть подписан цифровой подписью с использованием цифрового сертификата, зарегистрированного для имени вашего пакета Play.

• Запуск игры осуществлялся не через игровой клиент Google Play.

• Активный пользователь Google Play Games не владеет лицензией на приложение.

Шаг 5 : (Необязательно) Поддержка нескольких игровых процессов

Выполните эти дополнительные шаги интеграции, если ваша игра использует несколько процессов, и SDK Play Games для ПК используется другим процессом, отличным от того, который запускается Google Play Games на ПК. Например, если Google Play Games на ПК запускает лаунчер вашей игры, а затем ваш лаунчер запускает процесс игры, который будет взаимодействовать с SDK.

1. Процесс, непосредственно запускаемый Google Play Games для ПК, должен подтвердить успешную инициализацию Play Games PC SDK .

   Это обеспечивает наилучшее взаимодействие с пользователем, выявляя ошибки как можно быстрее. Обратите внимание, что дочерний процесс, использующий SDK, должен также выполнять инициализацию в дополнение к непосредственно запущенному процессу.

2. Для использования Play Games PC SDK в дочернем процессе передайте параметры командной строки запущенному дочернему процессу.

   Пример пересылки параметров командной строки:

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

   В этом примере мы видим иерархию процессов, где Google Play Games для ПК ( GooglePlayGames.exe ) запускает игру ( YourGameLauncher.exe ) с некоторыми примерами параметров ( --gpg_args=abc --your_args=123 ). Затем игра запускает дочерний процесс ( YourGame.exe ), который использует SDK Play Games для ПК. Для этого процесс игры, запущенный Google Play Games для ПК, передаёт дочернему процессу параметры командной строки, которые ему были переданы.

3. Завершите все процессы, когда игра остановится.

   Когда пользователь закрывает вашу игру или игра завершается из-за ошибки инициализации SDK, например, kActionRequiredShutdownClientProcess , закройте все процессы, запущенные вашей игрой. Это гарантирует, что при следующем запуске игры через клиент Google Play Games для ПК новые изменения, такие как переключение на другую активную учетную запись, вступят в силу.

Шаг 6 : Включение автозапуска при установке игр, изначально предназначенных для ПК.

Google Play Games на ПК (GPG) позволяет разработчикам включать функцию «автозапуска», которая автоматически запускает игру сразу после завершения процесса установки. Эта функция обеспечивает бесперебойную работу для пользователя, позволяя игроку сразу же погрузиться в игру, полностью авторизованному в рамках экосистемы GPG.

Как это работает

При включении этой функции GPG передаст токен сессии GPG процессу установки стороннего разработчика (3P) через аргументы командной строки. Затем ваш установщик будет отвечать за извлечение этого токена и его использование для запуска исполняемого файла игры в аутентифицированном контексте.

Предварительные требования

Для использования этой функции ваш сторонний установщик должен уметь обрабатывать аргументы командной строки.

Этапы реализации

1. Включите автоматическое воспроизведение в настройках публикации.

   Чтобы включить эту функцию, добавьте атрибут acceptsCommandLineArguments к элементу <installer> в файле play_publishing_config.xml .

   Пример содержимого файла 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>
   

   • Атрибут: acceptsCommandLineArguments
   • Тип: Boolean
   • По умолчанию: false
   • Режим работы: Если установить значение true, GPG добавит токен сессии к аргументам командной строки при выполнении установщика.

2. Обработайте токен сессии в вашем установщике.

   При запуске установщика клиентом GPG он получит токен сессии в качестве аргумента командной строки.

   • Формат аргументов: --g_session_token=<TOKEN>

   Что вам необходимо сделать:

   • Извлечение: Вашему установщику необходимо проанализировать аргументы командной строки, чтобы получить строку токена.
   • Передача данных: Если процесс установки включает запуск дополнительного средства запуска или игрового процесса, ваш установщик отвечает за безопасную передачу токена сессии конечному игровому процессу, использующему SDK.
   • Запуск: Используйте предоставленный токен сессии для запуска исполняемого файла игры. Это гарантирует запуск игры в аутентифицированном контексте GPG. В противном случае InitializeSDK завершится с ошибкой, и игроку потребуется перезапустить игру.

3. Обработка ошибок и резервные варианты

• Получение токена: Если по какой-либо причине GPG не может сгенерировать или передать токен сессии (например, ошибка генерации токена), процесс установки все равно продолжится. Однако ваш установщик будет запущен без аргумента --g_session_token.
• Надежность: Ваш установщик должен быть разработан таким образом, чтобы обрабатывать сценарии, в которых токен сессии отсутствует. В таких случаях установщик должен продолжить стандартную установку; не следует запускать автоматическую установку игры, так как InitializeSDK в любом случае завершится ошибкой.
• Ошибки установщика: Вы несете ответственность за надежность и обработку ошибок вашего установщика и последовательности запуска игры, которую он инициирует. GPG не контролирует процессы, происходящие внутри установщика после его запуска.

Следующие шаги

Используйте SDK при разработке в вашей IDE:

• Включить режим разработчика

Добавьте в своё приложение функции Google Play для ПК:

• Продавайте цифровые товары с помощью Play Billing.
• Оцените эффективность своего маркетинга с помощью Play Install Referrer.
• Защитите свою игру с помощью Play Integrity для ПК.