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

ytgame

مساحة الاسم ذات المستوى الأعلى لحزمة تطوير البرامج (SDK) الخاصة بـ "هيّا نلعب على YouTube"

وهي متغيّر ذو نطاق عام في النافذة الحالية. يجب عدم تجاهل هذا المتغيّر.
مساحات الاسم
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
كانت واجهة برمجة التطبيقات غير متاحة مؤقتًا.

اطلب من اللاعبين إعادة المحاولة في وقت لاحق إذا كانوا في مسار حرج.
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
كائن الخطأ الذي تطرحه حزمة تطوير البرامج (SDK) الخاصة بميزة "هيّا نلعب على YouTube".

الكائن SdkError هو عنصر ثانوي من Error ويحتوي على حقل إضافي.
الشركات المصنِّعة
constructor
الخصائص
errorType
تمثّل هذه السمة نوع الخطأ.
message
name
stack?

الخصائص

errorType

errorType: SdkErrorType
تمثّل هذه السمة نوع الخطأ.

ytgame.ads

الدوال والسمات ذات الصلة بالإعلانات
الدوال
requestInterstitialAd
يطلب عرض إعلان بيني.
requestRewardedAd
يطلب عرض "إعلان مقابل مكافأة" لنوع مكافأة معيّن.

الدوال

requestInterstitialAd

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

لا يقدّم أي ضمانات بشأن ما إذا تم عرض الإعلان أم لا. لا تستخدِم واجهة برمجة التطبيقات هذه لمكافأة اللاعبين مقابل مشاهدة إعلان.
مثال
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> وعد يتم تنفيذه عند نجاح الطلب أو رفضه/إلغاؤه عند تعذُّر تنفيذه.

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> وعد يتم تنفيذه عند نجاح الطلب مع القيمة 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 فتح المحتوى الذي يتطابق مع معرّف المحتوى المقدَّم.

بشكل عام، سيتم فتح المحتوى في علامة تبويب جديدة على الويب. على الأجهزة الجوّالة، سيتم فتح فيديو في المشغّل المصغّر وسيحلّ Playable محلّ Playable المفتوح حاليًا.
مثال
// 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> وعد يتم تنفيذه عند النجاح ورفضه/إصداره مع 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
الخصائص
contentType?
نوع المحتوى المطلوب فتحه
id
معرّف المحتوى الذي نريد فتحه

الخصائص

Optional contentType

contentType?: ContentType
نوع المحتوى المطلوب فتحه يجب توفيرها، ولكن في حال عدم توفيرها، سيتم استخدام القيمة VIDEO.

المعرِّف

id: string
معرّف المحتوى الذي نريد فتحه

ytgame.engagement.Score

كائن النتيجة الذي ترسله اللعبة إلى YouTube
الخصائص
value
تمثّل هذه السمة قيمة النتيجة كعدد صحيح.

الخصائص

value

value: number
تمثّل هذه السمة قيمة النتيجة كعدد صحيح. يجب أن تكون النتيجة أقل من الحد الأقصى لعدد صحيح آمن أو مساوية له. وإلا سيتم رفض النتيجة.

ytgame.game

الدوال والسمات المتعلّقة بسلوكيات الألعاب العامة
الدوال
firstFrameReady
يُعلم هذا الحدث YouTube بأنّ اللعبة قد بدأت في عرض اللقطات.
gameReady
يُعلم هذا الحدث YouTube بأنّ اللعبة جاهزة ليتفاعل معها اللاعبون.
loadData
تحميل بيانات اللعبة من YouTube على شكل سلسلة مسلسلة
saveData
يحفظ بيانات اللعبة على YouTube في شكل سلسلة مسلسلة.

الدوال

firstFrameReady

firstFrameReady(): void
يُعلم YouTube بأنّ اللعبة بدأت في عرض اللقطات.

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

gameReady

gameReady(): void
يُعلم هذا الإجراء YouTube بأنّ اللعبة أصبحت جاهزة ليتفاعل معها اللاعبون.

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

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