Referência do SDK da Sala de jogos do YouTube

ytgame

O namespace de nível superior do SDK da Sala de jogos do YouTube.

Essa é uma variável de escopo global na janela atual. Você NÃO PODE substituir essa variável.

Namespaces
`ads`	🧪 API DE PRÉ-LANÇAMENTO PÚBLICO: SUJEITA A ALTERAÇÕES SEM AVISO PRÉVIO.
`engagement`	As funções e propriedades relacionadas ao engajamento do jogador.
`game`	As funções e propriedades relacionadas a comportamentos genéricos de jogos.
`health`	As funções e propriedades relacionadas à integridade do jogo.
`system`	As funções e propriedades relacionadas ao sistema do YouTube.

Enumerações
`SdkErrorType`	Os tipos de erros que o SDK da Sala de jogos do YouTube gera.

Classes
`SdkError`	O objeto de erro gerado pelo SDK da Sala de jogos do YouTube.

Variáveis
`IN_PLAYABLES_ENV`	Indica se o jogo está sendo executado no ambiente da Sala de Jogos.
`SDK_VERSION`	A versão do SDK da Sala de jogos do YouTube.

Consulte também

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

Enumerações

`Const` SdkErrorType

SdkErrorType

Os tipos de erros que o SDK da Sala de jogos do YouTube gera.

Membros da enumeração
`API_UNAVAILABLE`	A API ficou temporariamente indisponível. Peça aos jogadores para tentar de novo mais tarde se estiverem em um fluxo crítico.
`INVALID_PARAMS`	A API foi chamada com parâmetros inválidos.
`SIZE_LIMIT_EXCEEDED`	A API foi chamada com parâmetros que excedem o limite de tamanho.
`UNKNOWN`	O tipo de erro é desconhecido.

Variáveis

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

Indica se o jogo está sendo executado no ambiente da Sala de Jogos. Você pode usar isso para determinar se deve ativar ou desativar recursos que estão disponíveis apenas na Sala de jogos. Combine essa verificação com a de ytgame para garantir que o SDK seja carregado.

Exemplo

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

A versão do SDK da Sala de jogos do YouTube.

Exemplo

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

ytgame.SdkError

Extends Error

O objeto de erro gerado pelo SDK da Sala de jogos do YouTube.

O objeto SdkError é um filho de Error e contém um campo adicional.

Construtores
`constructor`

Propriedades
`errorType`	O tipo do erro.
`message`
`name`
`stack?`

Propriedades

errorType

errorType:
                  SdkErrorType

O tipo do erro.

ytgame.ads

🧪 API DE PRÉ-LANÇAMENTO PÚBLICO: SUJEITA A ALTERAÇÕES SEM AVISO PRÉVIO.

As funções e propriedades relacionadas a anúncios.

Funções
`requestInterstitialAd`	Solicita a exibição de um anúncio intersticial.
`requestRewardedAd`	Solicita que um anúncio premiado seja mostrado para um tipo específico de recompensa.

Funções

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Solicita a exibição de um anúncio intersticial.

🧪 API DE PRÉVIA PÚBLICA: SUJEITA A ALTERAÇÕES SEM AVISO PRÉVIO.

Não garante se o anúncio foi mostrado. Não use essa API para recompensar jogadores por assistir a um anúncio.

Exemplo

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

Retorna
`Promise<void>`	uma promessa que é resolvida em uma solicitação bem-sucedida ou rejeita/gera uma exceção em uma solicitação sem êxito.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Solicita que um anúncio premiado seja mostrado para um tipo de recompensa específico.

🧪 API DE PRÉVIA PÚBLICA: SUJEITA A ALTERAÇÕES SEM AVISO PRÉVIO.

Não oferece garantias sobre se o anúncio foi mostrado.

Exemplo

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

