ข้อมูลอ้างอิง SDK ฟีเจอร์เล่นเกมของ YouTube

ytgame

เนมสเปซระดับบนสุดสําหรับ YouTube Playables SDK

นี่คือตัวแปรที่มีขอบเขตทั่วโลกในหน้าต่างปัจจุบัน คุณต้องไม่ลบล้างตัวแปรนี้
เนมสเปซ
ads
🧪 เวอร์ชันตัวอย่างแบบสาธารณะของ API: อาจมีการเปลี่ยนแปลงโดยไม่แจ้งให้ทราบ
engagement
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับการมีส่วนร่วมของผู้เล่น
game
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับลักษณะการทํางานทั่วไปของเกม
health
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับประสิทธิภาพของเกม
system
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับระบบ YouTube
การแจงนับ
SdkErrorType
ประเภทข้อผิดพลาดที่ SDK ฟีเจอร์เล่นเกมของ YouTube แสดง
ชั้นเรียน
SdkError
ออบเจ็กต์ข้อผิดพลาดที่ SDK ฟีเจอร์เล่นเกมของ YouTube แสดง
ตัวแปร
IN_PLAYABLES_ENV
เกมทำงานในสภาพแวดล้อมฟีเจอร์เล่นเกมหรือไม่
SDK_VERSION
เวอร์ชัน SDK ของฟีเจอร์เล่นเกมของ YouTube
ดูเพิ่มเติม

การแจงนับ

Const SdkErrorType

SdkErrorType
ประเภทข้อผิดพลาดที่ SDK ฟีเจอร์เล่นเกมของ YouTube แสดง
สมาชิกการแจงนับ
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
เวอร์ชัน SDK ของฟีเจอร์เล่นเกมของ YouTube
ตัวอย่าง
// 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: SUBJECT TO CHANGE WITHOUT NOTICE.

ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับโฆษณา
ฟังก์ชัน
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
ขอให้ YouTube เปิดเนื้อหาที่เกี่ยวข้องกับรหัสวิดีโอที่ระบุ
sendScore
ส่งคะแนนไปยัง YouTube

ฟังก์ชัน

openYTContent

openYTContent(content: Content): Promise<void>
ขอให้ 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> Promise ที่แก้ไขเมื่อดำเนินการสำเร็จและปฏิเสธ/แสดงข้อผิดพลาดด้วย ytgame.SdkError เมื่อดำเนินการไม่สำเร็จ

sendScore

sendScore(score: Score): Promise<void>
ส่งคะแนนไปยัง YouTube

คะแนนควรแสดงมิติข้อมูลของความก้าวหน้าในเกม หากมีหลายมิติข้อมูล นักพัฒนาแอปต้องเลือกมิติข้อมูลเดียวเพื่อให้สอดคล้องกัน ระบบจะจัดเรียงคะแนนและแสดงคะแนนสูงสุดใน UI ของ YouTube ดังนั้น 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> Promise ที่แก้ไขเมื่อดำเนินการสำเร็จและปฏิเสธ/แสดงข้อผิดพลาดด้วย ytgame.SdkError เมื่อดำเนินการไม่สำเร็จ

ytgame.engagement.Content

ออบเจ็กต์เนื้อหาที่เกมส่งไปยัง YouTube
พร็อพเพอร์ตี้
id
รหัสของวิดีโอที่ต้องการเปิด

พร็อพเพอร์ตี้

id

id: string
รหัสของวิดีโอที่ต้องการเปิด

ytgame.engagement.Score

ออบเจ็กต์คะแนนที่เกมส่งไปยัง YouTube
พร็อพเพอร์ตี้
value
ค่าคะแนนที่แสดงเป็นจำนวนเต็ม

พร็อพเพอร์ตี้

value

value: number
ค่าคะแนนที่แสดงเป็นจำนวนเต็ม คะแนนต้องน้อยกว่าหรือเท่ากับจำนวนเต็มที่ปลอดภัยสูงสุด มิฉะนั้นระบบจะปฏิเสธคะแนน

