이 페이지는 Cloud Translation API를 통해 번역되었습니다.

YouTube 게임 룸 SDK 참조

ytgame

YouTube Playables SDK의 최상위 네임스페이스입니다.

현재 창에서 전역 범위 변수입니다. 이 변수는 재정의하면 안 됩니다.

네임스페이스
`ads`	🧪 공개 미리보기 API: 예고 없이 변경될 수 있습니다.
`engagement`	플레이어 참여와 관련된 함수 및 속성입니다.
`game`	일반적인 게임 동작과 관련된 함수 및 속성입니다.
`health`	게임 상태와 관련된 함수 및 속성입니다.
`system`	YouTube 시스템과 관련된 함수 및 속성입니다.

열거
`SdkErrorType`	YouTube Playables SDK에서 발생하는 오류 유형입니다.

클래스
`SdkError`	YouTube Playables SDK에서 발생하는 오류 객체입니다.

변수
`IN_PLAYABLES_ENV`	게임이 Playables 환경 내에서 실행 중인지 여부입니다.
`SDK_VERSION`	YouTube Playables SDK 버전입니다.

참고 항목

https://developers.google.com/youtube/gaming/playables

열거

`Const` SdkErrorType

SdkErrorType

YouTube Playables SDK에서 발생하는 오류 유형입니다.

열거 멤버
`API_UNAVAILABLE`	API를 일시적으로 사용할 수 없습니다. 플레이어가 중요한 흐름에 있는 경우 나중에 다시 시도하도록 요청합니다.
`INVALID_PARAMS`	잘못된 매개변수로 API가 호출되었습니다.
`SIZE_LIMIT_EXCEEDED`	크기 한도를 초과하는 매개변수로 API가 호출되었습니다.
`UNKNOWN`	알 수 없는 오류 유형입니다.

변수

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

게임이 Playables 환경 내에서 실행 중인지 여부입니다. 이를 사용하여 플레이어블 내에서만 사용할 수 있는 기능을 사용 설정하거나 사용 중지할 수 있습니다. 이 검사를 ytgame 확인과 결합하여 SDK가 실제로 로드되는지 확인합니다.

예

const inPlayablesEnv = typeof ytgame !== "undefined" && ytgame.IN_PLAYABLES_ENV;

// An example of where you may want to fork behavior for saving data.
if (ytgame?.IN_PLAYABLES_ENV) {
  ytgame.game.saveData(dataStr);
} else {
  window.localStorage.setItem("SAVE_DATA", dataStr);
}

`Const` SDK_VERSION

SDK_VERSION: string

YouTube Playables SDK 버전입니다.

예

// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

Error 확장

YouTube Playables SDK에서 발생하는 오류 객체입니다.

SdkError 객체는 Error의 하위 요소이며 추가 필드를 포함합니다.

생성자
`constructor`

속성
`errorType`	오류 유형입니다.
`message`
`name`
`stack?`

속성

errorType

errorType:
                  SdkErrorType

오류 유형입니다.

ytgame.ads

🧪 PUBLIC PREVIEW API: 예고 없이 변경될 수 있습니다.

광고와 관련된 함수 및 속성입니다.

함수
`requestInterstitialAd`	전면 광고를 표시하도록 요청합니다.

함수

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental 전면 광고를 표시하도록 요청합니다.

🧪 공개 미리보기 API: 예고 없이 변경될 수 있습니다.

광고가 게재되었는지 여부에 대한 보장은 하지 않습니다.

예