Parâmetros
`rewardId: string`	Obrigatório. Um identificador que identifica exclusivamente o tipo de recompensa resgatável. Use um ID exclusivo para cada tipo de recompensa e reutilize o mesmo ID sempre que esse tipo específico for oferecido. Exemplo: 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 moedas" 7defcfa2-4312-4893-a13a-a84e0c47a4df: "3 vidas" 121b001a-0c25-4289-88f6-58e3620d938f: "Pular nível"

Retorna
`Promise<boolean>`	Uma promessa que é resolvida em uma solicitação bem-sucedida com o valor "true" se o usuário atender às condições para receber uma recompensa ou "false" se não atender. A promessa rejeita/gera uma exceção em uma solicitação sem êxito.

ytgame.engagement

As funções e propriedades relacionadas ao engajamento do jogador.

Interfaces
`Score`	O objeto de pontuação que o jogo envia ao YouTube.

Funções
`sendScore`	Envia uma pontuação para o YouTube.

Funções

sendScore

sendScore(score: Score): Promise<void>

Envia uma pontuação para o YouTube.

A pontuação deve representar uma dimensão do progresso no jogo. Se houver várias dimensões, o desenvolvedor precisará escolher uma para manter a consistência. As pontuações serão classificadas, e a maior pontuação será exibida na interface do YouTube. Portanto, qualquer interface de maior pontuação no jogo precisa estar alinhada com o que está sendo enviado pela API.

Exemplo

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

Parâmetros
`score: Score`	a pontuação a ser enviada ao YouTube.

Retorna
`Promise<void>`	Uma promessa que é resolvida quando a operação é bem-sucedida e rejeita/gera um `ytgame.SdkError` quando falha.

ytgame.engagement.Score

O objeto de pontuação que o jogo envia ao YouTube.

Propriedades
`value`	O valor da pontuação expresso como um número inteiro.

Propriedades

value

value: number

O valor da pontuação expresso como um número inteiro. A pontuação precisa ser menor ou igual ao número inteiro seguro máximo. Caso contrário, a pontuação será rejeitada.

ytgame.game

As funções e propriedades relacionadas a comportamentos genéricos de jogos.

Funções
`firstFrameReady`	Notifica o YouTube de que o jogo começou a mostrar frames.
`gameReady`	Notifica o YouTube de que o jogo está pronto para interação dos jogadores.
`loadData`	Carrega dados do jogo do YouTube na forma de uma string serializada.
`saveData`	Salva dados do jogo no YouTube na forma de uma string serializada.

Funções

firstFrameReady

firstFrameReady(): void

Notifica o YouTube de que o jogo começou a mostrar frames.

O jogo PRECISA chamar essa API. Caso contrário, o jogo não será mostrado aos usuários. firstFrameReady() PRECISA ser chamado antes de gameReady().

Exemplo

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

gameReady

gameReady(): void

Notifica o YouTube de que o jogo está pronto para interação dos jogadores.

O jogo PRECISA chamar essa API quando estiver interativo. O jogo NÃO PODE chamar essa API quando uma tela de carregamento ainda estiver sendo mostrada. Caso contrário, o jogo não vai passar no processo de certificação do YouTube.

Exemplo

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

loadData

loadData(): Promise<string>

Carrega dados do jogo do YouTube na forma de uma string serializada.

O jogo precisa processar qualquer análise entre a string e um formato interno.

Exemplo

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

Retorna
`Promise<string>`	Uma promessa que é concluída quando o carregamento é bem-sucedido e é rejeitada com um `ytgame.SdkError` quando falha.

saveData

saveData(data: string): Promise<void>

Salva dados do jogo no YouTube na forma de uma string serializada.

A string precisa ser válida, bem formada em UTF-16 e ter um máximo de 3 MiB. O jogo precisa processar qualquer análise entre a string e um formato interno. Se necessário, use String.isWellFormed() para verificar se a string está bem formada.

Exemplo

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

Parâmetros
`data: string`

Retorna
`Promise<void>`	Uma promessa que é resolvida quando o salvamento é bem-sucedido e rejeitada com um `ytgame.SdkError` quando falha.

