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

ytgame

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

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

การแจงนับ

Const SdkErrorType

SdkErrorType
ประเภทข้อผิดพลาดที่ YouTube Playables 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
เวอร์ชัน 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

🧪 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 ต้องระบุ ตัวระบุที่ระบุประเภทรางวัลที่อ้างสิทธิ์ได้แบบไม่ซ้ำ คุณต้องใช้รหัสที่ไม่ซ้ำกันสำหรับรางวัลแต่ละประเภท และใช้รหัสเดิมซ้ำทุกครั้งที่เสนอรางวัลประเภทนั้น เช่น
  • 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 coins"
  • 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives"
  • 121b001a-0c25-4289-88f6-58e3620d938f - "ข้ามระดับ"
การคืนสินค้า
Promise<boolean> Promise ที่จะเปลี่ยนเป็นค่าจริง (true) เมื่อคำขอสำเร็จหากผู้ใช้ มีคุณสมบัติตรงตามเงื่อนไขในการรับรางวัล หรือเป็นเท็จ (false) หากไม่มีคุณสมบัติตรงตามเงื่อนไข Promise ปฏิเสธ/ส่งข้อผิดพลาดเมื่อคำขอไม่สำเร็จ

ytgame.engagement

ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับการมีส่วนร่วมของผู้เล่น
อินเทอร์เฟซ
Score
ออบเจ็กต์คะแนนที่เกมส่งไปยัง YouTube
ฟังก์ชัน
sendScore
ส่งคะแนนไปยัง YouTube

ฟังก์ชัน

sendScore

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

คะแนนควรแสดงมิติเดียวของ ความคืบหน้าภายในเกม หากมีหลายมิติข้อมูล นักพัฒนาแอปต้องเลือกมิติข้อมูล 1 รายการเพื่อให้สอดคล้องกัน ระบบจะจัดเรียงคะแนนและแสดงคะแนนสูงสุด ใน 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.Score

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

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

value

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

ytgame.game

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

ฟังก์ชัน

firstFrameReady

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

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

gameReady

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

เกมต้องเรียกใช้ 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

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

onPause

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

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

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

onResume

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

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

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