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

ytgame

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

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

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

ytgame.engagement

הפונקציות והמאפיינים שקשורים למעורבות של השחקנים.
ערכי ספירה
ContentType
סוגי התוכן האפשריים.
ממשקים
Content
אובייקט התוכן שהמשחק שולח ל-YouTube.
Score
אובייקט הניקוד שהמשחק שולח ל-YouTube.
פונקציות
openYTContent
בקשות מ-YouTube לפתוח תוכן שתואם למזהה התוכן שצוין.
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.

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

מאפיינים

Optional contentType

contentType?: ContentType
סוג התוכן שרוצים לפתוח. מומלץ לספק את הערך, אבל אם לא מספקים אותו, המערכת מניחה שהערך הוא VIDEO.

id

id: string
המזהה של התוכן שרוצים לפתוח.

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

אחרי שהמשחק מושהה, אין ערובה שהוא ימשיך.
דוגמה
ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}
פרמטרים
callback: (() => void) פונקציית הקריאה החוזרת שתופעל.
החזרות
(() => void) פונקציה לביטול ההגדרה של הקריאה החוזרת, שבדרך כלל לא נמצאת בשימוש.