مرجع SDK YouTube Playables

ای‌تی گیم

فضای نام سطح بالا برای SDK مربوط به YouTube Playables.

این یک متغیر سراسری در پنجره فعلی است. شما نباید این متغیر را لغو کنید.
فضاهای نام
ads
توابع و ویژگی‌های مربوط به تبلیغات.
engagement
کارکردها و ویژگی‌های مربوط به تعامل بازیکن.
game
توابع و ویژگی‌های مربوط به رفتارهای عمومی بازی.
health
عملکردها و ویژگی‌های مربوط به سلامت بازی.
system
توابع و ویژگی‌های مربوط به سیستم یوتیوب.
شمارش‌ها
Sdk Error Type
انواع خطاهایی که SDK مربوط به YouTube Playables نشان می‌دهد.
کلاس‌ها
Sdk Error
شیء خطایی که SDK مربوط به YouTube Playables ارسال می‌کند.
متغیرها
IN_ PLAYABLES_ ENV
اینکه آیا بازی در محیط Playables اجرا می‌شود یا خیر.
SDK_ VERSION
نسخه SDK مربوط به YouTube Playables.
همچنین ببینید

شمارش‌ها

نوع خطای Const Sdk

SdkErrorType
انواع خطاهایی که SDK مربوط به YouTube Playables نشان می‌دهد.
اعضای شمارشی
API_ UNAVAILABLE
API موقتاً در دسترس نبود.

اگر بازیکنان در یک جریان بحرانی قرار دارند، از آنها بخواهید که بعداً دوباره تلاش کنند.
INVALID_ PARAMS
API با پارامترهای نامعتبر فراخوانی شد.
SIZE_ LIMIT_ EXCEEDED
API با پارامترهایی که از حد مجاز اندازه تجاوز کرده بودند، فراخوانی شد.
UNKNOWN
نوع خطا مشخص نیست.

متغیرها

Const IN_PLAYABLES_ENV

IN_PLAYABLES_ENV : boolean
اینکه آیا بازی در محیط Playables اجرا می‌شود یا خیر. می‌توانید از این گزینه برای تعیین فعال یا غیرفعال کردن ویژگی‌هایی که فقط در داخل Playables در دسترس هستند استفاده کنید. این بررسی را با بررسی 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

SDK_VERSION : string
نسخه SDK مربوط به YouTube Playables.
مثال 
// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

خطای ytgame.SdkError

Error گسترش
شیء خطایی که SDK مربوط به YouTube Playables ارسال می‌کند.

شیء SdkError فرزند Error است و شامل یک فیلد اضافی می‌باشد.
سازنده‌ها
constructor
خواص
error Type
نوع خطا.
message
name
stack ?

خواص

نوع خطا

errorType : SdkErrorType
نوع خطا.

تبلیغات ytgame

توابع و ویژگی‌های مربوط به تبلیغات.
توابع
request Interstitial Ad
درخواست نمایش یک تبلیغ بینابینی را دارد.
request Rewarded Ad
درخواست نمایش یک تبلیغ جایزه‌دار برای یک نوع جایزه خاص را می‌دهد.

توابع

درخواستتبلیغات بینابینی

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 > وعده‌ای که در صورت موفقیت‌آمیز بودن درخواست، اجرا می‌شود یا در صورت ناموفق بودن درخواست، آن را رد/پرتاب می‌کند.

درخواستRewardedAd

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 جان"
  • ‎121b001a-0c25-4289-88f6-58e3620d938f - "رد شدن از سطح"
بازگشت‌ها
Promise < boolean > وعده‌ای که در صورت موفقیت‌آمیز بودن درخواست، مقدار true را برمی‌گرداند، اگر کاربر شرایط دریافت پاداش را داشته باشد، و در صورت عدم موفقیت، مقدار false را برمی‌گرداند. این وعده در صورت ناموفق بودن درخواست، آن را رد/پرتاب می‌کند.

تعامل در بازی ytgame

کارکردها و ویژگی‌های مربوط به تعامل بازیکن.
شمارش‌ها
Content Type
انواع محتوای ممکن.
رابط‌ها
Content
محتوای مورد نظر که بازی به یوتیوب ارسال می‌کند.
Score
شیء امتیازی که بازی به یوتیوب ارسال می‌کند.
توابع
open YTContent
از یوتیوب درخواست می‌کند تا محتوایی مطابق با شناسه محتوای ارائه شده را باز کند.
send Score
امتیاز را به یوتیوب ارسال می‌کند.

