مرجع حزمة تطوير البرامج (SDK) لميزة "هيّا نلعب" على YouTube

ytgame

مساحة الاسم ذات المستوى الأعلى لحزمة تطوير البرامج (SDK) لمنصة YouTube Playables.

هذا متغيّر على مستوى عالمي في النافذة الحالية. يجب عدم إلغاء هذا المتغيّر.
مساحات الاسم
ads
🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.
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
لم تكن واجهة برمجة التطبيقات متاحة مؤقتًا.

اطلب من اللاعبين إعادة المحاولة في وقت لاحق إذا كانوا في مسار مهم.
INVALID_PARAMS
تمّ استدعاء واجهة برمجة التطبيقات باستخدام مَعلمات غير صالحة.
SIZE_LIMIT_EXCEEDED
تمّ استدعاء واجهة برمجة التطبيقات باستخدام مَعلمات تتجاوز الحدّ الأقصى المسموح به للحجم.
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

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

The functions and properties related to ads.
الدوال
requestInterstitialAd
يطلب عرض إعلان بيني.

الدوال

requestInterstitialAd

requestInterstitialAd(): Promise<void>
Experimental تطلب عرض إعلان بيني.

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

لا تقدّم أي ضمانات بشأن ما إذا تم عرض الإعلان.
مثال
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> وعد يتم حلّه عند النجاح ويرفض/يُعرَض مع ytgame.SdkError عند تعذُّر التنفيذ

sendScore

sendScore(score: Score): Promise<void>
إرسال نتيجة إلى YouTube:

يجب أن تمثّل النتيجة سمة واحدة من سمات مستوى التقدّم في اللعبة. إذا كانت هناك سمات متعددة، على المطوّر اختيار سمة واحدة لتصبح متسقة. سيتم ترتيب النتائج وسيتم عرض أعلى نتيجة في واجهة مستخدم YouTube، لذا يجب أن تتطابق أي واجهة مستخدم لأفضل نتيجة في اللعبة مع ما يتم إرساله من خلال واجهة برمجة التطبيقات هذه.
مثال
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> وعد يتم حلّه عند النجاح ويرفض/يُعرَض مع ytgame.SdkError عند تعذُّر التنفيذ

ytgame.engagement.Content

عنصر المحتوى الذي ترسله اللعبة إلى YouTube
الخصائص
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 بأنّ اللعبة بدأت بعرض اللقطات

MUST أن تستدعي اللعبة واجهة برمجة التطبيقات هذه. وإلا، لن تظهر اللعبة للمستخدمين. firstFrameReady() MUST استدعاء الإجراء gameReady() قبله.
مثال
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
إرسال إشعار إلى YouTube بأنّ اللعبة جاهزة للتفاعل معها من قِبل اللاعبين

MUST أن تستدعي اللعبة واجهة برمجة التطبيقات هذه عندما يصبح بالإمكان التفاعل معها. يجب ألا تطلب اللعبة بيانات من واجهة برمجة التطبيقات هذه عندما تكون شاشة التحميل لا تزال معروضة. وفي حال عدم استيفاء هذه المتطلبات، لن تجتاز اللعبة عملية الاعتماد في 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> وعد يكتمل عند نجاح التحميل ويرفض باستخدام 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> وعد يتم حلّه عند نجاح الحفظ ويرفض باستخدام ytgame.SdkError عند تعذُّر الحفظ

ytgame.health

الوظائف والسمات ذات الصلة بحالة اللعبة
الدوال
logError
تسجيل خطأ في YouTube
logWarning
تسجيل تحذير على YouTube

الدوال

logError

logError(): void
تسجيل خطأ في YouTube

ملاحظة: تعتمد واجهة برمجة التطبيقات هذه على أفضل الجهود ويتم الحد من معدّل إرسال البيانات، ما قد يؤدي إلى فقدان البيانات.
مثال
function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void
تسجيل تحذير في YouTube

ملاحظة: تعتمد هذه الواجهة على أفضل الجهود وهي محدودة السرعة، ما قد يؤدي إلى فقدان البيانات.
مثال
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> وعد يكتمل عند نجاح الحصول على اللغة ويرفض باستخدام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.

MUST أن تستخدم اللعبة واجهة برمجة التطبيقات هذه لتعديل حالة صوت اللعبة.
مثال
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) دالة لإلغاء ضبط دالة ردّ الاتصال التي لا يتم استخدامها عادةً