مرجع SDK YouTube Playables

ytgame

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

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

شمارش ها

Const SdkErrorType

SdkErrorType
انواع خطاهایی که YouTube Playables SDK ایجاد می کند.
شمارش اعضا
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_VERSION

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

ytgame.SdkError

Extends Error
شیء خطایی که YouTube Playables SDK پرتاب می کند.

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

خواص

نوع خطا

errorType : SdkErrorType
نوع خطا

ytgame.ads

🧪 API پیش‌نمایش عمومی: ممکن است بدون اطلاع قبلی تغییر کند.

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

توابع

درخواستInterstitialAd

requestInterstitialAd ( ) : Promise < void >
Experimental برای نمایش یک آگهی بینابینی درخواست می کند.

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

ytgame.engagement

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

توابع

openYTCcontent

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 > یک 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 ارسال می کند.
خواص
id
شناسه ویدیویی که می خواهیم باز کنیم.

خواص

شناسه

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

ytgame.engagement.Score

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

خواص

ارزش

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

ytgame.game

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

توابع

firstFrameReady

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

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

بازی آماده

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 ( 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

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

توابع

logError

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

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

ورود هشدار

logWarning ( ) : void
یک هشدار را در YouTube ثبت می کند.

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

ytgame.system

عملکردها و ویژگی های مربوط به سیستم YouTube.
توابع
get Language
زبانی را که در تنظیمات YouTube کاربر تنظیم شده است را به شکل یک برچسب زبان BCP-47 برمی‌گرداند.
is Audio Enabled
نشان می دهد که آیا صدای بازی در تنظیمات YouTube فعال است یا خیر.
on Audio Enabled Change
زمانی که رویداد تغییر تنظیمات صوتی از YouTube فعال می‌شود، یک تماس برگشتی را تنظیم می‌کند.
on Pause
زمانی که یک رویداد بازی در حالت مکث از YouTube فعال می‌شود، یک تماس برگشتی را تنظیم می‌کند.
on Resume
زمانی که یک رویداد بازی رزومه از 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 رد می شود.

isAudio Enabled

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

onPause برای همه نوع مکث فراخوانی می شود، از جمله زمانی که کاربر از بازی خارج می شود. هیچ تضمینی برای از سرگیری بازی وجود ندارد.
مثال 
ytgame.system.onPause(() => {
  pauseGame();
});

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

در رزومه

onResume ( callback : ( ( ) => void ) ) : ( ( ) => void )
زمانی که یک رویداد بازی رزومه از YouTube فعال می شود، یک تماس برگشتی را تنظیم می کند.

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

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