Integration requirements
Stay organized with collections
Save and categorize content based on your preferences.
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.
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-20 UTC."],[[["\u003cp\u003eThis document outlines the required integration guidelines for games using the YouTube Playables SDK, including loading the SDK, managing game readiness, and handling user interactions.\u003c/p\u003e\n"],["\u003cp\u003eGames must use specific Playables SDK functions, such as \u003ccode\u003efirstFrameReady\u003c/code\u003e and \u003ccode\u003egameReady\u003c/code\u003e, to manage the loading process and indicate when the game is ready for player input.\u003c/p\u003e\n"],["\u003cp\u003eThe document details requirements for sending user scores, which involves using the \u003ccode\u003esendScore\u003c/code\u003e function and ensuring accuracy in score tracking and saving.\u003c/p\u003e\n"],["\u003cp\u003eGames must implement cloud saving using the \u003ccode\u003esaveData\u003c/code\u003e and \u003ccode\u003eloadData\u003c/code\u003e functions, ensuring data integrity and backward compatibility across different game versions.\u003c/p\u003e\n"],["\u003cp\u003eAudio management is crucial, with games needing to respect system, device, and YouTube audio settings, and only using the \u003ccode\u003eisAudioEnabled\u003c/code\u003e and \u003ccode\u003eonAudioEnabledChange\u003c/code\u003e functions.\u003c/p\u003e\n"],["\u003cp\u003eGames must pause and resume in accordance to \u003ccode\u003eonPause\u003c/code\u003e and \u003ccode\u003eonResume\u003c/code\u003e callbacks provided by the SDK.\u003c/p\u003e\n"]]],["Games integrating with the YouTube Playables SDK must load the SDK first. They must signal readiness for loading and user interaction via `firstFrameReady` and `gameReady`. Games may send user scores with `sendScore`, ensuring consistency with game saves. For cloud saves, `saveData` and `loadData` are mandatory, preventing overwrites and ensuring data compatibility across versions. Games must also respect YouTube's audio settings and the mute button, using `isAudioEnabled` and `onAudioEnabledChange`, and they must pause and resume execution using `onPause` and `onResume`.\n"],null,["# Integration requirements\n\nThis section covers the integration between the Playable and the [YouTube\nPlayables SDK](/youtube/gaming/playables/reference/sdk).\n| **Important:** Translated requirements are provided for reference only. Refer to the [English versions of requirements](/youtube/gaming/playables/certification/requirements?hl=en) for definitive guidance.\n\n1 Load Playables SDK\n--------------------\n\n- Game **MUST** load the [YouTube Playables SDK](/youtube/gaming/playables/reference/sdk) before any of the game code.\n\n2 Game ready notification\n-------------------------\n\n- Game **MUST** call [`firstFrameReady`](/youtube/gaming/playables/reference/sdk#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.\n- Game **MUST** call [`gameReady`](/youtube/gaming/playables/reference/sdk#gameready) and **MUST** only call [`gameReady`](/youtube/gaming/playables/reference/sdk#gameready) when the game is ready for user interaction (example: main menu or game is ready to play).\n- Game **MUST NOT** call [`gameReady`](/youtube/gaming/playables/reference/sdk#gameready) while there are still non-interactable elements being displayed to the user (example: splash screens or loading screens).\n\nYouTube does not remove the \"loading spinner\" until this API is called.\n\n3 User scores\n-------------\n\n- Game **MAY** use [`sendScore`](/youtube/gaming/playables/reference/sdk#sendscore) to send the user's score.\n- If the game uses [`sendScore`](/youtube/gaming/playables/reference/sdk#sendscore) to send scores, the game **MUST** adhere to the [`sendScore`](/youtube/gaming/playables/reference/sdk#sendscore) specification and **MUST** ensure that the best score sent matches the best score in the game save.\n\n4 Cloud saves\n-------------\n\n- Game **MUST** call [`saveData`](/youtube/gaming/playables/reference/sdk#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.\n- Game **MUST NOT** use any other mechanism to save user progress. This feature enables players to resume the game at a later point.\n- Game **MUST** await [`loadData`](/youtube/gaming/playables/reference/sdk#loaddata) before calling [`saveData`](/youtube/gaming/playables/reference/sdk#savedata). If [`saveData`](/youtube/gaming/playables/reference/sdk#savedata) is called before [`loadData`](/youtube/gaming/playables/reference/sdk#loaddata) completes successfully, the request will be rejected. This prevents the game from overwriting any previously saved data.\n- Game **MUST** be able to use cloud save data from previous versions of the game without errors or crashes.\n- 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.\n- 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\n length](https://fetch.spec.whatwg.org/#http-network-or-cache-fetch:%7E:text=If%20the%20sum%20of%20contentLength%20and%20inflightKeepaliveBytes%20is%20greater%20than%2064%20kibibytes%2C%20then%20return%20a%20network%20error.).\n\n5 Mute toggle\n-------------\n\n- Game **MUST** respect system audio setting and mute button.\n- Game **MUST** respect the YouTube audio setting and mute button by using [`isAudioEnabled`](/youtube/gaming/playables/reference/sdk#isaudioenabled) and [`onAudioEnabledChange`](/youtube/gaming/playables/reference/sdk#onaudioenabledchange).\n- Game **MUST** respect the volume control on the device.\n- Game sound **MUST NOT** play unexpectedly.\n- When YouTube mute is set, audio **MUST NOT** be output and game audio controls **MUST NOT** affect audio output.\n- When YouTube mute is not set, game audio controls **MAY** affect audio output.\n- Game **SHOULD NOT** show an overall mute button within the game itself; allow users to rely on the YouTube-level features for this.\n- 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.\n\n6 Pause and resume\n------------------\n\nThe Playables SDK provides callbacks that provide cross-platform pause and\nresume capabilities.\n\n- Game **MUST** pause all execution after [`onPause`](/youtube/gaming/playables/reference/sdk#onpause) is called and **MUST** resume execution only when [`onResume`](/youtube/gaming/playables/reference/sdk#onresume) is called. Execution includes all Playable capabilities, such as game loop, music, interactions, network calls, and rendering.\n- Game **MUST NOT** use the web [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) or similar web APIs and **MUST** only use Playables SDK [`onPause`](/youtube/gaming/playables/reference/sdk#onpause) and [`onResume`](/youtube/gaming/playables/reference/sdk#onresume).\n- Game **SHOULD** save user progress when [`onPause`](/youtube/gaming/playables/reference/sdk#onpause) occurs."]]