شمارش‌ها

نوع محتوای Const

ContentType
انواع محتوای ممکن.
اعضای شمارشی
PLAYABLE
قابل پخش در یوتیوب.
VIDEO
یک ویدیوی یوتیوب.

توابع

openYTCent

openYTContent ( content : Content ) : Promise < void >
از یوتیوب درخواست می‌کند تا محتوایی مطابق با شناسه محتوای ارائه شده را باز کند.

به‌طورکلی، این کار محتوا را در یک تب جدید در وب باز می‌کند. در موبایل، یک ویدیو در مینی پلیر باز می‌شود و یک 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 محتوایی که قرار است در یوتیوب باز شود.
بازگشت‌ها
Promise < void > یک Promise که در صورت موفقیت اجرا می‌شود و در صورت شکست، با خطای ytgame.SdkError رد/پرتاب می‌شود.

ارسال امتیاز

sendScore ( score : Score ) : Promise < void >
امتیاز را به یوتیوب ارسال می‌کند.

امتیاز باید نشان‌دهنده‌ی یک بُعد از پیشرفت در بازی باشد. اگر چندین بُعد وجود داشته باشد، توسعه‌دهنده باید یک بُعد را برای سازگاری انتخاب کند. امتیازها مرتب می‌شوند و بالاترین امتیاز در رابط کاربری یوتیوب نمایش داده می‌شود، بنابراین هر رابط کاربری امتیاز بالا در بازی باید با آنچه از طریق این 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 نت موسیقی برای ارسال به یوتیوب.
بازگشت‌ها
Promise < void > یک Promise که در صورت موفقیت اجرا می‌شود و در صورت شکست، با خطای ytgame.SdkError رد/پرتاب می‌شود.

محتوای تعاملی بازی ytgame

محتوای مورد نظر که بازی به یوتیوب ارسال می‌کند.
خواص
content Type ?
نوع محتوایی که باید باز شود.
id
شناسه محتوایی که می‌خواهیم باز کنیم.

خواص

نوع محتوای Optional

contentType ?: ContentType
نوع محتوایی که باید باز شود. باید ارائه شود، اما اگر ارائه نشود، VIDEO فرض خواهد شد.

شناسه

id : string
شناسه محتوایی که می‌خواهیم باز کنیم.

امتیاز.مشارکت.ytgame

شیء امتیازی که بازی به یوتیوب ارسال می‌کند.
خواص
value
مقدار امتیاز که به صورت یک عدد صحیح بیان می‌شود.

خواص

ارزش

value : number
مقدار امتیاز به صورت یک عدد صحیح بیان می‌شود. امتیاز باید کمتر یا مساوی حداکثر عدد صحیح ایمن باشد. در غیر این صورت، امتیاز رد خواهد شد.

بازی ytgame

توابع و ویژگی‌های مربوط به رفتارهای عمومی بازی.
توابع
first Frame Ready
به یوتیوب اطلاع می‌دهد که بازی شروع به نمایش فریم‌ها کرده است.
game Ready
به یوتیوب اطلاع می‌دهد که بازی آماده‌ی تعامل بازیکنان است.
load Data
داده‌های بازی را از یوتیوب به شکل یک رشته سریالی بارگذاری می‌کند.
save Data
داده‌های بازی را به صورت یک رشته سریالی در یوتیوب ذخیره می‌کند.

توابع

firstFrameReady

firstFrameReady ( ) : void
به یوتیوب اطلاع می‌دهد که بازی شروع به نمایش فریم‌ها کرده است.

بازی باید این API را فراخوانی کند. در غیر این صورت، بازی به کاربران نمایش داده نمی‌شود. firstFrameReady() باید قبل از gameReady() فراخوانی شود.
مثال 
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

بازی آماده

gameReady ( ) : void
به یوتیوب اطلاع می‌دهد که بازی آماده‌ی تعامل بازیکنان است.

بازی باید این API را زمانی که قابل تعامل است فراخوانی کند. بازی نباید این API را زمانی که صفحه بارگذاری هنوز نمایش داده می‌شود فراخوانی کند. در غیر این صورت، بازی در فرآیند صدور گواهینامه YouTube رد می‌شود.
مثال 
function onGameInteractable() {
  ytgame.game.gameReady();
}