try {
  await ytgame.ads.requestInterstitialAd();
  // Ad request successful, do something else.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}

반환 값
`Promise<void>`	요청에 성공하면 결정되는 프로미스 또는 요청에 실패하면 거부/예외가 발생하는 프로미스

ytgame.engagement

플레이어 참여와 관련된 함수 및 속성입니다.

인터페이스
`Content`	게임에서 YouTube로 전송하는 콘텐츠 객체입니다.
`Score`	게임에서 YouTube로 전송하는 점수 객체입니다.

함수
`openYTContent`	제공된 동영상 ID에 해당하는 콘텐츠를 열도록 YouTube에 요청합니다.
`sendScore`	YouTube에 점수를 전송합니다.

함수

openYTContent

openYTContent(content: Content): Promise<void>

제공된 동영상 ID에 해당하는 콘텐츠를 열도록 YouTube에 요청합니다.

일반적으로 이 경우 웹에서는 새 탭에서, 모바일에서는 미니 플레이어에서 동영상이 열립니다.

예

async function showVideo(videoID: string) {
  try {
    await ytgame.engagement.openYTContent({ id: videoID });
    // Request successful, do something else.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

매개변수
`content: Content`	YouTube에서 열려는 콘텐츠를 선택합니다.

반환 값
`Promise<void>`	성공하면 결정되고 실패하면 `ytgame.SdkError`로 거부/예외가 발생하는 Promise입니다.

sendScore

sendScore(score: Score): Promise<void>

YouTube에 점수를 전송합니다.

점수는 게임 내 진행 상황의 한 측정기준을 나타내야 합니다. 측정기준이 여러 개인 경우 개발자는 일관성을 위해 하나의 측정기준을 선택해야 합니다. 점수가 정렬되고 가장 높은 점수가 YouTube UI에 표시되므로 게임 내 최고 점수 UI는 이 API를 통해 전송되는 점수와 일치해야 합니다.

예

async function onScoreAwarded(score: number) {
  try {
    await ytgame.engagement.sendScore({ value: score });
    // Score sent successfully, do something else.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

매개변수
`score: Score`	YouTube로 전송할 점수입니다.

반환 값
`Promise<void>`	성공하면 결정되고 실패하면 `ytgame.SdkError`로 거부/예외가 발생하는 Promise입니다.

ytgame.engagement.Content

게임에서 YouTube로 전송하는 콘텐츠 객체입니다.

속성
`id`	열려는 동영상의 ID입니다.

속성

id

id: string

열려는 동영상의 ID입니다.

ytgame.engagement.Score

게임에서 YouTube로 전송하는 점수 객체입니다.

속성
`value`	정수로 표현된 점수 값입니다.

속성

value

value: number

정수로 표현된 점수 값입니다. 점수는 최대 안전 정수보다 작거나 같아야 합니다. 그렇지 않으면 점수가 거부됩니다.

ytgame.game

일반적인 게임 동작과 관련된 함수 및 속성입니다.

함수
`firstFrameReady`	게임에서 프레임 표시를 시작했음을 YouTube에 알립니다.
`gameReady`	플레이어가 상호작용할 준비가 되었다고 YouTube에 알립니다.
`loadData`	직렬화된 문자열 형식으로 YouTube에서 게임 데이터를 로드합니다.
`saveData`	직렬화된 문자열 형식으로 게임 데이터를 YouTube에 저장합니다.

함수

firstFrameReady

firstFrameReady(): void

게임에서 프레임을 표시하기 시작했다고 YouTube에 알립니다.

게임은 이 API를 MUST. 그렇지 않으면 게임이 사용자에게 표시되지 않습니다. gameReady() 전에 firstFrameReady()를 호출MUST.

예

function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void

플레이어가 상호작용할 준비가 되었다고 YouTube에 알립니다.

상호작용이 가능한 경우 게임은 이 API를 호출MUST. 로드 화면이 여전히 표시되어 있을 때 게임에서 이 API를 호출해서는 안 됩니다. 그러지 않으면 게임이 YouTube 인증 프로세스에 실패합니다.

예

function onGameInteractable() {
  ytgame.game.gameReady();
}

loadData

loadData(): Promise<string>

YouTube에서 직렬화된 문자열 형식으로 게임 데이터를 로드합니다.

게임은 문자열과 내부 형식 간의 모든 파싱을 처리해야 합니다.

예

async function gameSetup() {
  try {
    const data = await ytgame.game.loadData();
    // Load succeeded, do something with data.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

반환 값
`Promise<string>`	로드에 성공하면 완료되고 실패하면 `ytgame.SdkError`로 거부되는 Promise입니다.

saveData

saveData(data: string): Promise<void>

직렬화된 문자열 형식으로 게임 데이터를 YouTube에 저장합니다.

문자열은 유효하고 올바른 형식의 UTF-16 문자열이어야 하며 최대 3MiB여야 합니다. 게임은 문자열과 내부 형식 간의 파싱을 처리해야 합니다. 필요한 경우 String.isWellFormed()을 사용하여 문자열의 형식이 올바른지 확인합니다.

예

async function saveGame() {
  try {
    ytgame.game.saveData(JSON.stringify(gameSave));
    // Save succeeded.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

매개변수
`data: string`

반환 값
`Promise<void>`	저장에 성공하면 결정되고 실패하면 `ytgame.SdkError`로 거부되는 Promise입니다.

ytgame.health

게임 상태와 관련된 함수 및 속성입니다.

함수
`logError`	YouTube에 오류를 로깅합니다.
`logWarning`	YouTube에 경고를 기록합니다.

함수

logError

logError(): void

YouTube에 오류를 로깅합니다.

참고: 이 API는 최선의 방식으로 실행되며 비율이 제한되어 데이터 손실이 발생할 수 있습니다.

예

function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void

YouTube에 경고를 로깅합니다.

참고: 이 API는 최선을 다하고 비율이 제한되어 데이터 손실이 발생할 수 있습니다.

예

function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

YouTube 시스템과 관련된 함수 및 속성입니다.

함수
`getLanguage`	사용자의 YouTube 설정에 설정된 언어를 BCP-47 언어 태그 형식으로 반환합니다.
`isAudioEnabled`	YouTube 설정에서 게임 오디오가 사용 설정되어 있는지 여부를 반환합니다.
`onAudioEnabledChange`	YouTube에서 오디오 설정 변경 이벤트가 실행될 때 트리거되도록 콜백을 설정합니다.
`onPause`	YouTube에서 일시중지 게임 이벤트가 실행될 때 트리거될 콜백을 설정합니다.
`onResume`	YouTube에서 게임 재개 이벤트가 실행될 때 트리거되도록 콜백을 설정합니다.

함수

getLanguage

getLanguage(): Promise<string>

사용자의 YouTube 설정에 설정된 언어를 BCP-47 언어 태그 형식으로 반환합니다.

다른 함수를 사용하여 사용자의 언어 또는 언어를 결정하거나 클라우드 저장에 언어 환경설정을 저장하지 마세요. 대신 이 함수를 사용하여 YouTube 전반에서 일관된 사용자 환경을 제공하세요.

예

const localeTag = await ytgame.system.getLanguage();
// `localeTag` is now set to something like "en-US" or "es-419".

반환 값
`Promise<string>`	언어 가져오기에 성공하면 완료되고 실패하면 `ytgame.SdkError`로 거부되는 Promise입니다.

isAudioEnabled

isAudioEnabled(): boolean

YouTube 설정에서 게임 오디오가 사용 설정되어 있는지 여부를 반환합니다.

게임은 이를 사용하여 게임 오디오 상태를 초기화해야 함.

예

function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}

반환 값
`boolean`	오디오가 사용 설정되어 있는지 나타내는 불리언입니다.

onAudioEnabledChange

onAudioEnabledChange(callback: ((isAudioEnabled: boolean) => void)): (() => void)

YouTube에서 오디오 설정 변경 이벤트가 발생할 때 트리거될 콜백을 설정합니다.

게임은 이 API를 사용하여 게임 오디오 상태를 업데이트해야 MUST.

예

ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});

매개변수
`callback: ((isAudioEnabled: boolean) => void)`	트리거할 콜백 함수입니다.

반환 값
`(() => void)`	일반적으로 사용되지 않는 콜백을 설정 해제하는 함수입니다.

onPause

onPause(callback: (() => void)): (() => void)

YouTube에서 일시중지 게임 이벤트가 실행될 때 트리거될 콜백을 설정합니다. 게임은 삭제되기 전에 상태를 저장할 수 있는 짧은 시간 내에 있습니다.

onPause는 사용자가 게임을 종료할 때를 비롯한 모든 유형의 일시중지 시 호출됩니다. 게임이 재개된다는 보장은 없습니다.

예

ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}

매개변수
`callback: (() => void)`	트리거할 콜백 함수입니다.

반환 값
`(() => void)`	일반적으로 사용되지 않는 콜백을 설정 해제하는 함수입니다.

onResume

onResume(callback: (() => void)): (() => void)

YouTube에서 게임 재개 이벤트가 실행될 때 트리거될 콜백을 설정합니다.

일시중지된 후 게임이 재개되지 않을 수 있습니다.

예

ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}

매개변수
`callback: (() => void)`	트리거할 콜백 함수입니다.

반환 값
`(() => void)`	일반적으로 사용되지 않는 콜백을 설정 해제하는 함수입니다.

YouTube 게임 룸 SDK 참조 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

ytgame

열거

Const SdkErrorType

변수

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

속성

errorType

ytgame.ads

함수

requestInterstitialAd

ytgame.engagement

함수

openYTContent

sendScore

ytgame.engagement.Content

속성

id

ytgame.engagement.Score

속성

value

ytgame.game

함수

firstFrameReady

gameReady

loadData

saveData

ytgame.health

함수

logError

logWarning

ytgame.system

함수

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

YouTube 게임 룸 SDK 참조

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION