Documentación de la herramienta

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 campo did que 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 es https://bsky.app/profile/<creador>/feed/<rkey>.
  • El generador de feeds, un servidor identificado por ese DID (un did:web o un did:plc). Su documento DID tiene un servicio con el id #bsky_fg y el tipo BskyFeedGenerator, cuyo serviceEndpoint es 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.

json
{
  "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:

json
{
  "@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:

  1. DID del servicio. El did del registro debe ser un did:web sobre un nombre de host solo (sin puerto ni ruta) o un did:plc. Si no, vuelve a publicar el registro con el DID correcto.
  2. Servicio #bsky_fg. El documento DID debe existir, ser un JSON válido cuyo id sea el DID, y tener un servicio #bsky_fg de tipo BskyFeedGenerator con un endpoint https.
  3. describeFeedGenerator. GET <endpoint>/xrpc/app.bsky.feed.describeFeedGenerator debe responder 200 con un did igual al DID del servicio y una lista feeds.
  4. 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.
  5. getFeedSkeleton. GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1 debe responder 200 con un array feed. 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 de https://, 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 feed de 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:web que cambió de host debe actualizar su documento DID; uno did:plc necesita 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.

Inspector de feeds

Previsualiza un feed personalizado y descubre por qué no muestra nada.