Conexões de rede

Como comunicar sua cena com servers externos e APIs.

A sua scene pode aproveitar serviços externos que expõem APIs; pode usar isto para obter dados de preços atualizados, dados meteorológicos ou qualquer outro tipo de informação exposta por uma API.

Também pode configurar o seu próprio servidor externo para ajudar a sua scene e servir para sincronizar dados entre os seus players. Isto pode ser feito com um servidor que expõe uma API REST ou com um servidor que usa WebSockets.

Chamar uma API REST

O código da sua scene pode enviar chamadas para uma API REST para obter dados.

Como o servidor pode demorar algum tempo a enviar a sua resposta, deve executar este comando como uma função assíncrona, usando executeTask().

executeTask(async () => {
	try {
		let response = await fetch(callUrl)
		let json = await response.json()
		console.log(json)
	} catch {
		console.log('failed to reach URL')
	}
})

O comando fetch também pode incluir um segundo argumento opcional que agrega headers, o método HTTP e o corpo HTTP num único objeto.

• url: Endereço para enviar o request

• init: Um FlatFetchInit objeto que pode conter:

  • method : Método HTTP a usar (GET, POST, DELETE, etc)

  • body: Conteúdo do corpo do request. Deve ser enviado como um objeto JSON serializado em string.

  • headers: Headers adicionais a incluir no request. Os headers relacionados com a assinatura são adicionados automaticamente.

  • redirect: Estratégia de redirecionamento ('follow' | 'error' | 'manual')

  • responseBodyType: Especifica se o corpo da resposta é 'text' ou 'json'

  • timeout: Quanto tempo esperar por uma resposta antes de o request falhar. Por predefinição, 30000 milissegundos (30 segundos).

executeTask(async () => {
	try {
		let response = await fetch(callUrl, {
			headers: { 'Content-Type': 'application/json' },
			method: 'POST',
			body: JSON.stringify(myBody),
		})
		let json = await response.json()
		console.log(json)
	} catch {
		console.log('failed to reach URL')
	}
})

O comando fetch devolve um response objeto com os seguintes dados:

• headers: Um ReadOnlyHeaders objeto. Chame o get() método para obter um header específico, ou o has() método para verificar se um header está presente.

• ok: Boolean

• redirected: Boolean

• status: Número do código de estado

• statusText: Texto para o código de estado

• type: Terá um dos seguintes valores: basic, cors, default, error, opaque, opaqueredirect

• url: URL que foi enviada

• json(): Obtém o corpo em formato JSON.

• text(): Obtém o corpo como texto.

📔 Nota: json() e text() são mutuamente exclusivos. Se obtiver o corpo da resposta num dos dois formatos, já não poderá obter o outro a partir do response objeto.

📔 Nota: Cada scene do Decentraland só tem permissão para executar um comando fetch de cada vez. Isto não afeta a forma como o código da scene deve ser estruturado, pois os requests são enfileirados internamente. Se a sua scene exigir o envio de vários requests para diferentes endpoints, tenha em conta que cada request só é enviado quando o anterior tiver recebido resposta.

Requests assinados

Pode empregar uma medida de segurança extra para certificar que um request está a ser originado de uma sessão de player dentro do Decentraland. Pode enviar os seus requests com uma assinatura adicional, assinada usando uma chave efémera que a sessão do Decentraland gera para cada player com base no endereço do player. O servidor que recebe o request pode então verificar que a mensagem assinada corresponde de facto a um endereço que está atualmente ativo no world.

Este tipo de medidas de segurança é especialmente valioso quando pode haver um incentivo para que um player abuse do sistema, para farmar tokens ou pontos num jogo.

Para enviar um request assinado, tudo o que precisa de fazer é usar a signedFetch() função, exatamente da mesma forma que usaria a fetch() function.

executeTask(async () => {
	try {
		let response = await signedFetch({
			url: callUrl,
			init: {
				headers: { 'Content-Type': 'application/json' },
				method: 'POST',
				body: JSON.stringify(myBody),
			},
		})

		if (!response.statusText) {
			throw new Error('Invalid response')
		}

		let json = await JSON.parse(response.statusText)

		console.log('Response received: ', json)
	} catch {
		console.log('failed to reach URL')
	}
})

O request inclui uma série adicional de headers, contendo uma mensagem assinada e um conjunto de metadata para a interpretar. A mensagem assinada consiste em todo o conteúdo do request encriptado usando a chave efémera do player.

O signedFetch() difere da fetch() função no facto de a resposta ser uma promise de uma mensagem HTTP completa, expressa como um FlatFetchResponse objeto. Isto inclui as seguintes propriedades:

• body

• headers

• ok

• status

• statusText

Por predefinição, body é considerado uma string, que pode analisar como no exemplo acima. Se o corpo da resposta estiver em formato json, pode especificá-lo no responseBodyType e depois aceder a isso a partir da json propriedade na resposta.

Validar um request assinado

Para tirar partido dos requests assinados, o servidor que os recebe deve validar que as assinaturas correspondem ao resto do request e que o timestamp codificado na mensagem assinada é atual.

Pode encontrar um exemplo simples de um servidor a realizar esta tarefa na seguinte scene de exemplo:

Validar a autenticidade do player

Timeout do request

Se um request HTTP demorar demasiado a receber resposta, falha para que outros requests possam ser enviados. Tanto para fetch() e signedFetch(), o timeout predefinido é de 30 segundos, mas pode atribuir um valor diferente em cada request configurando a timeout property em qualquer uma das duas funções. O valor de timeout é expresso em milissegundos.

fetch('https://some-url.com', { timeout: 1000 })

Usar WebSockets

Também pode enviar e obter dados de um servidor WebSocket, desde que este servidor use uma ligação segura com wss.

var socket = new WebSocket('url')

socket.onmessage = function (event) {
	console.log('WebSocket message received:', event)
}

A sintaxe para usar WebSockets não é diferente da implementada nativamente por JavaScript. Consulte a documentação de Mozilla Web API para obter detalhes sobre como receber e enviar mensagens através de WebSockets.

💡 Dica: Uma biblioteca que simplifica a utilização de ligações websocket e que demonstrou funcionar muito bem com Decentraland é Colyseus. Várias outras bibliotecas websocket não são compatíveis com o SDK do Decentraland.

Constrói uma camada de abstração sobre as ligações websocket que torna muito simples reagir a alterações e armazenar remotamente um estado de jogo consistente no servidor. Pode vê-la em ação nestes exemplos:

• Cube Jumper

• Space Traitor

• AI NPC

Depurar requests de rede

Pode depurar requests de rede abrindo o Debug Panel.

Para abrir o Debug Panel, pode clicar no ícone no canto superior direito. Depois selecione o separador Pedidos Web e clique em Open Chrome Devtools.

Isto abrirá uma nova janela do Chrome com o separador Network aberto.

Veja Depurar na preview para mais detalhes.