بارگذاری داده

loadData ( ) : Promise < string >
داده‌های بازی را از یوتیوب به شکل یک رشته سریالی بارگذاری می‌کند.

بازی باید هرگونه تجزیه بین رشته و یک قالب داخلی را مدیریت کند.
مثال 
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 ( data : string ) : Promise < void >
داده‌های بازی را به صورت یک رشته سریالی در یوتیوب ذخیره می‌کند.

رشته باید یک رشته معتبر و خوش‌فرم UTF-16 و حداکثر ۳ مگابایت باشد. بازی باید هرگونه تجزیه بین رشته و یک قالب داخلی را مدیریت کند. در صورت لزوم، 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

عملکردها و ویژگی‌های مربوط به سلامت بازی.
توابع
log Error
خطایی را در یوتیوب ثبت می‌کند.
log Warning
یک هشدار به یوتیوب ارسال می‌کند.

توابع

خطای ورود

logError ( ) : void
خطایی را در یوتیوب ثبت می‌کند.

توجه: این API از نوع best-effort و rate-limited است که می‌تواند منجر به از دست رفتن داده‌ها شود.
مثال 
function onError() {
  ytgame.health.logError();
}

هشدار ورود

logWarning ( ) : void
یک هشدار به یوتیوب ارسال می‌کند.

توجه: این API از نوع best-effort و rate-limited است که می‌تواند منجر به از دست رفتن داده‌ها شود.
مثال 
function onWarning() {
  ytgame.health.logWarning();
}

سیستم ytgame

توابع و ویژگی‌های مربوط به سیستم یوتیوب.
توابع
get Language
زبانی را که در تنظیمات یوتیوب کاربر به شکل برچسب زبان BCP-47 تنظیم شده است، برمی‌گرداند.
is Audio Enabled
برمی‌گرداند که آیا صدای بازی در تنظیمات یوتیوب فعال است یا خیر.
on Audio Enabled Change
یک فراخوانی برگشتی تنظیم می‌کند که هنگام اجرای رویداد تغییر تنظیمات صدا از یوتیوب، فعال شود.
on Pause
یک فراخوانی برگشتی تنظیم می‌کند که هنگام اجرای رویداد مکث بازی از YouTube، فعال شود.
on Resume
تنظیم می‌کند که هنگام اجرای یک رویداد بازی از سرگیری از یوتیوب، یک فراخوانی برگشتی (callback) اجرا شود.

توابع

زبان را دریافت کنید

getLanguage ( ) : Promise < string >
زبانی را که در تنظیمات یوتیوب کاربر به شکل برچسب زبان BCP-47 تنظیم شده است، برمی‌گرداند.

از توابع دیگر برای تعیین زبان یا موقعیت مکانی کاربر یا ذخیره تنظیمات زبان آنها در فضای ابری استفاده نکنید. در عوض، از این تابع برای اطمینان از اینکه تجربه کاربر در سراسر یوتیوب یکسان است، استفاده کنید.
مثال 
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
برمی‌گرداند که آیا صدای بازی در تنظیمات یوتیوب فعال است یا خیر.

بازی باید از این برای تنظیم اولیه وضعیت صدای بازی استفاده کند.
مثال 
function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}
بازگشت‌ها
boolean یک مقدار بولی که نشان می‌دهد آیا صدا فعال است یا خیر.

onAudioEnabledChange

onAudioEnabledChange ( callback : ( ( isAudioEnabled : boolean ) => void ) ) : ( ( ) => void )
یک فراخوانی برگشتی تنظیم می‌کند که هنگام اجرای رویداد تغییر تنظیمات صدا از یوتیوب، فعال شود.

بازی باید از این 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 ( callback : ( ( ) => void ) ) : ( ( ) => void )
تنظیم می‌کند که هنگام اجرای یک رویداد بازی از سرگیری از یوتیوب، یک فراخوانی برگشتی (callback) اجرا شود.

پس از توقف بازی، تضمینی برای از سرگیری آن وجود ندارد.
مثال 
ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}
پارامترها
callback : ( ( ) => void ) تابع فراخوانی که قرار است فعال شود.
بازگشت‌ها
( ( ) => void ) تابعی برای لغو تنظیم مجدد فراخوانی که معمولاً استفاده نمی‌شود.