Dokumentacja pakietu SDK Pokoju gier w YouTube

ytgame

Przestrzeń nazw najwyższego poziomu w przypadku pakietu SDK Pokoju gier na YouTube.

Jest to zmienna o zakresie globalnym w bieżącym oknie. Nie wolno zastępować tej zmiennej.

Przestrzenie nazw
`ads`	🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.
`engagement`	Funkcje i właściwości związane z zaangażowaniem graczy.
`game`	Funkcje i właściwości związane z ogólnymi zachowaniami w grze.
`health`	Funkcje i właściwości związane ze stanem gry.
`system`	Funkcje i właściwości związane z systemem YouTube.

Wyliczenia
`SdkErrorType`	Rodzaje błędów, które zgłasza pakiet SDK Pokoju gier na YouTube.

Zajęcia
`SdkError`	Obiekt błędu zgłaszany przez pakiet SDK Pokoju gier na YouTube.

Zmienne
`IN_PLAYABLES_ENV`	Informacja o tym, czy gra jest uruchomiona w środowisku Pokoju gier.
`SDK_VERSION`	Wersja pakietu SDK Pokoju gier na YouTube.

Zobacz też

https://developers.google.com/youtube/gaming/playables

Wyliczenia

`Const` SdkErrorType

SdkErrorType

Rodzaje błędów, które zgłasza pakiet SDK Pokoju gier na YouTube.

Elementy wyliczenia
`API_UNAVAILABLE`	Interfejs API był tymczasowo niedostępny. Jeśli gracze są w trakcie ważnej czynności, poproś ich o ponowienie próby w późniejszym czasie.
`INVALID_PARAMS`	Wywołano interfejs API z nieprawidłowymi parametrami.
`SIZE_LIMIT_EXCEEDED`	Wywołano interfejs API z parametrami przekraczającymi limit rozmiaru.
`UNKNOWN`	Nieznany typ błędu.

Zmienne

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

Informacja o tym, czy gra jest uruchomiona w środowisku Pokoju gier. Możesz użyć tego parametru, aby określić, czy włączyć lub wyłączyć funkcje dostępne tylko w Pokoju gier. Połącz to sprawdzenie ze sprawdzeniem ytgame, aby upewnić się, że pakiet SDK jest rzeczywiście załadowany.

Przykład

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

Wersja pakietu SDK Pokoju gier na YouTube.

Przykład

// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

Przedłuża Error

Obiekt błędu zgłaszany przez pakiet SDK Pokoju gier na YouTube.

Obiekt SdkError jest elementem podrzędnym obiektu Error i zawiera dodatkowe pole.

Zespoły
`constructor`

Właściwości
`errorType`	Typ błędu.
`message`
`name`
`stack?`

Właściwości

errorType

errorType:
                  SdkErrorType

Typ błędu.

ytgame.ads

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

Funkcje i właściwości związane z reklamami.

Funkcje
`requestInterstitialAd`	Żąda wyświetlenia reklamy pełnoekranowej.
`requestRewardedAd`	Wysyła prośbę o wyświetlenie reklamy z nagrodą w przypadku określonego typu nagrody.

Funkcje

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Wysyła żądanie wyświetlenia reklamy pełnoekranowej.

🧪 INTERFEJS API W WERSJI PUBLICZNEJ: MOŻE ULEC ZMIANIE BEZ POWIADOMIENIA.

Nie gwarantuje, że reklama została wyświetlona. Nie używaj tego interfejsu API do nagradzania graczy za oglądanie reklam.

Przykład

try {
  await ytgame.ads.requestInterstitialAd();
  // Ad request successful, do something else.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}

Zwroty
`Promise<void>`	obietnica, która jest spełniana w przypadku udanego żądania, a odrzucana lub zgłaszana w przypadku nieudanego żądania.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Żąda wyświetlenia reklamy z nagrodą w zamian za konkretny typ nagrody.

🧪 INTERFEJS API W WERSJI PUBLICZNEJ: MOŻE ULEC ZMIANIE BEZ POWIADOMIENIA.

Nie gwarantuje, że reklama została wyświetlona.

Przykład

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.
}

Parametry

Parametry
`rewardId: string`	Wymagane. Identyfikator, który w niepowtarzalny sposób określa typ nagrody, którą można odebrać. W przypadku każdego typu nagrody musisz użyć unikalnego identyfikatora i ponownie wykorzystywać ten sam identyfikator przy każdym oferowaniu tego typu nagrody. Przykład: 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 monet" 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 życia" 121b001a-0c25-4289-88f6-58e3620d938f – „Pomiń poziom”

rewardId: string

Wymagane. Identyfikator, który w niepowtarzalny sposób określa typ nagrody, którą można odebrać. W przypadku każdego typu nagrody musisz użyć unikalnego identyfikatora i ponownie wykorzystywać ten sam identyfikator przy każdym oferowaniu tego typu nagrody. Przykład:

