Riferimento per l'SDK della Sala giochi di YouTube

ytgame

Lo spazio dei nomi di primo livello per l'SDK YouTube Playables.

Si tratta di una variabile con ambito globale nella finestra corrente. NON DEVI eseguire l'override di questa variabile.
Spazi dei nomi
ads
🧪 API DI ANTEPRIMA PUBBLICA: SOGGETTO A MODIFICHE SENZA PREAVVISO.
engagement
Le funzioni e le proprietà relative al coinvolgimento dei giocatori.
game
Le funzioni e le proprietà relative ai comportamenti generici dei giochi.
health
Le funzioni e le proprietà relative alla salute del gioco.
system
Le funzioni e le proprietà relative al sistema di YouTube.
Enumerazioni
SdkErrorType
I tipi di errori generati dall'SDK YouTube Playables.
Corsi
SdkError
L'oggetto errore generato dall'SDK YouTube Playables.
Variabili
IN_PLAYABLES_ENV
Indica se il gioco è in esecuzione o meno nell'ambiente Playables.
SDK_VERSION
La versione dell'SDK YouTube Playables.
Vedi anche

Enumerazioni

Const SdkErrorType

SdkErrorType
I tipi di errori generati dall'SDK YouTube Playables.
Membri dell'enumerazione
API_UNAVAILABLE
L'API non è stata temporaneamente disponibile.

Chiedi ai giocatori di riprovare più tardi se si trovano in un flusso critico.
INVALID_PARAMS
L'API è stata chiamata con parametri non validi.
SIZE_LIMIT_EXCEEDED
L'API è stata chiamata con parametri che superano il limite di dimensioni.
UNKNOWN
Il tipo di errore è sconosciuto.

Variabili

Const IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean
Indica se il gioco è in esecuzione o meno nell'ambiente Playables. Puoi utilizzarlo per determinare se attivare o disattivare le funzionalità disponibili solo all'interno di Sala giochi. Combina questo controllo con la ricerca di ytgame per assicurarti che l'SDK sia effettivamente caricato.
Esempio
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
La versione dell'SDK YouTube Playables.
Esempio
// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

Si estende Error
L'oggetto errore generato dall'SDK YouTube Playables.

L'oggetto SdkError è un elemento secondario di Error e contiene un campo aggiuntivo.
Costruttori
constructor
Proprietà
errorType
Il tipo di errore.
message
name
stack?

Proprietà

errorType

errorType: SdkErrorType
Il tipo di errore.

ytgame.ads

🧪 API PREVIEW PUBBLICA: SOGGETTO A MODIFICHE SENZA PREAVVISO.

Le funzioni e le proprietà relative agli annunci.
Funzioni
requestInterstitialAd
Richiede la visualizzazione di un annuncio interstitial.

Funzioni

requestInterstitialAd

requestInterstitialAd(): Promise<void>
Experimental Richiede la visualizzazione di un annuncio interstitial.

🧪 API PREVIEW PUBBLICA: SOGGETTO A MODIFICHE SENZA PREAVVISO.

Non fornisce alcuna garanzia sulla visualizzazione dell'annuncio.
Esempio
try {
  await ytgame.ads.requestInterstitialAd();
  // Ad request successful, do something else.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}
Resi
Promise<void> una promessa che si risolve in una richiesta andata a buon fine o rifiuta/lancia un'eccezione in caso di richiesta non andata a buon fine.

ytgame.engagement

Le funzioni e le proprietà relative al coinvolgimento dei giocatori.
Interfacce
Content
L'oggetto dei contenuti inviato dal gioco a YouTube.
Score
L'oggetto punteggio inviato dalla partita a YouTube.
Funzioni
openYTContent
Chiede a YouTube di aprire i contenuti corrispondenti all'ID video fornito.
sendScore
Invia un punteggio a YouTube.

Funzioni

openYTContent

openYTContent(content: Content): Promise<void>
Chiede a YouTube di aprire i contenuti corrispondenti all'ID video fornito.

In genere, il video si aprirà in una nuova scheda sul web e nel miniplayer sui dispositivi mobili.
Esempio
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.
  }
}
Parametri
content: Content I contenuti da aprire su YouTube.
Resi
Promise<void> una promessa che si risolve in caso di successo e rifiuta/lancia un ytgame.SdkError in caso di errore.

