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 ANTEPRIMA PUBBLICA: SOGGETTA A MODIFICHE SENZA PREAVVISO.
`engagement`	Le funzioni e le proprietà relative al coinvolgimento dei giocatori.
`game`	Le funzioni e le proprietà relative ai comportamenti di gioco generici.
`health`	Le funzioni e le proprietà relative alla salute del gioco.
`system`	Le funzioni e le proprietà relative al sistema 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 nell'ambiente della Sala giochi.
`SDK_VERSION`	La versione dell'SDK YouTube Playables.

Vedi anche

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

Enumerazioni

`Const` SdkErrorType

SdkErrorType

I tipi di errori generati dall'SDK YouTube Playables.

Membri dell'enumerazione
`API_UNAVAILABLE`	L'API non era temporaneamente disponibile. Chiedi ai giocatori di riprovare in un secondo momento 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 nell'ambiente della Sala giochi. Puoi utilizzare questo valore per determinare se attivare o disattivare le funzionalità disponibili solo all'interno di Sala giochi. Combina questo controllo con la verifica di ytgame per assicurarti che l'SDK venga 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

Estende Error

L'oggetto di errore generato da YouTube Playables SDK.

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 ANTEPRIMA PUBBLICA: SOGGETTA A MODIFICHE SENZA PREAVVISO.

Le funzioni e le proprietà relative agli annunci.

Funzioni
`requestInterstitialAd`	Richiede la visualizzazione di un annuncio interstitial.
`requestRewardedAd`	Richiede la visualizzazione di un annuncio con premio per un determinato tipo di premio.

Funzioni

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Richiede la visualizzazione di un annuncio interstitial.

🧪 API ANTEPRIMA PUBBLICA: SOGGETTA A MODIFICHE SENZA PREAVVISO.

Non offre garanzie sulla visualizzazione dell'annuncio. Non utilizzare questa API per premiare i giocatori per la visualizzazione di un 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 caso di richiesta riuscita o viene rifiutata/genera un errore in caso di richiesta non riuscita.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Richiede la visualizzazione di un annuncio con premio per un determinato tipo di premio.

🧪 API ANTEPRIMA PUBBLICA: SOGGETTA A MODIFICHE SENZA PREAVVISO.

Non fornisce garanzie sulla visualizzazione dell'annuncio.

Esempio

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

Parametri

Parametri
`rewardId: string`	Obbligatorio. Un identificatore che identifica in modo univoco il tipo di premio rivendicabile. Devi utilizzare un ID univoco per ogni tipo di premio e riutilizzare lo stesso ID ogni volta che viene offerto quel tipo specifico di premio. Ad esempio: 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 monete" 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 vite" 121b001a-0c25-4289-88f6-58e3620d938f - "Salta livello"

rewardId: string

Obbligatorio. Un identificatore che identifica in modo univoco il tipo di premio rivendicabile. Devi utilizzare un ID univoco per ogni tipo di premio e riutilizzare lo stesso ID ogni volta che viene offerto quel tipo specifico di premio. Ad esempio:

21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 monete"
7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 vite"
121b001a-0c25-4289-88f6-58e3620d938f - "Salta livello"

Resi
`Promise<boolean>`	Una promessa che si risolve in una richiesta riuscita con valore true se l'utente ha soddisfatto le condizioni per ricevere un premio o false in caso contrario. La promessa rifiuta/genera un errore in caso di richiesta non riuscita.

ytgame.engagement

Le funzioni e le proprietà relative al coinvolgimento dei giocatori.

Interfacce
`Score`	L'oggetto del punteggio che il gioco invia a YouTube.

Funzioni
`sendScore`	Invia un punteggio a YouTube.

Funzioni

sendScore

sendScore(score: Score): Promise<void>

Invia un punteggio a YouTube.

Il punteggio deve rappresentare una dimensione dell'avanzamento all'interno del gioco. Se sono presenti più dimensioni, lo sviluppatore deve scegliere una dimensione da utilizzare in modo coerente. I punteggi verranno ordinati e il punteggio più alto verrà visualizzato nell'interfaccia utente di YouTube, in modo che qualsiasi interfaccia utente di punteggio più alto nel gioco sia allineata a ciò che 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`	il punteggio da inviare a YouTube.

Resi
`Promise<void>`	una promessa che viene risolta in caso di esito positivo e rifiutata/generata con un `ytgame.SdkError` in caso di esito negativo.

ytgame.engagement.Score

L'oggetto del punteggio che il gioco invia 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, lo spartito verrà rifiutato.

ytgame.game

Le funzioni e le proprietà relative ai comportamenti di gioco generici.

Funzioni
`firstFrameReady`	Notifica a YouTube che il gioco ha iniziato a mostrare i frame.
`gameReady`	Comunica a YouTube che il gioco è pronto per l'interazione dei 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

Notifica a YouTube che il gioco ha iniziato a mostrare i frame.

Il gioco DEVE chiamare questa API. In caso contrario, il gioco non viene mostrato agli utenti. firstFrameReady() DEVE essere chiamato prima di gameReady().

Esempio

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

gameReady

gameReady(): void

Notifica a YouTube che il gioco è pronto per l'interazione dei giocatori.

Il gioco DEVE chiamare questa API quando è interattivo. Il gioco NON DEVE chiamare questa API quando viene 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 l'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 viene rifiutata con un `ytgame.SdkError` in caso di errore.

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 formata e avere una dimensione massima di 3 MiB. Il gioco deve gestire l'analisi della stringa e di un formato interno. Se necessario, utilizza String.isWellFormed() per verificare se la stringa è ben formata.

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 viene risolta quando il salvataggio è riuscito e 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 è di tipo best-effort e con 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 è di tipo best-effort e con 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 YouTube.

Funzioni
`getLanguage`	Restituisce la lingua impostata nelle impostazioni di YouTube dell'utente sotto forma di un tag di lingua BCP-47.
`isAudioEnabled`	Indica se l'audio del gioco è 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 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 di lingua BCP-47.

Non utilizzare altre funzioni per determinare la lingua o le impostazioni internazionali dell'utente o per memorizzare la sua preferenza della lingua 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 viene rifiutata con un `ytgame.SdkError` in caso di errore.

isAudioEnabled

isAudioEnabled(): boolean

Restituisce un valore che indica se l'audio del gioco è attivato nelle impostazioni di YouTube.

Il gioco DEVE utilizzare questo valore 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 è abilitato.

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 DEVE 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, che di solito non viene utilizzata.

onPause

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

Imposta un callback da attivare quando viene attivato un evento di pausa del gioco da YouTube. Il gioco ha una breve finestra per salvare qualsiasi stato prima di essere rimosso.

onPause viene chiamato per tutti i tipi di pause, anche quando l'utente esce dal gioco. Non è garantito che la partita riprenderà.

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, che di solito non viene utilizzata.

onResume

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

Imposta un callback da attivare quando viene attivato un evento di ripresa del gioco da YouTube.

Dopo la messa in pausa, la ripresa del gioco non è garantita.

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, che di solito non viene utilizzata.

Riferimento per l'SDK della Sala giochi di YouTube Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

ytgame

Enumerazioni

Const SdkErrorType

Variabili

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Proprietà

errorType

ytgame.ads

Funzioni

requestInterstitialAd

requestRewardedAd

ytgame.engagement

Funzioni

sendScore

ytgame.engagement.Score

Proprietà

value

ytgame.game

Funzioni

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Funzioni

logError

logWarning

ytgame.system

Funzioni

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Riferimento per l'SDK della Sala giochi di YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION