Integration requirements

  • This document outlines the required integration guidelines for games using the YouTube Playables SDK, including loading the SDK, managing game readiness, and handling user interactions.

  • Games must use specific Playables SDK functions, such as firstFrameReady and gameReady, to manage the loading process and indicate when the game is ready for player input.

  • The document details requirements for sending user scores, which involves using the sendScore function and ensuring accuracy in score tracking and saving.

  • Games must implement cloud saving using the saveData and loadData functions, ensuring data integrity and backward compatibility across different game versions.

  • Audio management is crucial, with games needing to respect system, device, and YouTube audio settings, and only using the isAudioEnabled and onAudioEnabledChange functions.

  • Games must pause and resume in accordance to onPause and onResume callbacks provided by the SDK.

This section covers the integration between the Playable and the YouTube Playables SDK.

1 Load Playables SDK

2 Game ready notification

  • Game MUST call firstFrameReady either when the game is rendering a loading screen or splash screen that explicitly communicates to the user that the loading process is underway.
  • Game MUST call gameReady and MUST only call gameReady when the game is ready for user interaction (example: main menu or game is ready to play).
  • Game MUST NOT call gameReady while there are still non-interactable elements being displayed to the user (example: splash screens or loading screens).

YouTube does not remove the "loading spinner" until this API is called.

3 User scores

  • Game MAY use sendScore to send the user's score.
  • If the game uses sendScore to send scores, the game MUST adhere to the sendScore specification and MUST ensure that the best score sent matches the best score in the game save.

4 Cloud saves

  • Game MUST call saveData to save progress when users have made material game progress (for example, a level change) where the game mechanics lead the user to believe that their progress is saved.
  • Game MUST NOT use any other mechanism to save user progress. This feature enables players to resume the game at a later point.
  • Game MUST await loadData before calling saveData. If saveData is called before loadData completes successfully, the request will be rejected. This prevents the game from overwriting any previously saved data.
  • Game MUST be able to use cloud save data from previous versions of the game without errors or crashes.
  • Game SHOULD use the cloud save data to maintain user progress across all game versions where the user would expect their data to be used.
  • Games SHOULD automatically save user progress at important game milestones to prevent data loss. A final flush save is performed when a user exits the game but is best effort and can only save up to 64 KiB in content length.

5 Mute toggle

  • Game MUST respect system audio setting and mute button.
  • Game MUST respect the YouTube audio setting and mute button by using isAudioEnabled and onAudioEnabledChange.
  • Game MUST respect the volume control on the device.
  • Game sound MUST NOT play unexpectedly.
  • When YouTube mute is set, audio MUST NOT be output and game audio controls MUST NOT affect audio output.
  • When YouTube mute is not set, game audio controls MAY affect audio output.
  • Game SHOULD NOT show an overall mute button within the game itself; allow users to rely on the YouTube-level features for this.
  • Game MAY have separate granular audio controls in the game, such as for music and sound effects, but they MUST follow all other audio control requirements.

Different audio settings for background, sfx, dialogs

6 Pause and resume

The Playables SDK provides callbacks that provide cross-platform pause and resume capabilities.

  • Game MUST pause all execution after onPause is called and MUST resume execution only when onResume is called. Execution includes all Playable capabilities, such as game loop, music, interactions, network calls, and rendering.
  • Game MUST NOT use the web Page Visibility API or similar web APIs and MUST only use Playables SDK onPause and onResume.
  • Game SHOULD save user progress when onPause occurs.