sendScore

sendScore(score: Score): Promise<void>
Invia un punteggio a YouTube.

Il punteggio deve rappresentare una dimensione dell'avanzamento nel gioco. Se sono presenti più dimensioni, lo sviluppatore deve scegliere una dimensione per garantire la coerenza. I punteggi verranno ordinati e il punteggio più alto verrà visualizzato nell'interfaccia utente di YouTube, pertanto qualsiasi interfaccia utente del punteggio più alto in-game deve essere in linea con quanto viene inviato tramite questa API.
Esempio
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.
  }
}
Parametri
score: Score la partitura da inviare a YouTube.
Resi
Promise<void> una promessa che si risolve in caso di successo e rifiuta/lancia un ytgame.SdkError in caso di errore.

ytgame.engagement.Content

L'oggetto dei contenuti inviato dal gioco a YouTube.
Proprietà
id
L'ID del video che vogliamo aprire.

Proprietà

id

id: string
L'ID del video che vogliamo aprire.

ytgame.engagement.Score

L'oggetto punteggio inviato dalla partita a YouTube.
Proprietà
value
Il valore del punteggio espresso come numero intero.

Proprietà

value

value: number
Il valore del punteggio espresso come numero intero. Il punteggio deve essere inferiore o uguale al numero intero sicuro massimo. In caso contrario, il punteggio verrà rifiutato.

ytgame.game

Le funzioni e le proprietà relative ai comportamenti generici dei giochi.
Funzioni
firstFrameReady
Invia una notifica a YouTube che indica che il gioco ha iniziato a mostrare frame.
gameReady
Comunica a YouTube che il gioco è pronto per essere utilizzato dai giocatori.
loadData
Carica i dati di gioco da YouTube sotto forma di stringa serializzata.
saveData
Salva i dati di gioco su YouTube sotto forma di stringa serializzata.

Funzioni

firstFrameReady

firstFrameReady(): void
Invia una notifica a YouTube che indica che il gioco ha iniziato a mostrare frame.

Il gioco MUST chiamare questa API. In caso contrario, il gioco non viene mostrato agli utenti. firstFrameReady() MUST essere chiamato prima di gameReady().
Esempio
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
Invia una notifica a YouTube che indica che il gioco è pronto per essere utilizzato dai giocatori.

Il gioco MUST chiamare questa API quando è possibile interagire con esso. Il gioco NON DEVE chiamare questa API quando è ancora visualizzata una schermata di caricamento. In caso contrario, il gioco non supera la procedura di certificazione di YouTube.
Esempio
function onGameInteractable() {
  ytgame.game.gameReady();
}

loadData

loadData(): Promise<string>
Carica i dati di gioco da YouTube sotto forma di stringa serializzata.

Il gioco deve gestire qualsiasi analisi tra la stringa e un formato interno.
Esempio
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.
  }
}
Resi
Promise<string> Una promessa che viene completata quando il caricamento è riuscito e rifiuta con un ytgame.SdkError se non è riuscito.

saveData

saveData(data: string): Promise<void>
Salva i dati di gioco su YouTube sotto forma di stringa serializzata.

La stringa deve essere una stringa UTF-16 valida e ben formattata e non deve superare i 3 MiB. Il gioco deve gestire qualsiasi analisi tra la stringa e un formato interno. Se necessario, utilizza String.isWellFormed() per verificare se la stringa è ben formattata.
Esempio
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.
  }
}
Parametri
data: string
Resi
Promise<void> Una promessa che si risolve quando il salvataggio è riuscito e viene rifiutata con un ytgame.SdkError in caso di errore.

