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

ytgame

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

ตัวแปรนี้มีขอบเขตทั่วโลก ในหน้าต่างปัจจุบัน คุณต้องไม่ลบล้างตัวแปรนี้
เนมสเปซ
ads
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับโฆษณา
engagement
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับการมีส่วนร่วมของผู้เล่น
game
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับลักษณะการทำงานของเกมทั่วไป
health
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับสถานะของเกม
system
ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับระบบ YouTube
การแจงนับ
SdkErrorType
ประเภทข้อผิดพลาดที่ YouTube Playables SDK แสดง
คลาส
SdkError
ออบเจ็กต์ข้อผิดพลาดที่ SDK ฟีเจอร์เล่นเกมของ YouTube แสดง
ตัวแปร
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

ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับโฆษณา
ฟังก์ชัน
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> Promise ที่จะทำงานเมื่อคำขอสำเร็จ หรือปฏิเสธ/ส่งข้อผิดพลาดเมื่อคำขอไม่สำเร็จ

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 ต้องระบุ ตัวระบุที่ระบุประเภทรางวัลที่อ้างสิทธิ์ได้แบบไม่ซ้ำ คุณต้องใช้รหัสที่ไม่ซ้ำกันสำหรับรางวัลแต่ละประเภท และใช้รหัสเดิมซ้ำทุกครั้งที่เสนอรางวัลประเภทนั้นๆ เช่น คุณอาจทำให้รหัส อ่านได้หรือเป็น UUID คุณสามารถรวมรหัสนี้เป็นรหัสที่ฮาร์ดโค้ดไว้ในโค้ดเกม สำหรับรางวัลที่เฉพาะเจาะจง ข้อกำหนดเดียวของเราคือคุณต้องระบุรหัสและ รหัสดังกล่าวต้องไม่มีข้อมูลผู้ใช้ เช่น
  • 100-coins-reward-12 - "100 เหรียญ"
  • 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives"
  • 121b001a-0c25-4289-88f6-58e3620d938f - "ข้ามระดับ"
การคืนสินค้า
Promise<boolean> Promise ที่จะเปลี่ยนเป็นค่าจริงเมื่อคำขอสำเร็จ หากผู้ใช้ มีคุณสมบัติตรงตามเงื่อนไขในการรับรางวัล หรือเป็นค่าเท็จหากผู้ใช้ไม่มีคุณสมบัติตรงตามเงื่อนไข Promise จะปฏิเสธ/ส่งข้อผิดพลาดเมื่อคำขอไม่สำเร็จ

ytgame.engagement

ฟังก์ชันและพร็อพเพอร์ตี้ที่เกี่ยวข้องกับการมีส่วนร่วมของผู้เล่น
การแจงนับ
ContentType
ประเภทเนื้อหาที่เป็นไปได้
อินเทอร์เฟซ
Content
ออบเจ็กต์เนื้อหาที่เกมส่งไปยัง YouTube
Score
ออบเจ็กต์คะแนนที่เกมส่งไปยัง YouTube
ฟังก์ชัน
openYTContent
ขอให้ YouTube เปิดเนื้อหาที่สอดคล้องกับ Content ID ที่ระบุ
sendScore
ส่งคะแนนไปยัง YouTube

การแจงนับ

Const ContentType

ContentType
ประเภทเนื้อหาที่เป็นไปได้
สมาชิกการแจงนับ
PLAYABLE
เกมที่เล่นในฟีเจอร์เล่นเกมของ YouTube
VIDEO
วิดีโอ YouTube

ฟังก์ชัน

openYTContent

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

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

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

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

Optional contentType

contentType?: ContentType
ประเภทเนื้อหาที่จะเปิด ควรระบุ แต่หากไม่ได้ระบุ ระบบจะถือว่าเป็น VIDEO

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 ทราบว่าเกมเริ่มแสดงเฟรมแล้ว

เกมต้องเรียกใช้ 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) ฟังก์ชันเพื่อยกเลิกการตั้งค่าฟังก์ชันเรียกกลับที่มักไม่ได้ใช้