Conexiones de red

Cómo comunicar tu scene con servers y APIs externas.

Tu scene puede aprovechar servicios externos que exponen APIs; puedes usar esto para obtener datos de precios actualizados, datos meteorológicos o cualquier otro tipo de información expuesta por una API.

También puedes configurar tu propio servidor externo para ayudar a tu scene y servir para sincronizar datos entre tus jugadores. Esto se puede hacer con un servidor que exponga una API REST o con un servidor que use WebSockets.

Llamar a una API REST

El código de tu scene puede enviar llamadas a una API REST para obtener datos.

Como el servidor puede tardar un tiempo en enviar su respuesta, debes ejecutar este comando como una función asíncrona, usando executeTask().

executeTask(async () => {
	try {
		let response = await fetch(callUrl)
		let json = await response.json()
		console.log(json)
	} catch {
		console.log('no se pudo الوصول a la URL')
	}
})

El comando fetch también puede incluir un segundo argumento opcional que agrupa headers, el método HTTP y el cuerpo HTTP en un solo objeto.

• url: Dirección a la que enviar la request

• init: Un FlatFetchInit objeto que puede contener:

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

  • body: Contenido del cuerpo de la request. Debe enviarse como un objeto JSON serializado.

  • headers: Headers adicionales para incluir en la request. Los headers relacionados con la firma se agregan automáticamente.

  • redirect: Estrategia de redirección ('follow' | 'error' | 'manual')

  • responseBodyType: Especifica si el cuerpo de la respuesta es 'text' o 'json'

  • timeout: Cuánto tiempo esperar por una respuesta antes de que la request falle. Por defecto, 30000 milisegundos (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('no se pudo الوصول a la URL')
	}
})

El comando fetch devuelve un response objeto con los siguientes datos:

• headers: Un ReadOnlyHeaders objeto. Llama al método get() para obtener un header específico, o al has() para comprobar si un header está presente.

• ok: Booleano

• redirected: Booleano

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

• statusText: Texto para el código de estado

• type: Tendrá uno de los siguientes valores: basic, cors, default, error, opaque, opaqueredirect

• url: URL que fue enviada

• json(): Obtener el cuerpo en formato JSON.

• text(): Obtener el cuerpo como texto.

📔 Nota: json() y text() son mutuamente excluyentes. Si obtienes el cuerpo de la respuesta en uno de los dos formatos, ya no puedes obtener el otro desde el response objeto.

📔 Nota: Cada scene de Decentraland solo tiene permitido realizar un comando fetch a la vez. Esto no afecta cómo debe estructurarse el código de la scene, ya que las requests se ponen en cola internamente. Si tu scene requiere enviar múltiples requests a diferentes endpoints, ten en cuenta que cada request solo se envía cuando la anterior ha recibido respuesta.

Requests firmadas

Puedes emplear una medida de seguridad adicional para certificar que una request se origina en una sesión de jugador dentro de Decentraland. Puedes enviar tus requests con una firma adicional, firmada usando una clave efímera que la sesión de Decentraland genera para cada jugador en función de la dirección del jugador. El servidor que recibe la request puede entonces verificar que el mensaje firmado realmente coincide con una dirección que está activa actualmente en el mundo.

Este tipo de medidas de seguridad son especialmente valiosas cuando puede haber un incentivo para que un jugador abuse del sistema, para farmear tokens o puntos en un juego.

Para enviar una request firmada, todo lo que necesitas hacer es usar la signedFetch() función, exactamente de la misma manera en que usarías 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('Respuesta inválida')
		}

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

		console.log('Respuesta recibida: ', json)
	} catch {
		console.log('no se pudo الوصول a la URL')
	}
})

La request incluye una serie adicional de headers, que contienen un mensaje firmado y un conjunto de metadata para interpretarlo. El mensaje firmado consiste en todo el contenido de la request cifrado usando la clave efímera del jugador.

El signedFetch() difiere de la fetch() función en que la respuesta es una promise de un mensaje HTTP completo, expresado como un objeto FlatFetchResponse . Esto incluye las siguientes propiedades:

• body

• headers

• ok

• status

• statusText

Por defecto, body se considera una cadena, que puedes analizar como en el ejemplo anterior. Si el cuerpo de la respuesta está en formato JSON, puedes especificarlo en el responseBodyType y luego acceder a eso desde la propiedad json de la respuesta.

Validar una request firmada

Para hacer uso de requests firmadas, el servidor que las recibe debe validar que las firmas coincidan con el resto de la request, y que la marca de tiempo codificada dentro del mensaje firmado sea actual.

Puedes encontrar un ejemplo sencillo de un servidor que realiza esta tarea en el siguiente ejemplo de scene:

Validar la autenticidad del jugador

Request timeout

Si una request HTTP tarda demasiado en recibir respuesta, falla para que se puedan enviar otras requests. Para ambas fetch() y signedFetch(), el umbral de timeout predeterminado es de 30 segundos, pero puedes asignar un valor diferente en cada request configurando la timeout propiedad en cualquiera de las dos funciones. El valor de timeout se expresa en milisegundos.

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

Usar WebSockets

También puedes enviar y obtener datos desde un servidor WebSocket, siempre que este servidor use una conexión segura con wss.

var socket = new WebSocket('url')

socket.onmessage = function (event) {
	console.log('Mensaje de WebSocket recibido:', event)
}

La sintaxis para usar WebSockets no es diferente de la implementada de forma nativa por JavaScript. Consulta la documentación de Mozilla Web API para obtener detalles sobre cómo capturar y enviar mensajes a través de WebSockets.

💡 Consejo: Una biblioteca que simplifica el uso de conexiones websocket y que ha demostrado funcionar muy bien con Decentraland es Colyseus. Varias otras bibliotecas websocket no son compatibles con el SDK de Decentraland.

Construye una capa de abstracción sobre las conexiones websocket que hace que reaccionar a cambios y almacenar un estado de juego coherente de forma remota en el servidor sea súper fácil. Puedes verlo en acción en estos ejemplos:

• Cube Jumper

• Space Traitor

• AI NPC

Depuración de requests de red

Puedes depurar requests de red abriendo el Debug Panel.

Para abrir el Debug Panel, puedes hacer clic en el icono en la esquina superior derecha. Luego selecciona la Solicitudes web tab y haz clic en Abrir Chrome Devtools.

Esto abrirá una nueva ventana de Chrome con la tab Network abierta.

Consulta Depurar en preview para más detalles.