21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 monet"
7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 życia"
121b001a-0c25-4289-88f6-58e3620d938f – „Pomiń poziom”

Zwroty
`Promise<boolean>`	Obietnica, która jest spełniana w przypadku udanego żądania z wartością „prawda”, jeśli użytkownik spełnił warunki otrzymania nagrody, lub „fałsz”, jeśli ich nie spełnił. Obietnica odrzuca lub zgłasza błąd w przypadku nieudanego żądania.

ytgame.engagement

Funkcje i właściwości związane z zaangażowaniem graczy.

Interfejsy
`Score`	Obiekt wyniku, który gra wysyła do YouTube.

Funkcje
`sendScore`	Wysyła wynik do YouTube.

Funkcje

sendScore

sendScore(score: Score): Promise<void>

Wysyła wynik do YouTube.

Wynik powinien odzwierciedlać jeden z wymiarów postępu w grze. Jeśli jest kilka wymiarów, deweloper musi wybrać jeden z nich, aby zachować spójność. Wyniki będą sortowane, a najwyższy z nich będzie wyświetlany w interfejsie YouTube, więc interfejs rekordów w grze powinien być zgodny z danymi przesyłanymi przez ten interfejs API.

Przykład

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.
  }
}

Parametry
`score: Score`	wynik do wysłania do YouTube.

Zwroty
`Promise<void>`	Obietnica, która jest spełniana w przypadku powodzenia i odrzucana lub zgłasza błąd `ytgame.SdkError` w przypadku niepowodzenia.

ytgame.engagement.Score

Obiekt wyniku, który gra wysyła do YouTube.

Właściwości
`value`	Wartość wyniku wyrażona jako liczba całkowita.

Właściwości

value

value: number

Wartość wyniku wyrażona jako liczba całkowita. Wynik musi być mniejszy lub równy maksymalnej bezpiecznej liczbie całkowitej. W przeciwnym razie wynik zostanie odrzucony.

ytgame.game

Funkcje i właściwości związane z ogólnymi zachowaniami w grze.

Funkcje
`firstFrameReady`	Informuje YouTube, że gra zaczęła wyświetlać klatki.
`gameReady`	Informuje YouTube, że gra jest gotowa do interakcji z graczami.
`loadData`	Wczytuje dane z gry z YouTube w postaci zserializowanego ciągu znaków.
`saveData`	Zapisuje dane z gry w YouTube w postaci serializowanego ciągu tekstowego.

Funkcje

firstFrameReady

firstFrameReady(): void

Informuje YouTube, że gra zaczęła wyświetlać klatki.

Gra MUSI wywołać ten interfejs API. W przeciwnym razie gra nie będzie wyświetlana użytkownikom. Metodę firstFrameReady() MUSI wywołać przed metodą gameReady().

Przykład

function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void

Powiadamia YouTube, że gra jest gotowa do interakcji z graczami.

Gra MUSI wywołać ten interfejs API, gdy będzie można z niej korzystać. Gra NIE MOŻE wywoływać tego interfejsu API, gdy nadal wyświetla się ekran wczytywania. W przeciwnym razie gra nie przejdzie procesu certyfikacji YouTube.

Przykład

function onGameInteractable() {
  ytgame.game.gameReady();
}

loadData

loadData(): Promise<string>

Wczytuje dane gry z YouTube w postaci serializowanego ciągu znaków.

Gra musi obsługiwać analizowanie ciągu znaków i przekształcanie go do formatu wewnętrznego.

Przykład

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.
  }
}

Zwroty
`Promise<string>`	Obietnica, która jest spełniana, gdy wczytywanie się powiedzie, i odrzucana z wartością `ytgame.SdkError`, gdy się nie powiedzie.

saveData

saveData(data: string): Promise<void>

Zapisuje dane z gier w YouTube w postaci serializowanego ciągu znaków.

Ciąg znaków musi być prawidłowym, dobrze sformatowanym ciągiem znaków UTF-16 o maksymalnym rozmiarze 3 MiB. Gra musi obsługiwać wszelkie analizowanie ciągu znaków i przekształcanie go w format wewnętrzny. W razie potrzeby użyj String.isWellFormed(), aby sprawdzić, czy ciąg jest prawidłowo sformatowany.

Przykład

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.
  }
}

Parametry
`data: string`

Zwroty
`Promise<void>`	Obietnica, która jest spełniana, gdy zapisywanie się powiodło, i odrzucana z błędem `ytgame.SdkError`, gdy się nie powiodło.

ytgame.health

Funkcje i właściwości związane ze stanem gry.

Funkcje
`logError`	Rejestruje błąd w YouTube.
`logWarning`	Rejestruje ostrzeżenie w YouTube.

Funkcje

logError

logError(): void

