YouTube 게임 룸 SDK 참조

ytgame

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

이는 현재 창의 전역 범위 변수입니다. 이 변수를 재정의하면 안 됩니다(MUST NOT).
네임스페이스
ads
광고와 관련된 함수 및 속성입니다.
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 Playables SDK 버전입니다.
예
// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

Error을 확장합니다.
YouTube 게임 룸 SDK에서 발생하는 오류 객체입니다.

SdkError 객체는 Error의 하위 요소이며 추가 필드를 포함합니다.
생성자
constructor
속성
errorType
오류 유형입니다.
message
name
stack?

속성

errorType

errorType: SdkErrorType
오류 유형입니다.

ytgame.ads

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

함수

requestInterstitialAd

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

광고가 표시되었는지 여부는 보장하지 않습니다. 이 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>
특정 리워드 유형에 대해 보상형 광고를 표시하도록 요청합니다.

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

ytgame.engagement

플레이어 참여와 관련된 함수 및 속성입니다.
열거
ContentType
가능한 콘텐츠 유형입니다.
인터페이스
Content
게임에서 YouTube로 전송하는 콘텐츠 객체입니다.
Score
게임에서 YouTube로 전송하는 점수 객체입니다.
함수
openYTContent
제공된 콘텐츠 ID에 해당하는 콘텐츠를 열도록 YouTube에 요청합니다.
sendScore
YouTube로 점수를 전송합니다.

열거

Const ContentType

ContentType
가능한 콘텐츠 유형입니다.
열거형 멤버
PLAYABLE
YouTube 게임 룸입니다.
VIDEO
YouTube 동영상입니다.

함수

openYTContent

openYTContent(content: Content): Promise<void>
제공된 콘텐츠 ID에 해당하는 콘텐츠를 열도록 YouTube에 요청합니다.

일반적으로 이 요청은 웹에서 새 탭으로 콘텐츠를 엽니다. 휴대기기에서는 동영상이 소형 플레이어에서 열리고 게임 룸이 현재 열려 있는 게임 룸을 대체합니다.
예
// Open a video.
async function showVideo(videoID: string) {
  try {
    await ytgame.engagement.openYTContent({
      id: videoID,
      contentType: ytgame.engagement.ContentType.VIDEO,
    });
    // Request successful, content may have opened.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

// Open a Playable.
async function openDifferentPlayable(playableID: string) {
  try {
    await ytgame.engagement.openYTContent({
      id: playableID,
      contentType: ytgame.engagement.ContentType.PLAYABLE,
    });
    // Request successful, content may have opened.
    // On mobile, the new Playable will replace the current one.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}
매개변수
content: Content YouTube에서 열 콘텐츠
반환 값
Promise<void> 성공하면 결정되고 실패하면 ytgame.SdkError로 거부/발생되는 프로미스

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.Content

게임에서 YouTube로 전송하는 콘텐츠 객체입니다.
속성
contentType?
열 콘텐츠의 유형입니다.
id
열려는 콘텐츠의 ID입니다.

속성

Optional contentType

contentType?: ContentType
열 콘텐츠의 유형입니다. 제공해야 하지만 제공하지 않으면 VIDEO이 가정됩니다.

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). 그렇지 않으면 게임이 사용자에게 표시되지 않습니다. 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) 일반적으로 사용되지 않는 콜백을 설정 해제하는 함수