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 campodidque 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:webou umdid:plc). O seu documento DID tem um serviço com o id#bsky_fge o tipoBskyFeedGenerator, cujoserviceEndpointé 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.
{
"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:
{
"@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:
- DID do serviço. O
diddo registo tem de ser umdid:websobre um nome de anfitrião simples (sem porta nem caminho) ou umdid:plc. Caso contrário, volte a publicar o registo com o DID certo. - Serviço
#bsky_fg. O documento DID tem de existir, ser um JSON válido cujoidé o DID, e ter um serviço#bsky_fgdo tipoBskyFeedGeneratorcom um endpoint https. describeFeedGenerator.GET <endpoint>/xrpc/app.bsky.feed.describeFeedGeneratortem de responder 200 com umdidigual ao DID do serviço e uma listafeeds.- 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. getFeedSkeleton.GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1tem de responder 200 com uma listafeed. 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 dehttps://, 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
feedde 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:webque mudou de anfitrião tem de atualizar o documento DID; umdid:plcprecisa 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.