YouTube 게임 룸 SDK 참조

ytgame

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

이는 현재 창의 전역 범위 변수입니다. 이 변수를 재정의하면 안 됩니다(MUST NOT).
네임스페이스
ads
🧪 공개 미리보기 API: 예고 없이 변경될 수 있습니다.
engagement
플레이어 참여와 관련된 함수 및 속성입니다.
game
일반 게임 동작과 관련된 함수 및 속성입니다.
health
게임 상태와 관련된 함수 및 속성입니다.
system
YouTube 시스템과 관련된 함수 및 속성입니다.
열거
SdkErrorType
YouTube 게임 룸 SDK에서 발생하는 오류 유형입니다.
클래스
SdkError
YouTube Playables SDK에서 발생시키는 오류 객체입니다.
변수
IN_PLAYABLES_ENV
게임이 게임 룸 환경 내에서 실행되고 있는지 여부입니다.
SDK_VERSION
YouTube 게임 SDK 버전입니다.
참고 항목

열거

Const SdkErrorType

SdkErrorType
YouTube 게임 룸 SDK에서 발생하는 오류 유형입니다.
열거형 멤버
API_UNAVAILABLE
API를 일시적으로 사용할 수 없었습니다.

중요한 흐름에 있는 경우 나중에 다시 시도하도록 플레이어에게 요청하세요.
INVALID_PARAMS
잘못된 매개변수로 API가 호출되었습니다.
SIZE_LIMIT_EXCEEDED
크기 제한을 초과하는 매개변수로 API가 호출되었습니다.
UNKNOWN
오류 유형을 알 수 없습니다.

변수

Const IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean
게임이 게임 룸 환경 내에서 실행되고 있는지 여부입니다. 이를 사용하여 게임 룸 내에서만 사용할 수 있는 기능을 사용 설정할지 아니면 사용 중지할지 결정할 수 있습니다. 이 검사를 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 게임 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

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

광고와 관련된 함수 및 속성입니다.
함수
requestInterstitialAd
전면 광고를 표시하도록 요청합니다.
requestRewardedAd
특정 보상 유형에 대해 보상형 광고를 표시하도록 요청합니다.

함수

requestInterstitialAd

requestInterstitialAd(): Promise<void>
Experimental 전면 광고를 표시하도록 요청합니다.

🧪 공개 미리보기 API: 사전 통지 없이 변경될 수 있습니다.

광고가 표시되었는지 여부에 관해 보장하지 않습니다. 이 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> 성공한 요청에 대해 결정되고 실패한 요청에 대해 거부되거나 예외가 발생하는 프로미스

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>
Experimental 특정 보상 유형에 대해 보상형 광고를 표시하도록 요청합니다.

🧪 공개 미리보기 API: 사전 통지 없이 변경될 수 있습니다.

광고가 표시되었는지 여부를 보장하지 않습니다.
예
try {
  const isRewardEarned = await ytgame.ads.requestRewardedAd("21403813-2e22-4316-a8b2-7d4f52a6f6fb");
  // Handle reward being earned or not.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}
매개변수
rewardId: string 필수 항목입니다. 청구 가능한 리워드 유형을 고유하게 식별하는 식별자입니다. 각 보상 유형에 고유 ID를 사용하고 특정 보상 유형이 제공될 때마다 동일한 ID를 다시 사용해야 합니다. 예:
  • 21403813-2e22-4316-a8b2-7d4f52a6f6fb - '100코인'
  • 7defcfa2-4312-4893-a13a-a84e0c47a4df - '3 lives'
  • 121b001a-0c25-4289-88f6-58e3620d938f - '레벨 건너뛰기'
반환 값
Promise<boolean> 사용자가 보상을 받을 조건을 충족한 경우 true, 그렇지 않은 경우 false 값을 사용하여 요청이 성공적으로 처리될 때 처리되는 프로미스입니다. 프로미스는 요청이 실패하면 거부되거나 예외를 발생시킵니다.

ytgame.engagement

플레이어 참여와 관련된 함수 및 속성입니다.
인터페이스
Score
게임에서 YouTube로 전송하는 점수 객체입니다.
함수
sendScore
YouTube로 점수를 전송합니다.

함수

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로 거부/발생되는 프로미스입니다.

ytgame.engagement.Score

게임에서 YouTube로 전송하는 점수 객체입니다.
속성
value
정수로 표현된 점수 값입니다.

속성

value

value: number
정수로 표현된 점수 값입니다. 점수는 최대 안전 정수 이하여야 합니다. 그렇지 않으면 점수가 거부됩니다.

ytgame.game

일반 게임 동작과 관련된 함수 및 속성입니다.
함수
firstFrameReady
게임에서 프레임 표시를 시작했음을 YouTube에 알립니다.
gameReady
플레이어가 상호작용할 준비가 된 게임임을 YouTube에 알립니다.
loadData
직렬화된 문자열 형식으로 YouTube에서 게임 데이터를 로드합니다.
saveData
게임 데이터를 직렬화된 문자열 형식으로 YouTube에 저장합니다.

함수

firstFrameReady

firstFrameReady(): void
게임에서 프레임 표시를 시작했음을 YouTube에 알립니다.

게임에서 이 API를 호출해야 합니다(MUST). 그렇지 않으면 게임이 사용자에게 표시되지 않습니다. firstFrameReady()는 gameReady() 전에 호출해야 합니다(MUST).
예
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
플레이어가 상호작용할 준비가 되었음을 YouTube에 알립니다.

게임은 상호작용이 가능할 때 이 API를 호출해야 합니다. 로드 화면이 아직 표시되는 동안에는 게임에서 이 API를 호출해서는 안 됩니다(MUST NOT). 그렇지 않으면 게임이 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로 거부되는 프로미스

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 설정에서 게임 오디오가 사용 설정되어 있는지 여부를 반환합니다.

게임은 이를 사용하여 게임 오디오 상태를 초기화해야 합니다(SHOULD).
예
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) 일반적으로 사용되지 않는 콜백을 설정 해제하는 함수