ytgame.health

Le funzioni e le proprietà relative alla salute del gioco.
Funzioni
logError
Registra un errore su YouTube.
logWarning
Registra un avviso su YouTube.

Funzioni

logError

logError(): void
Registra un errore su YouTube.

Nota: questa API è basata sul criterio del massimo impegno e ha un limite di frequenza, il che può comportare la perdita di dati.
Esempio
function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void
Registra un avviso su YouTube.

Nota: questa API è basata sul criterio del massimo impegno e ha un limite di frequenza, il che può comportare la perdita di dati.
Esempio
function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

Le funzioni e le proprietà relative al sistema di YouTube.
Funzioni
getLanguage
Restituisce la lingua impostata nelle impostazioni di YouTube dell'utente sotto forma di tag lingua BCP-47.
isAudioEnabled
Restituisce se l'audio della partita è attivo nelle impostazioni di YouTube.
onAudioEnabledChange
Imposta un callback da attivare quando viene attivato l'evento di modifica delle impostazioni audio da YouTube.
onPause
Imposta un callback da attivare quando viene attivato un evento di messa in pausa del gioco da YouTube.
onResume
Imposta un callback da attivare quando viene attivato un evento di ripresa del gioco da YouTube.

Funzioni

getLanguage

getLanguage(): Promise<string>
Restituisce la lingua impostata nelle impostazioni di YouTube dell'utente sotto forma di tag lingua BCP-47.

Non utilizzare altre funzioni per determinare la lingua o la codifica dell'utente o per memorizzare le sue preferenze linguistiche nel salvataggio sul cloud. Utilizza invece questa funzione per garantire un'esperienza utente coerente su YouTube.
Esempio
const localeTag = await ytgame.system.getLanguage();
// `localeTag` is now set to something like "en-US" or "es-419".
Resi
Promise<string> Una promessa che viene completata quando l'ottenimento della lingua è riuscito e rifiuta con un ytgame.SdkError in caso di errore.

isAudioEnabled

isAudioEnabled(): boolean
Restituisce se l'audio del gioco è abilitato nelle impostazioni di YouTube.

Il gioco DEVE utilizzarlo per inizializzare lo stato dell'audio del gioco.
Esempio
function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}
Resi
boolean Un valore booleano che indica se l'audio è attivo.

onAudioEnabledChange

onAudioEnabledChange(callback: ((isAudioEnabled: boolean) => void)): (() => void)
Imposta un callback da attivare quando viene attivato l'evento di modifica delle impostazioni audio da YouTube.

Il gioco MUST utilizzare questa API per aggiornare lo stato audio del gioco.
Esempio
ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});
Parametri
callback: ((isAudioEnabled: boolean) => void) la funzione di callback da attivare.
Resi
(() => void) una funzione per annullare l'impostazione del callback, in genere non utilizzata.

onPause

onPause(callback: (() => void)): (() => void)
Imposta un callback da attivare quando viene attivato un evento di messa in pausa del gioco da YouTube. Il gioco ha un breve intervallo di tempo per salvare qualsiasi stato prima di essere eliminato.

onPause viene chiamato per tutti i tipi di interruzioni, incluso quando l'utente esce dal gioco. Non è garantito che la partita verrà ripresa.
Esempio
ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}
Parametri
callback: (() => void) la funzione di callback da attivare.
Resi
(() => void) una funzione per annullare l'impostazione del callback, in genere non utilizzata.

onResume

onResume(callback: (() => void)): (() => void)
Imposta un callback da attivare quando viene attivato un evento di ripresa della partita da YouTube.

Dopo essere stata messa in pausa, la partita non riprende necessariamente.
Esempio
ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}
Parametri
callback: (() => void) la funzione di callback da attivare.
Resi
(() => void) una funzione per annullare l'impostazione del callback, in genere non utilizzata.