ytgame.game

ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับลักษณะการทํางานทั่วไปของเกม
ฟังก์ชัน
firstFrameReady
แจ้งให้ YouTube ทราบว่าเกมเริ่มแสดงเฟรมแล้ว
gameReady
แจ้งให้ YouTube ทราบว่าเกมพร้อมให้ผู้เล่นโต้ตอบแล้ว
loadData
โหลดข้อมูลเกมจาก YouTube ในรูปแบบสตริงที่แปลงเป็นอนุกรม
saveData
บันทึกข้อมูลเกมลงใน YouTube ในรูปแบบสตริงที่แปลงเป็นรหัส

ฟังก์ชัน

firstFrameReady

firstFrameReady(): void
แจ้งให้ YouTube ทราบว่าเกมเริ่มแสดงเฟรมแล้ว

เกมMUSTเรียกใช้ API นี้ ไม่เช่นนั้น เกมจะไม่แสดงต่อผู้ใช้ firstFrameReady() MUSTเรียกใช้ก่อน gameReady()
ตัวอย่าง
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
แจ้งให้ YouTube ทราบว่าเกมพร้อมให้ผู้เล่นโต้ตอบ

เกมMUSTเรียกใช้ API นี้เมื่อโต้ตอบได้ เกมต้องไม่เรียกใช้ 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> Promise ที่เสร็จสมบูรณ์เมื่อโหลดสำเร็จและปฏิเสธด้วย ytgame.SdkError เมื่อโหลดไม่สำเร็จ

saveData

saveData(data: string): Promise<void>
บันทึกข้อมูลเกมลงใน YouTube ในรูปแบบสตริงที่แปลงเป็นอนุกรม

สตริงต้องเป็นสตริง UTF-16 ที่ถูกต้องและอยู่ในรูปแบบที่ถูกต้อง โดยมีขนาดไม่เกิน 3 MiB เกมต้องจัดการการแยกวิเคราะห์ระหว่างสตริงกับรูปแบบภายใน หากจำเป็น ให้ใช้ 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> Promise ที่แสดงผลเมื่อบันทึกสําเร็จและปฏิเสธด้วย 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> Promise ที่เสร็จสมบูรณ์เมื่อรับภาษาได้สําเร็จ และปฏิเสธด้วย ytgame.SdkError เมื่อไม่สําเร็จ

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

เกมMUSTใช้ API นี้เพื่ออัปเดตสถานะเสียงของเกม
ตัวอย่าง
ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});
พารามิเตอร์
callback: ((isAudioEnabled: boolean) => void) ฟังก์ชัน Callback จะทริกเกอร์
การคืนสินค้า
(() => void) ฟังก์ชันเพื่อยกเลิกการตั้งค่า Callback ซึ่งปกติแล้วจะไม่ได้ใช้

onPause

onPause(callback: (() => void)): (() => void)
ตั้งค่าการเรียกกลับให้ทริกเกอร์เมื่อเหตุการณ์หยุดเกมชั่วคราวเริ่มทํางานจาก YouTube เกมมีเวลาสั้นๆ ในการบันทึกสถานะก่อนที่จะถูกนำออก

onPause จะเรียกใช้สำหรับการหยุดชั่วคราวทุกประเภท รวมถึงเมื่อผู้ใช้ออกจากเกม เราไม่รับประกันว่าเกมจะกลับมาเล่นต่อได้
ตัวอย่าง
ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}
พารามิเตอร์
callback: (() => void) ฟังก์ชัน Callback จะทริกเกอร์
การคืนสินค้า
(() => void) ฟังก์ชันเพื่อยกเลิกการตั้งค่า Callback ซึ่งปกติแล้วจะไม่ได้ใช้

onResume

onResume(callback: (() => void)): (() => void)
ตั้งค่าการเรียกกลับให้ทริกเกอร์เมื่อมีการเรียกเหตุการณ์ "กลับมาเล่นต่อ" จาก YouTube

หลังจากหยุดชั่วคราวแล้ว เราไม่รับประกันว่าเกมจะกลับมาเล่นต่อ
ตัวอย่าง
ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}
พารามิเตอร์
callback: (() => void) ฟังก์ชัน Callback จะทริกเกอร์
การคืนสินค้า
(() => void) ฟังก์ชันเพื่อยกเลิกการตั้งค่า Callback ซึ่งปกติแล้วจะไม่ได้ใช้