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 Chơi game trên YouTube.

Đây là một biến có phạm vi toàn cầu 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 CẦN 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 tình trạng của trò chơi.
`system`	Các hàm và thuộc tính liên quan đến hệ thống YouTube.

Bảng liệt kê
`SdkErrorType`	Các loại lỗi mà SDK Chơi game trên YouTube đưa ra.

Lớp
`SdkError`	Đối tượng lỗi mà SDK Chơi game trên YouTube gửi.

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

Xem thêm

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

Bảng liệt kê

`Const` SdkErrorType

SdkErrorType

Các loại lỗi mà SDK Chơi game trên YouTube đưa ra.

Thành viên liệt kê
`API_UNAVAILABLE`	API tạm thời không hoạt động. Yêu cầu người chơi thử lại vào lúc khác nếu họ đang trong một quy trình 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 Chơi game hay không. Bạn có thể dùng thông tin này để xác định xem có nên bật hay tắt những tính năng chỉ có trong thẻ Chơi game hay không. Kết hợp bước kiểm tra này với bước kiểm tra ytgame để đảm bảo 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 Chơi game trên YouTube.

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 Chơi game trên YouTube tạo ra.

Đối tượng SdkError là đối tượng 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 TRƯỚC CÔNG KHAI: CÓ THỂ THAY ĐỔI MÀ KHÔNG CẦN 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ị một quảng cáo xen kẽ.
`requestRewardedAd`	Yêu cầu hiển thị quảng cáo có tặng thưởng cho một loại phần thưởng cụ thể.

Hàm

requestInterstitialAd

requestInterstitialAd(): Promise<void>

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

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

Không đảm bảo về việc quảng cáo có được hiển thị hay không. Không sử dụng API này để tặng thưởng cho người chơi khi họ xem quảng cáo.

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 khi yêu cầu thành công hoặc từ chối/gây ra lỗi khi yêu cầu không thành công.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Yêu cầu hiển thị quảng cáo có tặng thưởng cho một loại phần thưởng cụ thể.

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

Không đảm bảo về việc quảng cáo có được hiển thị hay không.

Ví dụ:

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

Thông số

Thông số
`rewardId: string`	Bắt buộc. Giá trị nhận dạng xác định duy nhất loại phần thưởng có thể nhận. Bạn phải sử dụng một mã nhận dạng duy nhất cho mỗi loại phần thưởng và sử dụng lại mã nhận dạng đó mỗi lần bạn cung cấp loại phần thưởng cụ thể đó. Ví dụ: 21403813-2e22-4316-a8b2-7d4f52a6f6fb – "100 xu" 7defcfa2-4312-4893-a13a-a84e0c47a4df – "3 mạng" 121b001a-0c25-4289-88f6-58e3620d938f – "Bỏ qua cấp độ"

rewardId: string

Bắt buộc. Giá trị nhận dạng xác định duy nhất loại phần thưởng có thể nhận. Bạn phải sử dụng một mã nhận dạng duy nhất cho mỗi loại phần thưởng và sử dụng lại mã nhận dạng đó mỗi lần bạn cung cấp loại phần thưởng cụ thể đó. Ví dụ:

21403813-2e22-4316-a8b2-7d4f52a6f6fb – "100 xu"
7defcfa2-4312-4893-a13a-a84e0c47a4df – "3 mạng"
121b001a-0c25-4289-88f6-58e3620d938f – "Bỏ qua cấp độ"

Giá trị trả về
`Promise<boolean>`	Một lời hứa phân giải khi yêu cầu thành công với giá trị true nếu người dùng đáp ứng các điều kiện để nhận phần thưởng hoặc false nếu họ không đáp ứng. Lệnh hứa từ chối/gây ra lỗi khi 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
`Score`	Đối tượng điểm số mà trò chơi gửi đến YouTube.

Hàm
`sendScore`	Gửi điểm số đến YouTube.

Hàm

sendScore

sendScore(score: Score): Promise<void>

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

Điểm số này 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 để đảm bảo tính nhất quán. Điểm số sẽ được sắp xếp và điểm cao nhất sẽ xuất hiện 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 cao trong trò chơi đều phải phù hợp với điểm số đượ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`	bản nhạc để gửi đến YouTube.

Giá trị trả về
`Promise<void>`	một Promise phân giải khi thành công và từ chối/gây ra lỗi với `ytgame.SdkError` khi không thành công.

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 số được biểu thị dưới dạng số nguyên.

Thuộc tính

value

value: number

Giá trị điểm số đượ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 biết rằng người chơi đã có thể tương tác với trò chơi.
`loadData`	Tải dữ liệu trò chơi từ YouTube dưới dạng một chuỗi được chuyển đổi tuần tự.
`saveData`	Lưu dữ liệu trò chơi vào YouTube dưới dạng một chuỗi được chuyển đổ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 PHẢI gọi API này. Nếu không, người dùng sẽ không thấy trò chơi. Bạn PHẢI gọi firstFrameReady() trước gameReady().

Ví dụ:

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

gameReady

gameReady(): void

Thông báo cho YouTube biết rằng người chơi đã có thể tương tác với trò chơi.

Trò chơi PHẢI 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 đang 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ưới dạng một chuỗi được chuyển đổ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 Promise hoàn thành 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ưới dạng một chuỗi được chuyển đổi tuần tự.

Chuỗi này phải là một chuỗi UTF-16 hợp lệ, có cấu trúc rõ ràng và tối đa 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 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 Promise 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 tình trạng của trò chơi.

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

Hàm

logError

logError(): void

Ghi lại lỗi vào YouTube.

Lưu ý: API này hoạt động hiệu quả nhất có thể và bị giới hạn về tốc độ, điều này có thể dẫn đến 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 hiệu quả nhất có thể và bị giới hạn về tốc độ, điều này có thể dẫn đến 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ề trạng thái bật hay tắt âm thanh trò chơi trong phần cài đặt YouTube.
`onAudioEnabledChange`	Đặt một lệnh gọi lại sẽ đượ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 một lệnh gọi lại sẽ được kích hoạt khi một sự kiện tạm dừng trò chơi được kích hoạt từ YouTube.
`onResume`	Đặt một lệnh gọi lại sẽ được kích hoạt khi một 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 dùng các hàm khác để xác định ngôn ngữ hoặc ngôn ngữ địa phương của người dùng, hoặc lưu trữ lựa chọn ưu tiên 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 Promise hoàn thành khi nhận được ngôn ngữ thành công và từ chối bằng một `ytgame.SdkError` khi không thành công.

isAudioEnabled

isAudioEnabled(): boolean

Trả về trạng thái bật/tắt âm thanh trò chơi trong phần cài đặt YouTube.

Trò chơi NÊN dùng trạng thái 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 giá trị boolean cho biết liệu âm thanh có được bật hay không.

onAudioEnabledChange

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

Đặt một lệnh gọi lại sẽ được 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 PHẢI 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ỷ đặt lệnh gọi lại thường không được dùng.

onPause

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

Đặt một lệnh gọi lại sẽ được kích hoạt khi một 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, kể cả khi người dùng thoát 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ỷ đặt lệnh gọi lại thường không được dùng.

onResume

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

Đặt một lệnh gọi lại sẽ được kích hoạt khi một 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ỷ đặt lệnh gọi lại thường không được 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

Bảng 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

requestRewardedAd

ytgame.engagement

Hàm

sendScore

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