مرجع حزمة تطوير البرامج (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>
Experimental يطلب عرض إعلان بيني.

🧪 واجهة برمجة التطبيقات هذه متاحة للمعاينة العامة، وهي عرضة للتغيير بدون إشعار.

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

🧪 واجهة برمجة التطبيقات هذه متاحة للمعاينة العامة، وهي عرضة للتغيير بدون إشعار.

لا تقدّم أي ضمانات بشأن ما إذا كان الإعلان قد تم عرضه.
مثال
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 coins"
  • ‫7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives"
  • 121b001a-0c25-4289-88f6-58e3620d938f - "تخطّي المستوى"
المرتجعات
Promise<boolean> وعد يتم تنفيذه عند نجاح الطلب مع القيمة صحيح إذا استوفى المستخدم الشروط اللازمة للحصول على مكافأة، أو القيمة خطأ إذا لم يستوفِها. ترفض الوعد أو تعرض خطأ عند تعذّر تنفيذ الطلب.

ytgame.engagement

الدوال والسمات ذات الصلة بتفاعل اللاعبين
واجهات
Score
كائن النتيجة الذي ترسله اللعبة إلى YouTube
الدوال
sendScore
يتم إرسال النتيجة إلى YouTube.

الدوال

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.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) دالة لإلغاء ضبط دالة رد الاتصال التي لا يتم استخدامها عادةً