Amigos gestiona el acceso a la cuenta, las solicitudes y el perfil. Tu módulo puede abrir sus formularios, añadir acciones junto a los amigos o recibir avisos de cambios.
Probarlo en Studio
- Abre modules/friends o crea un proyecto con Amigos (simulación).
- En el visor, pulsa Amigos junto al buscador de Biblioteca o Guardados. También puedes abrirlo desde la sección CUENTA de Ajustes.
- Accede con demo@nelkano.test y Nelkano123, o registra una cuenta ficticia.
- Busca otro usuario escribiendo al menos dos caracteres y prueba las solicitudes.
- Abre Editar perfil para cambiar el nombre, estado o color.
Puedes enviar, cancelar, aceptar y rechazar solicitudes, y eliminar amistades con confirmación. El rol no es editable y la foto es simulada. Las cuentas y amistades de Studio se reinician al cerrar el servidor de desarrollo: no se consulta nelkano.com ni se envían correos. Utiliza credenciales de prueba.
Usar la cuenta en la app
Abre Amigos desde Biblioteca o Guardados, o pulsa Iniciar sesión en Ajustes → General → CUENTA. Accede con tu cuenta de nelkano.com; si te registras, actívala desde el correo. Una vez dentro puedes gestionar amistades y editar el perfil con foto. El rol lo decide el servidor.
Crear tus propios formularios de acceso
const account = await host.account.snapshot();
await host.account.login({email, password});
await host.account.register({name, email, password,
password_confirm: confirmation, terms: true});
await host.account.logout();Declara account.session. La identidad pública incluye uid, signedIn, nombre, correo, permiso friends y rol. El módulo define sus formularios y validaciones; los tokens los conserva la app.
Consultar una ruta de cuenta autorizada
const account = await host.account.snapshot();
const response = await host.network.request({
method: "GET", path: "/api/nelkano/friends",
accountUid: account.uid
});Declara network.account. La app comprueba la cuenta de la petición y devuelve status y body. Android realiza la petición autenticada; Studio devuelve datos ficticios. Para un servidor propio utiliza las conexiones externas y sus permisos.
Seleccionar una foto
const image = await host.resources.pickImage();
if (!image.cancelled) {
// Conserva image.resourceId hasta guardar el perfil.
}Requiere resources.image. Recibes una referencia del host y, si está disponible, una vista previa. La imagen se publica al guardar el perfil con avatarResource en POST /api/nelkano/profile; elegirla no la publica.
Se admiten PNG, JPEG y WebP de hasta 4 MiB. La referencia pertenece al módulo y a la cuenta que la eligieron y caduca a los diez minutos. Las filas pueden mostrar avatar.url; Android descarga las imágenes de nelkano.com/sites/ y Studio utiliza una foto simulada.
Conservar la sesión
Android cifra la sesión con Android Keystore, valida los permisos firmados y renueva los tokens. Cerrar sesión elimina la copia local e intenta revocarla en el servidor. Los tokens no llegan al módulo.
Integrarte con Amigos
Declara modules.hooks y añade a consumes el proveedor nelkano.friends, el nombre del gancho y la versión 1.0.0. Usa optional:false si tu módulo necesita Amigos activo.
Añadir una acción a un amigo
await host.hooks.contribute("nelkano.friends", "friend-actions", "invite", {label: "Invitar a mi mundo", scope: "friends"});- scope: friends, incoming, outgoing o search. Si lo omites, la acción aparece en todos.
- shortLabel: etiqueta compacta opcional de 1 a 32 caracteres. Si falta, se utiliza label.
- Callback: Amigos llama a onHook con hook friend-actions, operation execute y value {accountUid, friend, scope}. contributionId identifica tu botón.
- Respuesta: devuelve {message} para mostrar el resultado.
Implementa la acción en tu módulo: el ejemplo solo añade el botón de invitación. Las acciones se retiran al desactivarlo y se rechazan si la cuenta o la lista han cambiado.
Consultar las amistades
const data = await host.hooks.invoke("nelkano.friends", "friends-data", "refresh", {});refresh consulta el servidor y requiere sesión. snapshot devuelve lo ya cargado: una lista vacía no confirma que se haya consultado el servidor.
La respuesta incluye revision, account y las listas friends, incoming y outgoing. Cada usuario tiene uid, name, statusText, avatarColor y avatarUrl. No se comparten correo, contraseña ni tokens.
Recibir cambios
await host.hooks.contribute("nelkano.friends", "friends-events", "changes", {});Amigos llama a onHook con operation changed y un value que incluye el snapshot y type: session-changed, friends-updated o profile-updated. Conserva esos datos; evita llamar de vuelta a Amigos dentro del mismo callback.
Son avisos de las operaciones del módulo, no presencia en tiempo real ni notificaciones push. Se admiten hasta 16 acciones y 8 receptores. El fallo de un receptor no interrumpe la operación principal.
Ejecutar el ejemplo de integración
- Ejecuta .\nelkmod.cmd example friends-hooks C:/mis-modulos/mi-integracion.
- Carga Amigos y el ejemplo en Studio.
- Pulsa Invitar a mi mundo (ejemplo) junto a un amigo y comprueba la respuesta.
El ejemplo demuestra la llamada, sin crear un mundo ni enviar una invitación real. Se exporta por separado. Para conectar jugadores, consulta el capítulo Multijugador.
Abrir los formularios de Amigos
Consume account-access 1.0.0 de nelkano.friends:
- open: devuelve el modal de acceso o la lista de Amigos, según la sesión.
- dispatch: recibe {action, payload} y ejecuta las acciones del formulario. Conserva sus actionId al reenviarlas.
- snapshot: devuelve la identidad pública.
El modal mantiene el contexto de la pantalla de origen. Utiliza kind:panel, layout:form, un ID estable por cuenta y dismissAction:close. Cerrar conserva sesión, búsqueda, pestaña y listas; cambiar de cuenta inicia un borrador nuevo.
La búsqueda es global, por nombre o correo. Espera 350 ms tras escribir y necesita al menos dos caracteres. Las pestañas separan Amigos y Solicitudes; el contador muestra las recibidas pendientes y las enviadas tienen su propia sección. Eliminar amigo está en ⋮ y pide confirmación. La conexión entre jugadores se abre desde el modal de Multijugador.