Conexiones de red

Cómo comunicar tu escena con servidores 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 se puede hacer 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().

// Crea un objeto factory basado en el abi
	// Pasos de configuración explicados en la sección anterior
		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 body 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 body de la petición. Debe enviarse como un objeto JSON stringificado.

  • headers: Headers adicionales para 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 body 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).

// Crea un objeto factory basado en el abi
	// Pasos de configuración explicados en la sección anterior
		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 se envió

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

• text(): Obtener el body como texto.

📔 Nota: json() y text() son mutuamente excluyentes. Si obtienes el body 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 ejecutar un fetch comando a la vez. Esto no afecta cómo debe estructurarse el código de la escena, ya que las solicitudes se encolan internamente. Si tu escena requiere enviar múltiples solicitudes a diferentes endpoints, ten en cuenta que cada solicitud solo se envía cuando la anterior ha recibido respuesta.

Solicitudes firmadas

Puedes emplear una medida de seguridad adicional para certificar que una petición se origina desde 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 en función de la dirección del jugador. El servidor que recibe la petición puede entonces verificar que el mensaje firmado coincide 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 solicitud firmada, todo lo que necesitas hacer es usar la signedFetch() función, de exactamente la misma manera que usarías la fetch() función.

// Crea un objeto factory basado en el abi
	// Pasos de configuración explicados en la sección anterior
		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 todo el contenido de la petición cifrado usando la clave efímera del jugador.

El signedFetch() difiere 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 parsear como en el ejemplo anterior. Si el body de la respuesta está en formato json, puedes especificarlo en el responseBodyType y luego acceder a eso desde la json propiedad en la response.

Validar una solicitud firmada

Para hacer uso de solicitudes firmadas, el servidor que las reciba debe validar que las firmas coinciden con el resto de la petición, y que la marca temporal que está codificada dentro del mensaje firmado esté actual.

Puedes encontrar un ejemplo simple de un servidor que realiza esta tarea en la siguiente escena de ejemplo:

Validar autenticidad del jugador

Tiempo de espera de la petición

Si una petición HTTP tarda demasiado en responder, falla para que otras solicitudes puedan enviarse. 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 solicitud 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('WebSocket message received:', event)
}

La sintaxis para usar WebSockets no difiere de la implementada nativamente por JavaScript. Consulta la documentación de Mozilla Web API para detalles sobre cómo recibir y enviar mensajes a través de WebSockets.

💡 Consejo: Una librería que simplifica el uso de conexiones websocket y que ha demostrado funcionar muy bien con Decentraland es Colyseus. Varias otras librerías de 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 remotamente en el servidor. Puedes verlo en acción en estos ejemplos:

• Cube Jumper

• Space Traitor

• AI NPC

Depuración de solicitudes de red

Puedes depurar las solicitudes 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 pestaña y haz clic Open Chrome Devtools.

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

Ver Depurar en preview para más detalles.