Rejestruje błąd w YouTube.

Uwaga: ten interfejs API działa w trybie najlepszej jakości i ma ograniczone limity, co może powodować utratę danych.

Przykład

function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void

Rejestruje ostrzeżenie w YouTube.

Uwaga: ten interfejs API działa na zasadzie „najlepszych starań” i ma ograniczone limity, co może powodować utratę danych.

Przykład

function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

Funkcje i właściwości związane z systemem YouTube.

Funkcje
`getLanguage`	Zwraca język ustawiony w ustawieniach YouTube użytkownika w postaci tagu języka zgodnego ze standardem BCP-47.
`isAudioEnabled`	Informuje, czy dźwięk z gry jest włączony w ustawieniach YouTube.
`onAudioEnabledChange`	Ustawia wywołanie zwrotne, które ma być uruchamiane, gdy z YouTube zostanie wysłane zdarzenie zmiany ustawień dźwięku.
`onPause`	Ustawia wywołanie zwrotne, które ma być wywoływane, gdy z YouTube zostanie wyemitowane zdarzenie wstrzymania gry.
`onResume`	Ustawia wywołanie zwrotne, które ma być uruchamiane, gdy z YouTube zostanie wywołane zdarzenie wznowienia gry.

Funkcje

getLanguage

getLanguage(): Promise<string>

Zwraca język ustawiony w ustawieniach YouTube użytkownika w postaci tagu języka BCP-47.

Nie używaj innych funkcji do określania języka lub ustawień regionalnych użytkownika ani nie przechowuj jego preferencji językowych w zapisie w chmurze. Zamiast tego używaj tej funkcji, aby zapewnić spójność wrażeń użytkowników w YouTube.

Przykład

const localeTag = await ytgame.system.getLanguage();
// `localeTag` is now set to something like "en-US" or "es-419".

Zwroty
`Promise<string>`	Obietnica, która zostanie spełniona, gdy pobieranie języka się powiedzie, a w przypadku niepowodzenia zostanie odrzucona z wartością `ytgame.SdkError`.

isAudioEnabled

isAudioEnabled(): boolean

Zwraca informację, czy dźwięk z gry jest włączony w ustawieniach YouTube.

Gra POWINNA używać tej funkcji do inicjowania stanu dźwięku z gry.

Przykład

function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}

Zwroty
`boolean`	wartość logiczna wskazująca, czy dźwięk jest włączony.

onAudioEnabledChange

onAudioEnabledChange(callback: ((isAudioEnabled: boolean) => void)): (() => void)

Ustawia wywołanie zwrotne, które ma być aktywowane, gdy z YouTube zostanie wyemitowane zdarzenie zmiany ustawień dźwięku.

Gra MUSI używać tego interfejsu API do aktualizowania stanu dźwięku w grze.

Przykład

ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});

Parametry
`callback: ((isAudioEnabled: boolean) => void)`	funkcja wywołania zwrotnego, która ma zostać wywołana.

Zwroty
`(() => void)`	funkcja do anulowania wywołania zwrotnego, która jest zwykle nieużywana.

onPause

onPause(callback: (() => void)): (() => void)

Ustawia wywołanie zwrotne, które ma być wywoływane, gdy z YouTube zostanie wyemitowane zdarzenie wstrzymania gry. Gra ma krótki czas na zapisanie stanu przed usunięciem.

onPause jest wywoływana w przypadku wszystkich typów wstrzymania, w tym gdy użytkownik opuści grę. Nie ma gwarancji, że gra zostanie wznowiona.

Przykład

ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}

Parametry
`callback: (() => void)`	funkcja wywołania zwrotnego, która ma zostać wywołana.

Zwroty
`(() => void)`	funkcja do anulowania wywołania zwrotnego, która jest zwykle nieużywana.

onResume

onResume(callback: (() => void)): (() => void)

Ustawia wywołanie zwrotne, które ma zostać wywołane, gdy z YouTube zostanie wyemitowane zdarzenie wznowienia gry.

Po wstrzymaniu gry nie ma gwarancji, że zostanie ona wznowiona.

Przykład

ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}

Parametry
`callback: (() => void)`	funkcja wywołania zwrotnego, która ma zostać wywołana.

Zwroty
`(() => void)`	funkcja do anulowania wywołania zwrotnego, która jest zwykle nieużywana.

Dokumentacja pakietu SDK Pokoju gier w YouTube Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

ytgame

Wyliczenia

Const SdkErrorType

Zmienne

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Właściwości

errorType

ytgame.ads

Funkcje

requestInterstitialAd

requestRewardedAd

ytgame.engagement

Funkcje

sendScore

ytgame.engagement.Score

Właściwości

value

ytgame.game

Funkcje

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Funkcje

logError

logWarning

ytgame.system

Funkcje

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Dokumentacja pakietu SDK Pokoju gier w YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION