Cómo funciona un feed personalizado de Bluesky y cómo depurarlo
Las piezas de un feed personalizado de Bluesky: el registro, el DID del servicio, el servicio #bsky_fg, feed esqueleto e hidratado, y cómo arreglar cada revisión.
Las piezas de un feed personalizado
Un feed personalizado tiene dos mitades, que viven en sitios distintos:
- El registro,
app.bsky.feed.generator, en la cuenta de su creador: su nombre, descripción, avatar y un campodidque nombra el generador de feeds que lo sirve. Su dirección es la URI AT del feed,at://<creador>/app.bsky.feed.generator/<rkey>, y su enlace de bsky.app eshttps://bsky.app/profile/<creador>/feed/<rkey>. - El generador de feeds, un servidor identificado por ese DID (un
did:webo undid:plc). Su documento DID tiene un servicio con el id#bsky_fgy el tipoBskyFeedGenerator, cuyoserviceEndpointes la dirección https del servidor.
Un mismo generador puede servir muchos feeds, cada uno desde su propio registro.
Feed esqueleto y feed hidratado
Cuando alguien abre un feed, la app pide app.bsky.feed.getFeed a la AppView de Bluesky. La AppView lee el registro, resuelve el DID del generador, encuentra su endpoint #bsky_fg y llama allí a app.bsky.feed.getFeedSkeleton. El generador responde con un esqueleto: una lista de URI de publicaciones, nada más.
{
"feed": [
{ "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
],
"cursor": "1731567000000"
}Después la AppView lo hidrata: obtiene cada publicación, su autor y sus cifras, aplica bloqueos, silencios y etiquetas, y devuelve publicaciones completas. El generador no sabe quién lee el feed salvo que la persona haya iniciado sesión: entonces la petición lleva un token que la identifica.
La AppView también sigue cada generador: isOnline indica que lo contactó hace poco, isValid que sus respuestas tenían la forma correcta. El inspector de feeds muestra ambos.
El documento DID
Para un did:web, el documento se sirve en https://<host>/.well-known/did.json; para un did:plc, lo guarda el directorio PLC. Uno mínimo:
{
"@context": ["https://www.w3.org/ns/did/v1"],
"id": "did:web:feed.example.com",
"service": [
{
"id": "#bsky_fg",
"type": "BskyFeedGenerator",
"serviceEndpoint": "https://feed.example.com"
}
]
}El generador también debe responder a app.bsky.feed.describeFeedGenerator con el mismo DID y la URI AT de cada feed que sirve.
La revisión, paso a paso
La revisión del inspector solo se ejecuta cuando la pides, y sigue el mismo camino que la AppView:
- DID del servicio. El
diddel registro debe ser undid:websobre un nombre de host solo (sin puerto ni ruta) o undid:plc. Si no, vuelve a publicar el registro con el DID correcto. - Servicio
#bsky_fg. El documento DID debe existir, ser un JSON válido cuyoidsea el DID, y tener un servicio#bsky_fgde tipoBskyFeedGeneratorcon un endpoint https. describeFeedGenerator.GET <endpoint>/xrpc/app.bsky.feed.describeFeedGeneratordebe responder 200 con undidigual al DID del servicio y una listafeeds.- El feed está incluido. La URI AT del feed debería estar en esa lista
feeds. Si falta, es un aviso: algunos generadores sirven feeds que no incluyen. getFeedSkeleton.GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1debe responder 200 con un arrayfeed. Un 401 significa que el feed necesita una persona con sesión iniciada: funciona en la app, pero no para lectores sin sesión ni en la vista previa del inspector.
Cada petición tiene 4 segundos y 64 KB, y se muestra lo que tardó. Las peticiones pasan por nuestros controles de seguridad: solo https en el puerto 443, y nunca hacia una dirección privada o local. Un generador en una red doméstica o detrás de un túnel a localhost falla la revisión aunque la app lo alcance por una dirección pública.
Arreglos habituales
- Fuera de línea, pero el servidor funciona: revisa el endpoint del documento DID (una errata,
http://en lugar dehttps://, una ruta de más) y que el certificado sea válido para ese host. - Válido es false: el esqueleto debe ser un objeto con un array
feedde elementos{ "post": "<uri at>" }; los campos extra no molestan, otras formas sí. - La vista previa está vacía pero el esqueleto no: las publicaciones devueltas pueden estar borradas, ser de cuentas bloqueadas o retiradas, o de autores que solo comparten con personas con sesión iniciada.
- Funcionaba y dejó de hacerlo: un generador
did:webque cambió de host debe actualizar su documento DID; unodid:plcnecesita una operación PLC.
El tutorial de feeds personalizados del protocolo AT y el kit de inicio de Bluesky explican cómo crear uno. Bluesky.bot tiene su propio generador para el feed de bots; su documento DID está en /.well-known/did.json.