ytgame.health

As funções e propriedades relacionadas à integridade do jogo.

Funções
`logError`	Registra um erro no YouTube.
`logWarning`	Registra um aviso no YouTube.

Funções

logError

logError(): void

Registra um erro no YouTube.

Observação:essa API é de melhor esforço e tem limite de taxa, o que pode resultar em perda de dados.

Exemplo

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

logWarning

logWarning(): void

Registra um aviso no YouTube.

Observação:essa API é de melhor esforço e tem limitação de taxa, o que pode resultar em perda de dados.

Exemplo

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

ytgame.system

As funções e propriedades relacionadas ao sistema do YouTube.

Funções
`getLanguage`	Retorna o idioma definido nas configurações do YouTube do usuário na forma de uma tag de idioma BCP-47.
`isAudioEnabled`	Retorna se o áudio do jogo está ativado nas configurações do YouTube.
`onAudioEnabledChange`	Define um callback para ser acionado quando o evento de mudança nas configurações de áudio for disparado pelo YouTube.
`onPause`	Define um callback que será acionado quando um evento de pausa do jogo for disparado no YouTube.
`onResume`	Define um callback para ser acionado quando um evento de retomada de jogo é disparado no YouTube.

Funções

getLanguage

getLanguage(): Promise<string>

Retorna o idioma definido nas configurações do YouTube do usuário na forma de uma tag de idioma BCP-47.

Não use outras funções para determinar o idioma ou a localidade do usuário nem armazene a preferência de idioma dele no salvamento na nuvem. Em vez disso, use esta função para garantir que a experiência do usuário seja consistente em todo o YouTube.

Exemplo

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

Retorna
`Promise<string>`	Uma promessa que é concluída quando a recuperação do idioma é bem-sucedida e é rejeitada com um `ytgame.SdkError` quando falha.

isAudioEnabled

isAudioEnabled(): boolean

Retorna se o áudio do jogo está ativado nas configurações do YouTube.

O jogo DEVE usar isso para inicializar o estado do áudio do jogo.

Exemplo

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

Retorna
`boolean`	um booleano que indica se o áudio está ativado.

onAudioEnabledChange

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

Define um callback para ser acionado quando o evento de mudança nas configurações de áudio for disparado pelo YouTube.

O jogo PRECISA usar essa API para atualizar o estado de áudio do jogo.

Exemplo

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

Parâmetros
`callback: ((isAudioEnabled: boolean) => void)`	a função de callback a ser acionada.

Retorna
`(() => void)`	uma função para remover o callback, que geralmente não é usado.

onPause

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

Define um callback que será acionado quando um evento de pausa do jogo for disparado no YouTube. O jogo tem uma janela curta para salvar qualquer estado antes de ser removido.

onPause é chamado para todos os tipos de pausas, inclusive quando o usuário sai do jogo. Não há garantia de que o jogo será retomado.

Exemplo

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

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

Parâmetros
`callback: (() => void)`	a função de callback a ser acionada.

Retorna
`(() => void)`	uma função para remover o callback, que geralmente não é usado.

onResume

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

Define um callback para ser acionado quando um evento de retomada do jogo é disparado no YouTube.

Depois de ser pausado, não há garantia de que o jogo será retomado.

Exemplo

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

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

Parâmetros
`callback: (() => void)`	a função de callback a ser acionada.

Retorna
`(() => void)`	uma função para remover o callback, que geralmente não é usado.

Referência do SDK da Sala de jogos do YouTube Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

ytgame

Enumerações

Const SdkErrorType

Variáveis

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Propriedades

errorType

ytgame.ads

Funções

requestInterstitialAd

requestRewardedAd

ytgame.engagement

Funções

sendScore

ytgame.engagement.Score

Propriedades

value

ytgame.game

Funções

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Funções

logError

logWarning

ytgame.system

Funções

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Referência do SDK da Sala de jogos do YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION