Trang này được dịch bởi Cloud Translation API.

Tài liệu tham khảo về SDK Chơi game trên YouTube

ytgame

Không gian tên cấp cao nhất cho SDK YouTube Playables.

Đây là một biến có phạm vi toàn cục trong cửa sổ hiện tại. Bạn KHÔNG ĐƯỢC ghi đè biến này.

Không gian tên
`ads`	🧪 API XEM TRƯỚC CÔNG KHAI: CÓ THỂ THAY ĐỔI MÀ KHÔNG THÔNG BÁO TRƯỚC.
`engagement`	Các hàm và thuộc tính liên quan đến mức độ tương tác của người chơi.
`game`	Các hàm và thuộc tính liên quan đến hành vi chung của trò chơi.
`health`	Các hàm và thuộc tính liên quan đến trạng thái của trò chơi.
`system`	Các hàm và thuộc tính liên quan đến hệ thống YouTube.

Liệt kê
`SdkErrorType`	Các loại lỗi mà SDK YouTube Playables gửi.

Lớp
`SdkError`	Đối tượng lỗi mà SDK YouTube Playables gửi.

Biến
`IN_PLAYABLES_ENV`	Trò chơi có đang chạy trong môi trường Playables hay không.
`SDK_VERSION`	Phiên bản SDK YouTube Playables.

Xem thêm

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

Liệt kê

`Const` SdkErrorType

SdkErrorType

Các loại lỗi mà SDK YouTube Playables gửi.

Thành phần liệt kê
`API_UNAVAILABLE`	API tạm thời không hoạt động. Hãy yêu cầu người chơi thử lại vào lúc khác nếu họ đang ở trong một luồng quan trọng.
`INVALID_PARAMS`	API được gọi bằng các tham số không hợp lệ.
`SIZE_LIMIT_EXCEEDED`	API được gọi bằng các tham số vượt quá giới hạn kích thước.
`UNKNOWN`	Không xác định được loại lỗi.

Biến

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

Trò chơi có đang chạy trong môi trường Playables hay không. Bạn có thể sử dụng thông tin này để xác định xem có bật hay tắt các tính năng chỉ có trong nội dung có thể chơi hay không. Kết hợp việc kiểm tra này với việc kiểm tra ytgame để đảm bảo rằng SDK thực sự được tải.

Ví dụ:

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

Phiên bản SDK YouTube Playables.

Ví dụ:

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

ytgame.SdkError

Mở rộng Error

Đối tượng lỗi mà SDK YouTube Playables gửi.

Đối tượng SdkError là một phần tử con của Error và chứa một trường bổ sung.

Hàm khởi tạo
`constructor`

Thuộc tính
`errorType`	Loại lỗi.
`message`
`name`
`stack?`

Thuộc tính

errorType

errorType:
                  SdkErrorType

Loại lỗi.

ytgame.ads

🧪 API XEM XÉT CÔNG KHAI: CÓ THỂ THAY ĐỔI MÀ KHÔNG THÔNG BÁO TRƯỚC.

Các hàm và thuộc tính liên quan đến quảng cáo.

Hàm
`requestInterstitialAd`	Yêu cầu hiển thị quảng cáo xen kẽ.

Hàm

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Yêu cầu hiển thị quảng cáo xen kẽ.

API XEM TRƯỚC CÔNG CỘNG: CÓ THỂ THAY ĐỔI MÀ KHÔNG THÔNG BÁO.

Không đảm bảo rằng quảng cáo có hiển thị hay không.

Ví dụ:

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

Giá trị trả về
`Promise<void>`	một lời hứa sẽ phân giải trên một yêu cầu thành công hoặc từ chối/ném trên một yêu cầu không thành công.

ytgame.engagement

Các hàm và thuộc tính liên quan đến mức độ tương tác của người chơi.

Giao diện
`Content`	Đối tượng nội dung mà trò chơi gửi đến YouTube.
`Score`	Đối tượng điểm số mà trò chơi gửi đến YouTube.

Hàm
`openYTContent`	Yêu cầu YouTube mở nội dung tương ứng với mã video được cung cấp.
`sendScore`	Gửi điểm đến YouTube.

Hàm

openYTContent

openYTContent(content: Content): Promise<void>

Yêu cầu YouTube mở nội dung tương ứng với mã video được cung cấp.

Nhìn chung, thao tác này sẽ mở video trong một thẻ mới trên web và trong trình phát mini trên thiết bị di động.

Ví dụ:

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

Thông số
`content: Content`	nội dung cần mở trên YouTube.

Giá trị trả về
`Promise<void>`	một Lời hứa sẽ phân giải khi thành công và từ chối/gửi bằng một `ytgame.SdkError` khi không thành công.

sendScore

sendScore(score: Score): Promise<void>

Gửi điểm số đến YouTube.

Điểm số phải thể hiện một khía cạnh của tiến trình trong trò chơi. Nếu có nhiều phương diện, nhà phát triển phải chọn một phương diện nhất quán. Điểm số sẽ được sắp xếp và điểm số cao nhất sẽ hiển thị trong giao diện người dùng của YouTube. Vì vậy, mọi giao diện người dùng điểm số cao trong trò chơi phải phù hợp với nội dung đang được gửi qua API này.

Ví dụ:

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

Thông số
`score: Score`	điểm số cần gửi đến YouTube.

Giá trị trả về
`Promise<void>`	một Lời hứa sẽ phân giải khi thành công và từ chối/gửi bằng một `ytgame.SdkError` khi không thành công.

ytgame.engagement.Content

Đối tượng nội dung mà trò chơi gửi đến YouTube.

Thuộc tính
`id`	Mã nhận dạng của video mà chúng ta muốn mở.

Thuộc tính

id

id: string

Mã nhận dạng của video mà chúng ta muốn mở.

ytgame.engagement.Score

Đối tượng điểm số mà trò chơi gửi đến YouTube.

Thuộc tính
`value`	Giá trị điểm được biểu thị dưới dạng số nguyên.

Thuộc tính

value

value: number

Giá trị điểm được biểu thị dưới dạng số nguyên. Điểm số phải nhỏ hơn hoặc bằng số nguyên an toàn tối đa. Nếu không, điểm số sẽ bị từ chối.

ytgame.game

Các hàm và thuộc tính liên quan đến hành vi chung của trò chơi.

Hàm
`firstFrameReady`	Thông báo cho YouTube rằng trò chơi đã bắt đầu hiển thị khung hình.
`gameReady`	Thông báo cho YouTube rằng trò chơi đã sẵn sàng để người chơi tương tác.
`loadData`	Tải dữ liệu trò chơi từ YouTube ở dạng chuỗi tuần tự.
`saveData`	Lưu dữ liệu trò chơi vào YouTube ở dạng chuỗi tuần tự.

Hàm

firstFrameReady

firstFrameReady(): void

Thông báo cho YouTube rằng trò chơi đã bắt đầu hiển thị khung hình.

Trò chơi MUST gọi API này. Nếu không, người dùng sẽ không thấy trò chơi. firstFrameReady() MUST được gọi trước gameReady().

Ví dụ:

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

gameReady

gameReady(): void

Thông báo cho YouTube rằng trò chơi đã sẵn sàng để người chơi tương tác.

Trò chơi MUST gọi API này khi có thể tương tác. Trò chơi KHÔNG ĐƯỢC gọi API này khi màn hình tải vẫn hiển thị. Nếu không, trò chơi sẽ không vượt qua được quy trình chứng nhận của YouTube.

Ví dụ:

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

loadData

loadData(): Promise<string>

Tải dữ liệu trò chơi từ YouTube ở dạng chuỗi tuần tự.

Trò chơi phải xử lý mọi hoạt động phân tích cú pháp giữa chuỗi và định dạng nội bộ.

Ví dụ:

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

Giá trị trả về
`Promise<string>`	một Lời hứa hoàn tất khi tải thành công và từ chối bằng một `ytgame.SdkError` khi không thành công.

saveData

saveData(data: string): Promise<void>

Lưu dữ liệu trò chơi vào YouTube ở dạng chuỗi tuần tự.

Chuỗi phải là chuỗi UTF-16 hợp lệ, được định dạng đúng cách và có kích thước tối đa là 3 MiB. Trò chơi phải xử lý mọi hoạt động phân tích cú pháp giữa chuỗi và một định dạng nội bộ. Nếu cần, hãy sử dụng String.isWellFormed() để kiểm tra xem chuỗi có được định dạng đúng cách hay không.

Ví dụ:

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

Thông số
`data: string`

Giá trị trả về
`Promise<void>`	một Lời hứa sẽ phân giải khi lưu thành công và từ chối bằng một `ytgame.SdkError` khi không thành công.

ytgame.health

Các hàm và thuộc tính liên quan đến trạng thái của trò chơi.

Hàm
`logError`	Ghi lại lỗi vào YouTube.
`logWarning`	Ghi lại cảnh báo cho YouTube.

Hàm

logError

logError(): void

Ghi lỗi vào YouTube.

Lưu ý: API này hoạt động theo khả năng tốt nhất và có giới hạn tốc độ, điều này có thể dẫn đến việc mất dữ liệu.

Ví dụ:

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

logWarning

logWarning(): void

Ghi lại cảnh báo cho YouTube.

Lưu ý: API này hoạt động theo khả năng tốt nhất và có giới hạn tốc độ, điều này có thể dẫn đến việc mất dữ liệu.

Ví dụ:

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

ytgame.system

Các hàm và thuộc tính liên quan đến hệ thống YouTube.

Hàm
`getLanguage`	Trả về ngôn ngữ được đặt trong phần cài đặt YouTube của người dùng dưới dạng thẻ ngôn ngữ BCP-47.
`isAudioEnabled`	Trả về thông tin về việc âm thanh trò chơi có được bật trong phần cài đặt của YouTube hay không.
`onAudioEnabledChange`	Đặt lệnh gọi lại được kích hoạt khi sự kiện thay đổi chế độ cài đặt âm thanh được kích hoạt từ YouTube.
`onPause`	Đặt lệnh gọi lại để kích hoạt khi sự kiện tạm dừng trò chơi được kích hoạt từ YouTube.
`onResume`	Đặt lệnh gọi lại để kích hoạt khi sự kiện tiếp tục trò chơi được kích hoạt từ YouTube.

Hàm

getLanguage

getLanguage(): Promise<string>

Trả về ngôn ngữ được đặt trong phần cài đặt YouTube của người dùng dưới dạng thẻ ngôn ngữ BCP-47.

Không sử dụng các hàm khác để xác định ngôn ngữ hoặc ngôn ngữ của người dùng, hoặc lưu lựa chọn ưu tiên về ngôn ngữ của họ trong tính năng lưu vào đám mây. Thay vào đó, hãy sử dụng hàm này để đảm bảo trải nghiệm người dùng nhất quán trên YouTube.

Ví dụ:

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

Giá trị trả về
`Promise<string>`	một Lời hứa hoàn tất khi nhận được ngôn ngữ thành công và từ chối bằng `ytgame.SdkError` khi không thành công.

isAudioEnabled

isAudioEnabled(): boolean

Trả về thông tin về việc âm thanh trò chơi có được bật trong phần cài đặt của YouTube hay không.

Trò chơi NÊN sử dụng thông tin này để khởi chạy trạng thái âm thanh trò chơi.

Ví dụ:

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

Giá trị trả về
`boolean`	một boolean cho biết liệu âm thanh có được bật hay không.

onAudioEnabledChange

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

Đặt lệnh gọi lại để kích hoạt khi sự kiện thay đổi chế độ cài đặt âm thanh được kích hoạt từ YouTube.

Trò chơi MUST sử dụng API này để cập nhật trạng thái âm thanh của trò chơi.

Ví dụ:

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

Thông số
`callback: ((isAudioEnabled: boolean) => void)`	hàm callback sẽ được kích hoạt.

Giá trị trả về
`(() => void)`	một hàm để huỷ thiết lập lệnh gọi lại thường không được sử dụng.

onPause

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

Đặt lệnh gọi lại để kích hoạt khi sự kiện tạm dừng trò chơi được kích hoạt từ YouTube. Trò chơi có một khoảng thời gian ngắn để lưu mọi trạng thái trước khi bị loại bỏ.

onPause được gọi cho tất cả các loại tạm dừng, bao gồm cả khi người dùng thoát khỏi trò chơi. Không có gì đảm bảo rằng trò chơi sẽ tiếp tục.

Ví dụ:

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

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

Thông số
`callback: (() => void)`	hàm callback sẽ được kích hoạt.

Giá trị trả về
`(() => void)`	một hàm để huỷ thiết lập lệnh gọi lại thường không được sử dụng.

onResume

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

Đặt lệnh gọi lại để kích hoạt khi sự kiện tiếp tục trò chơi được kích hoạt từ YouTube.

Sau khi bị tạm dừng, trò chơi không được đảm bảo sẽ tiếp tục.

Ví dụ:

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

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

Thông số
`callback: (() => void)`	hàm callback sẽ được kích hoạt.

Giá trị trả về
`(() => void)`	một hàm để huỷ thiết lập lệnh gọi lại thường không được sử dụng.

Tài liệu tham khảo về SDK Chơi game trên YouTube Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

ytgame

Liệt kê

Const SdkErrorType

Biến

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Thuộc tính

errorType

ytgame.ads

Hàm

requestInterstitialAd

ytgame.engagement

Hàm

openYTContent

sendScore

ytgame.engagement.Content

Thuộc tính

id

ytgame.engagement.Score

Thuộc tính

value

ytgame.game

Hàm

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Hàm

logError

logWarning

ytgame.system

Hàm

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Tài liệu tham khảo về SDK Chơi game trên YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION