Documentação da ferramenta

Como funciona um feed personalizado do Bluesky e como o depurar

As peças de um feed personalizado do Bluesky: o registo, o DID do serviço, o serviço #bsky_fg, feed esqueleto e hidratado, e como corrigir cada verificação.

As peças de um feed personalizado

Um feed personalizado tem duas metades, que vivem em sítios diferentes:

  • O registo, app.bsky.feed.generator, na conta do seu criador: o nome, a descrição, o avatar e um campo did que indica o gerador de feeds que o serve. O seu endereço é o URI AT do feed, at://<criador>/app.bsky.feed.generator/<rkey>, e a sua ligação bsky.app é https://bsky.app/profile/<criador>/feed/<rkey>.
  • O gerador de feeds, um servidor identificado por esse DID (um did:web ou um did:plc). O seu documento DID tem um serviço com o id #bsky_fg e o tipo BskyFeedGenerator, cujo serviceEndpoint é o endereço https do servidor.

Um mesmo gerador pode servir muitos feeds, cada um a partir do seu próprio registo.

Feed esqueleto e feed hidratado

Quando alguém abre um feed, a aplicação pede app.bsky.feed.getFeed à AppView do Bluesky. A AppView lê o registo, resolve o DID do gerador, encontra o seu endpoint #bsky_fg e chama aí app.bsky.feed.getFeedSkeleton. O gerador responde com um esqueleto: uma lista de URI de publicações, nada mais.

json
{
  "feed": [
    { "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
  ],
  "cursor": "1731567000000"
}

Depois a AppView hidrata-o: obtém cada publicação, o autor e os números, aplica bloqueios, silenciamentos e etiquetas, e devolve publicações completas. O gerador não sabe quem lê o feed, a não ser que a pessoa tenha sessão iniciada: nesse caso o pedido leva um token que a identifica.

A AppView também acompanha cada gerador: isOnline indica que o contactou recentemente, isValid que as respostas tinham a forma certa. O inspetor de feeds mostra ambos.

O documento DID

Para um did:web, o documento é servido em https://<anfitrião>/.well-known/did.json; para um did:plc, é o diretório PLC que o guarda. Um documento 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"
    }
  ]
}

O gerador também tem de responder a app.bsky.feed.describeFeedGenerator com o mesmo DID e o URI AT de cada feed que serve.

A verificação, passo a passo

A verificação do inspetor só é executada quando a pede, e segue o mesmo caminho que a AppView:

  1. DID do serviço. O did do registo tem de ser um did:web sobre um nome de anfitrião simples (sem porta nem caminho) ou um did:plc. Caso contrário, volte a publicar o registo com o DID certo.
  2. Serviço #bsky_fg. O documento DID tem de existir, ser um JSON válido cujo id é o DID, e ter um serviço #bsky_fg do tipo BskyFeedGenerator com um endpoint https.
  3. describeFeedGenerator. GET <endpoint>/xrpc/app.bsky.feed.describeFeedGenerator tem de responder 200 com um did igual ao DID do serviço e uma lista feeds.
  4. O feed está incluído. O URI AT do feed deveria estar nessa lista feeds. Se faltar, é um aviso: alguns geradores servem feeds que não incluem.
  5. getFeedSkeleton. GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1 tem de responder 200 com uma lista feed. Um 401 significa que o feed precisa de uma pessoa com sessão iniciada: funciona na aplicação, mas não para leitores sem sessão nem na pré-visualização do inspetor.

Cada pedido tem 4 segundos e 64 KB, e o tempo que demorou é mostrado. Os pedidos passam pelos nossos controlos de segurança: só https na porta 443, e nunca para um endereço privado ou local. Um gerador numa rede doméstica ou atrás de um túnel para localhost falha a verificação mesmo quando a aplicação o alcança por um endereço público.

Correções habituais

  • Offline, mas o servidor funciona: verifique o endpoint no documento DID (um erro de escrita, http:// em vez de https://, um caminho a mais) e se o certificado é válido para esse anfitrião.
  • Válido é false: o esqueleto tem de ser um objeto com uma lista feed de elementos { "post": "<uri at>" }; campos a mais não fazem mal, outras formas sim.
  • A pré-visualização está vazia mas o esqueleto não: as publicações devolvidas podem estar apagadas, ser de contas bloqueadas ou retiradas, ou de autores que só partilham com pessoas com sessão iniciada.
  • Funcionava e deixou de funcionar: um gerador did:web que mudou de anfitrião tem de atualizar o documento DID; um did:plc precisa de uma operação PLC.

O tutorial de feeds personalizados do protocolo AT e o kit inicial do Bluesky explicam como criar um. O Bluesky.bot tem o seu próprio gerador para o feed de bots; o seu documento DID está em /.well-known/did.json.

Inspetor de feeds

Pré-visualize um feed personalizado e descubra porque não mostra nada.