Conexiones de red

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

Tu escena 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 escena y servir para sincronizar datos entre tus jugadores. Esto puede hacerse con un servidor que exponga una REST API, o con un servidor que use WebSockets.

Llamar a una REST API

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

Dado que el servidor puede tardar 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('failed to reach 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 petición

• init: Un FlatFetchInit objeto que puede contener:

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

  • body: Contenido del cuerpo de la petición. Debe enviarse como un objeto JSON stringificado.

  • headers: Headers adicionales a incluir en la petición. Los headers relacionados con la firma se añaden 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 una respuesta antes de que la petición 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('failed to reach URL')
	}
})

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

• headers: Un ReadOnlyHeaders objeto. Llama al get() método para obtener un header específico, o al has() método 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: A cada escena de Decentraland solo se le permite realizar una fetch comando a la vez. Esto no afecta a cómo debe estar estructurado el código de la escena, ya que las solicitudes se ponen en cola internamente. Si tu escena requiere enviar múltiples peticiones a diferentes endpoints, ten en cuenta que cada petición solo se envía cuando la anterior ha recibido respuesta.

Peticiones firmadas

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

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

Para enviar una petición firmada, todo lo que necesitas hacer es usar la signedFetch() función, de exactamente la misma manera en que usarías la fetch() función.

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')
	}
})

La petición incluye una serie adicional de headers, que contienen un mensaje firmado y un conjunto de metadatos para interpretarlo. El mensaje firmado consiste en todos los contenidos de la petición cifrados usando la clave efímera del jugador.

El signedFetch() difíere de la fetch() función en que la respuesta es una promesa de un mensaje HTTP completo, expresado como un FlatFetchResponse objeto. 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 json propiedad en la respuesta.

Validando una petición firmada

Para hacer uso de peticiones firmadas, el servidor que las recibe debe validar que las firmas coinciden con el resto de la petición, y que la marca de tiempo que está codificada dentro del mensaje firmado esté vigente.

Puedes encontrar un ejemplo sencillo de un servidor realizando esta tarea en la siguiente escena de ejemplo:

Validar la autenticidad del jugador

Tiempo de espera de la petición

Si una petición HTTP tarda demasiado en recibir respuesta, falla para que puedan enviarse otras peticiones. Para ambas fetch() y signedFetch(), el umbral de tiempo de espera por defecto es de 30 segundos, pero puedes asignar un valor diferente en cada petición 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 de un servidor WebSocket, siempre que ese servidor use una conexión segura con wss.

var socket = new WebSocket('url')

socket.onmessage = function (event) {
	console.log('WebSocket message received:', 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 detalles sobre cómo capturar y enviar mensajes a través de WebSockets.

💡 Tip: 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 facilita reaccionar a cambios y almacenar un estado de juego consistente de forma remota en el servidor. Puedes verlo en acción en estos ejemplos:

• Cube Jumper

• Space Traitor

• AI NPC

Depuración de peticiones de red

Puedes depurar las peticiones de red abriendo el Panel de depuración.

Para abrir el Panel de depuración, puedes hacer clic en el icono en la esquina superior derecha. Luego selecciona la Solicitudes web pestaña y haz clic Abrir Chrome Devtools.

Esto abrirá una nueva ventana de Chrome con la pestaña Network abierta.

Ver Depurar en vista previa para más detalles.