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

ytgame

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

זהו משתנה עם היקף גלובלי בחלון הנוכחי. אסור לשנות את המשתנה הזה.

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

ערכי ספירה
`SdkErrorType`	סוגי השגיאות שמוחזרות על ידי ה-SDK של המשחקייה של YouTube.

שיעורים
`SdkError`	אובייקט השגיאה שה-SDK של המשחקייה של YouTube מחזיר.

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

ראה גם

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

ערכי ספירה

`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

אובייקט השגיאה שה-SDK של המשחקייה של YouTube מקפיץ.

האובייקט SdkError הוא צאצא של Error ומכיל שדה נוסף.

יצרנים
`constructor`

מאפיינים
`errorType`	סוג השגיאה.
`message`
`name`
`stack?`

מאפיינים

errorType

errorType:
                  SdkErrorType

סוג השגיאה.

ytgame.ads

‫🧪 API בגרסת Public Preview: עשויים לחול שינויים ללא הודעה מראש.

הפונקציות והמאפיינים שקשורים למודעות.

פונקציות
`requestInterstitialAd`	שולחת בקשה להצגת מודעת מעברון.
`requestRewardedAd`	שליחת בקשה להצגת מודעה מתגמלת עבור סוג תגמול מסוים.

פונקציות

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental שולח בקשה להצגת מודעת מעברון.

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

Makes no guarantees about whether the ad was shown. אסור להשתמש ב-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>

Experimental שליחת בקשה להצגת מודעה מתגמלת עבור סוג תגמול מסוים.

🧪 API בגרסת PUBLIC PREVIEW: עשוי להשתנות ללא הודעה מוקדמת.

אין הבטחה שהמודעה תוצג.

דוגמה

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 מטבעות" 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives" ‫121b001a-0c25-4289-88f6-58e3620d938f – 'דילוג על רמה'

rewardId: string

חובה. מזהה שמזהה באופן ייחודי את סוג התגמול שאפשר לקבל. לכל סוג תגמול צריך להיות מזהה ייחודי, וצריך להשתמש באותו מזהה בכל פעם שמוצע סוג התגמול הזה. למשל:

‫21403813-2e22-4316-a8b2-7d4f52a6f6fb – ‏"100 מטבעות"
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.

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

אובייקט הניקוד שהמשחק שולח ל-YouTube.

מאפיינים
`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 תקינה ומעוצבת היטב, והגודל שלה לא יכול להיות יותר מ-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 הזה הוא מסוג best-effort (מאמץ מרבי) ויש לו מגבלת קצב, ולכן עלול להתרחש אובדן נתונים.

דוגמה

function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void

מתעד אזהרה ב-YouTube.

הערה: ממשק ה-API הזה הוא מסוג best-effort (מאמץ מרבי) ומוגבל בקצב, ולכן עלול לגרום לאובדן נתונים.

דוגמה

function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

הפונקציות והמאפיינים שקשורים למערכת YouTube.

פונקציות
`getLanguage`	הפונקציה מחזירה את השפה שמוגדרת בהגדרות של המשתמש ב-YouTube, בתבנית של תג שפה לפי BCP-47.
`isAudioEnabled`	הפונקציה מחזירה את הערך true אם האודיו של המשחק מופעל בהגדרות YouTube, אחרת היא מחזירה את הערך false.
`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)`	פונקציית הקריאה החוזרת שתופעל.

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

onPause

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

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

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

דוגמה

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

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

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

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

onResume

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

הפונקציה מגדירה קריאה חוזרת להפעלה כשאירוע של המשך משחק מופעל מ-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

requestRewardedAd

ytgame.engagement

פונקציות

sendScore

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