דף זה תורגם על ידי Cloud Translation API.

מידע על SDK של המשחקייה ב-YouTube

ytgame

מרחב השמות ברמה העליונה של YouTube Playables SDK.

זהו משתנה ברמת ה-global בחלון הנוכחי. אסור לשנות את המשתנה הזה.

מרחבי שמות
`ads`	🧪 ממשק API בתצוגה מקדימה ציבורית: עשוי להשתנות ללא הודעה מראש.
`engagement`	הפונקציות והמאפיינים שקשורים למעורבות השחקנים.
`game`	הפונקציות והמאפיינים שקשורים להתנהגויות כלליות במשחק.
`health`	הפונקציות והמאפיינים שקשורים לבריאות המשחק.
`system`	הפונקציות והמאפיינים שקשורים למערכת של YouTube.

ערכים מספריים
`SdkErrorType`	סוגי השגיאות ש-YouTube Playables SDK גורם להן.

שיעורים
`SdkError`	אובייקט השגיאה ש-YouTube Playables SDK גורם להפעלה שלו.

משתנים
`IN_PLAYABLES_ENV`	האם המשחק פועל בסביבת Playables.
`SDK_VERSION`	גרסת ה-SDK של YouTube Playables.

ראה גם

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

ערכים מספריים

`Const` SdkErrorType

SdkErrorType

סוגי השגיאות ש-YouTube Playables SDK גורם להן.

חברי Enumeration
`API_UNAVAILABLE`	ה-API לא היה זמין באופן זמני. אם השחקנים נמצאים בתהליך קריטי, צריך לבקש מהם לנסות שוב מאוחר יותר.
`INVALID_PARAMS`	התבצעה קריאה ל-API עם פרמטרים לא חוקיים.
`SIZE_LIMIT_EXCEEDED`	ה-API הופעל עם פרמטרים שחורגים ממגבלת הגודל.
`UNKNOWN`	סוג השגיאה לא ידוע.

משתנים

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

האם המשחק פועל בסביבת Playables. תוכלו להשתמש בנתונים האלה כדי לקבוע אם להפעיל או להשבית תכונות שזמינות רק ב'משחקייה'. כדאי לשלב את הבדיקה הזו עם בדיקה של 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 Playables.

דוגמה

// 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`	בקשה להצגת מודעת מעברון.

פונקציות

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.

הציון צריך לייצג מימד אחד של התקדמות במשחק. אם יש כמה מאפיינים, המפתח צריך לבחור מאפיין אחד כדי לשמור על עקביות. התוצאות יסודרו והתוצאה הגבוהה ביותר תוצג בממשק המשתמש של YouTube, כך שממשק המשתמש של התוצאות הגבוהות במשחק צריך להיות תואם למה שנשלח דרך ה-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: number

ערך הציון שמוצג כמספר שלם. הציון חייב להיות קטן מ-maximum safe integer או שווה לו. אחרת, הציון יידחה.

ytgame.game

הפונקציות והמאפיינים שקשורים להתנהגויות כלליות במשחק.

פונקציות
`firstFrameReady`	שליחת הודעה ל-YouTube על כך שהמשחק התחיל להציג מסגרות.
`gameReady`	שליחת הודעה ל-YouTube על כך שהמשחק מוכן לשימוש של השחקנים.
`loadData`	טעינת נתוני משחקים מ-YouTube בצורת מחרוזת בסריאליזציה.
`saveData`	שמירת נתוני המשחק ב-YouTube כמחרוזת בסריאליזציה.

פונקציות

firstFrameReady

firstFrameReady(): void

שליחת הודעה ל-YouTube על כך שהמשחק התחיל להציג מסגרות.

MUST להפעיל את ה-API הזה במשחק. אחרת, המשחק לא יוצג למשתמשים. MUST לבצע קריאה ל-firstFrameReady() לפני 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 תקינה בפורמט תקין, בגודל של עד 3MB. המשחק חייב לטפל בכל ניתוח בין המחרוזת לבין פורמט פנימי. אם צריך, משתמשים ב-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`	הגדרת קריאה חוזרת (callback) שתופעל כשהאירוע של שינוי הגדרות האודיו יופעל מ-YouTube.
`onPause`	הגדרת פונקציית קריאה חוזרת (callback) שתופעל כשאירוע השהיה של משחק יופעל מ-YouTube.
`onResume`	הגדרת קריאה חוזרת (callback) שתופעל כשאירוע של המשך משחק יופעל מ-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)

הגדרת קריאה חוזרת (callback) שתופעל כשהאירוע של שינוי הגדרות האודיו יופעל מ-YouTube.

MUST להשתמש ב-API הזה במשחק כדי לעדכן את מצב האודיו במשחק.

דוגמה

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

פרמטרים
`callback: ((isAudioEnabled: boolean) => void)`	פונקציית הקריאה החוזרת שתופעל.

החזרות
`(() => void)`	פונקציה להסרת ההגדרה של פונקציית הקריאה החוזרת, שבדרך כלל לא בשימוש.

onPause

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

הגדרת פונקציית קריאה חוזרת (callback) שתופעל כשאירוע השהיה של משחק יופעל מ-YouTube. למשחק יש חלון קצר לשמירת המצב לפני שהוא יוסר.

onPause נקראת בכל סוגי ההשהיות, כולל כשהמשתמש יוצא מהמשחק. אין ערובה שהמשחק ימשיך.

דוגמה

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

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

פרמטרים
`callback: (() => void)`	פונקציית הקריאה החוזרת שתופעל.

החזרות
`(() => void)`	פונקציה להסרת ההגדרה של פונקציית הקריאה החוזרת, שבדרך כלל לא בשימוש.

onResume

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

הגדרת קריאה חוזרת (callback) שתופעל כשאירוע של המשך המשחק יופעל מ-YouTube.

לא בטוח שהמשחק ימשיך אחרי ההשהיה.

דוגמה

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

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

פרמטרים
`callback: (() => void)`	פונקציית הקריאה החוזרת שתופעל.

החזרות
`(() => void)`	פונקציה להסרת ההגדרה של פונקציית הקריאה החוזרת, שבדרך כלל לא בשימוש.

מידע על SDK של המשחקייה ב-YouTube קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

ytgame

ערכים מספריים

Const SdkErrorType

משתנים

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

מאפיינים

errorType

ytgame.ads

פונקציות

requestInterstitialAd

ytgame.engagement

פונקציות

openYTContent

sendScore

ytgame.engagement.Content

מאפיינים

id

ytgame.engagement.Score

מאפיינים

ערך

ytgame.game

פונקציות

firstFrameReady

gameReady

loadData

saveData

ytgame.health

פונקציות

logError

logWarning

ytgame.system

פונקציות

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

מידע על SDK של המשחקייה ב-YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION