Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Riferimento per l'SDK della Sala giochi di YouTube

ytgame

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

Si tratta di una variabile con ambito globale nella finestra corrente. NON DEVI eseguire l'override di questa variabile.

Spazi dei nomi
`ads`	Funzioni e proprietà correlate agli annunci.
`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à correlate alla salute del gioco.
`system`	Le funzioni e le proprietà relative al sistema YouTube.

Enumerazioni
`SdkErrorType`	I tipi di errori generati dall'SDK Sala giochi di YouTube.

Corsi
`SdkError`	L'oggetto errore generato dall'SDK Sala giochi di YouTube.

Variabili
`IN_PLAYABLES_ENV`	Indica se il gioco è in esecuzione nell'ambiente Sala giochi.
`SDK_VERSION`	La versione dell'SDK Sala giochi di YouTube.

Vedi anche

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

Enumerazioni

`Const` SdkErrorType

SdkErrorType

I tipi di errori generati dall'SDK Sala giochi di YouTube.

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 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 Sala giochi di YouTube.

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

Funzioni e proprietà correlate 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>

Richiede la visualizzazione di un annuncio interstitial.

Non offre alcuna garanzia in merito alla visualizzazione dell'annuncio. Non utilizzare questa API per premiare i giocatori che guardano 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 che viene rifiutata/genera un errore in caso di richiesta non riuscita.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

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

Non offre garanzie sulla visualizzazione dell'annuncio.

Esempio

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

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, puoi rendere l'ID leggibile o un UUID. Puoi includerlo come ID hardcoded nel codice del gioco per il premio specifico. Gli unici requisiti sono che tu fornisca un ID e che non contenga dati utente. Ad esempio: 100-coins-reward-12 - "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, puoi rendere l'ID leggibile o un UUID. Puoi includerlo come ID hardcoded nel codice del gioco per il premio specifico. Gli unici requisiti sono che tu fornisca un ID e che non contenga dati utente. Ad esempio:

100-coins-reward-12 - "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.

Enumerazioni
`ContentType`	I tipi di contenuti possibili.

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

Funzioni
`openYTContent`	Richiede a YouTube di aprire i contenuti corrispondenti all'ID contenuto fornito.
`sendScore`	Invia un punteggio a YouTube.

Enumerazioni

`Const` ContentType

ContentType

I tipi di contenuti possibili.

Membri dell'enumerazione
`PLAYABLE`	Un gioco della Sala giochi di YouTube.
`VIDEO`	Un video di YouTube.

Funzioni

openYTContent

openYTContent(content: Content): Promise<void>

Richiede a YouTube di aprire i contenuti corrispondenti all'ID contenuto fornito.

In genere, i contenuti vengono aperti in una nuova scheda sul web. Su dispositivo mobile, un video si aprirà nel Mini player e un'esperienza riproducibile sostituirà quella attualmente aperta.

Esempio

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

Parametri
`content: Content`	i contenuti da aprire su 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.

sendScore

sendScore(score: Score): Promise<void>

Invia un punteggio a YouTube.

Il punteggio deve rappresentare una dimensione dei progressi all'interno del gioco. Se ci sono più dimensioni, lo sviluppatore deve scegliere una dimensione per garantire la coerenza. I punteggi verranno ordinati e il miglior punteggio verrà visualizzato nell'interfaccia utente di YouTube, quindi qualsiasi interfaccia utente di miglior punteggio nel gioco deve essere 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.Content

L'oggetto dei contenuti che il gioco invia a YouTube.

Proprietà
`contentType?`	Il tipo di contenuti da aprire.
`id`	L'ID dei contenuti che vogliamo aprire.

Proprietà

`Optional` contentType

contentType?:
                    ContentType

Il tipo di contenuti da aprire. Deve essere fornito, ma se non viene fornito, verrà utilizzato il valore VIDEO.

id

id: string

L'ID dei contenuti che vogliamo aprire.

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, il punteggio 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`	Notifica 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à correlate alla salute del gioco.

Funzioni
`logError`	Registra un errore su YouTube.
`logWarning`	Registra un avviso per YouTube.

Funzioni

logError

logError(): void

Registra un errore su YouTube.

Nota:questa API è di tipo best-effort e con limiti 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`	Restituisce un valore che indica se l'audio del gioco è attivato nelle impostazioni di YouTube.
`onAudioEnabledChange`	Imposta una richiamata 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 le sue preferenze 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 il recupero 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 è abilitato 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 generato 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

Enumerazioni

Const ContentType

Funzioni

openYTContent

sendScore

ytgame.engagement.Content

Proprietà

Optional contentType

id

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

`Const` ContentType

`Optional` contentType