Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês
Prévias de link (OGP / X Card / fediverse:creator)
As prévias que outros serviços mostram das páginas deste servidor, o que o servidor retorna para elas e os passos para verificá-las manualmente. Os cartões que este servidor mostra para os links nas próprias publicações estão em Cartões de links em publicações abaixo; como parar de buscá-los de um domínio está nas configurações da instância.
O que o servidor retorna
Seção intitulada “O que o servidor retorna”my serve retorna o HTML da página inicial (https://<host>/), da página de informações da instância (https://<host>/about),
das páginas dos documentos publicados (/about/terms, /about/privacy, /about/commerce), da página sobre o rastreador de cartões de link (/about/crawler), dos perfis
(https://<host>/@alice) e das publicações (https://<host>/@alice/status/<post ID>), embutindo meta tags no shell do
cliente web.
Uma requisição de HTML é sempre tratada como sem login, então uma prévia mostra apenas o que um visitante sem login pode ver.
| Página | Resposta |
|---|---|
A página inicial (/) e a página de informações da instância (/about) |
200. O shell com meta tags que apresentam a instância (veja “A página inicial” abaixo) |
A página sobre o rastreador de cartões de link (/about/crawler) |
200. O shell com meta tags que apresentam a instância, com o título “Rastreador de cartões de link | nome da instância” |
As páginas dos documentos publicados (/about/terms, /about/privacy, /about/commerce) |
200. O shell com meta tags que apresentam a instância, com o título “nome do documento | nome da instância”. A página de um documento que não está publicado recebe o shell genérico |
Uma publicação public, o perfil de uma conta local ativa |
200. O shell com meta tags |
Uma publicação unlisted |
200. O shell com meta tags, mais <meta name="robots" content="noindex, noarchive"> e X-Robots-Tag: noindex, noarchive |
Uma publicação local, private, direct, excluída ou inexistente, e o perfil e as publicações de uma conta suspensa, desativada, excluída ou limitada |
404. O shell genérico e X-Robots-Tag: noindex, noarchive. O corpo e os cabeçalhos são iguais seja qual for o motivo |
/@<old username>/status/<post ID> |
301, para a URL com o nome de usuário atual |
A página de uma hashtag (/tags/<tag>) |
200. O shell genérico, com o link para o feed Atom da hashtag (veja “O shell genérico” abaixo) |
| Qualquer outra página do cliente web (explorar, as páginas públicas de custos e de apoiadores, login e assim por diante) | 200. O shell genérico, com as meta tags da instância (veja “O shell genérico” abaixo) |
Toda página também leva as declarações para mecanismos de busca e rastreadores de IA (meta tags como noindex e noai, e
X-Robots-Tag, Content-Usage e tdm-reservation), conforme as configurações da instância e as do dono
(mecanismos de busca e rastreadores de IA). O noindex da tabela acima é sempre adicionado, sejam quais forem as configurações.
noindex não impede as prévias de link.
Uma requisição com um Accept do ActivityPub não recebe o shell; o lado ActivityPub a responde (um perfil responde com o
id do ator, e uma publicação que um visitante sem login pode ver responde com um 302 para o seu id). Toda resposta leva Vary: Accept.
Meta tags
Seção intitulada “Meta tags”| Tag | Conteúdo |
|---|---|
og:title, <title> |
“Nome de exibição (@nome de usuário@domínio da conta)”. O nome de usuário se o nome de exibição estiver vazio. Para um artigo, o título dele |
og:type |
profile para um perfil, article para uma publicação e um artigo |
og:url, <link rel="canonical"> |
A URL canônica (a URL com o nome de usuário atual) |
og:description |
O texto simples do corpo da publicação (a bio, para um perfil) sem tags, cortado em 200 grafemas. Para uma publicação com aviso de conteúdo, apenas o texto do aviso de conteúdo. Para um artigo, o resumo dele, também quando está marcado como sensível; o corpo de um artigo nunca está na página |
og:image, og:image:alt / width / height |
A imagem escolhida na ordem abaixo |
og:site_name |
O nome da instância (o texto name, igual em todos os idiomas; host quando não há; nome e domínio) |
og:locale, <html lang dir> |
O idioma da publicação. Quando não está definido (und), o idioma padrão de publicação do autor e, na falta dele, o default_locale da instância. Não muda com Accept-Language. og:locale tem a forma language_TERRITORY: um idioma sem região recebe a região usual dele (ja → ja_JP, en → en_US, pt → pt_BR), e <html lang> mantém a tag de idioma como está |
article:published_time, article:author |
Apenas publicações. O horário da publicação (UTC) e a URL do perfil do autor |
profile:username |
Apenas perfis. username@account domain |
twitter:card |
summary_large_image quando a imagem é mais larga que cerca de 2:1 (largura / altura >= 1,7) e tem pelo menos 300x157, caso contrário summary |
fediverse:creator |
@username@account domain. O Mastodon o mostra como “autor” |
<link rel="alternate" type="application/activity+json"> |
O id do AP (o ator ou o objeto da publicação) |
<link rel="alternate" type="application/atom+xml"> |
Apenas perfis que têm um feed Atom: o endereço do feed (https://<host>/@<username>.atom), com o título igual ao de og:title. Um perfil cujo dono desativou o feed, e uma conta limitada ou que se mudou, não têm nenhum |
As meta tags da página inicial apresentam a própria instância.
og:typeéwebsite,og:title,<title>eog:site_namesão o nome da instância, eog:urle<link rel="canonical">sãohttps://<host>/.og:descriptioné o texto da instânciashort_descriptioncortado em 200 grafemas. É omitido quando não há.- O idioma (
og:locale,<html lang dir>) é odefault_localeda instância. O nome e a descrição são o mesmo valor em todos os idiomas. og:imageé a imagem da instância: o número 3 abaixo, ou o número 4, 5 ou 6 se não houver.- Ela não pertence a uma conta, então
fediverse:creatore oalternatedo ActivityPub não são gerados. - A página de informações da instância (
/about) tem as mesmas meta tags.og:titlee<title>são “Sobre {nome da instância}” (server:preview.about_title), eog:urle<link rel="canonical">sãohttps://<host>/about. - As páginas dos documentos publicados (
/about/terms,/about/privacy,/about/commerce) também têm as mesmas meta tags.og:titlee<title>são “{nome do documento} | {nome da instância}” (server:preview.document_title), eog:urle<link rel="canonical">são o endereço dessa página. A página de um documento que não está publicado recebe o shell genérico. - A página sobre o rastreador de cartões de link (
/about/crawler) tem as mesmas meta tags, com a mesma forma de título e de endereço.
O shell genérico, que toda outra página e o 404 de uma publicação oculta retornam, leva as mesmas tags da página inicial sem um endereço próprio: og:type website, o nome da instância como og:site_name e og:title, short_description como og:description, og:locale, a imagem da instância e twitter:card. Ele não tem og:url nem <link rel="canonical">, então uma única cópia serve todos os caminhos, e o 404 de uma publicação oculta continua idêntico ao de qualquer outra página.
A página de uma hashtag acrescenta apenas <link rel="alternate" type="application/atom+xml"> para o feed da hashtag (https://<host>/tags/<tag>.atom), com o título “#tag em nome da instância” (server:feed.tag_title), tenha ou não uma publicação usado a hashtag ainda. Um link compartilhado para uma hashtag ou para a página pública de custos mostra o cartão da instância.
Os próprios feeds são documentos Atom 1.0 com as 20 publicações públicas locais mais recentes que não são respostas nem impulsos, com ETag, Last-Modified e Cache-Control: public, max-age=60. A entrada de um artigo é o título e o resumo dele, com o link para o artigo; o corpo fica na página do artigo. Cada perfil com feed também tem um feed apenas de artigos, https://<host>/@<username>/articles.atom, com o título “Artigos de nome (@handle)” (server:feed.articles_title), que segue as mesmas regras; a página do perfil aponta apenas para o feed principal. O servidor guarda cada feed renderizado no seu armazenamento chave-valor por um minuto, então uma mudança chega a um feed em cerca de um minuto. Um feed leva o mesmo X-Robots-Tag e as mesmas declarações de IA do perfil dele; o feed de uma hashtag é sempre noindex e declara a recusa de IA de qualquer um dos autores. Um perfil sem feed, e uma hashtag que nenhuma publicação usou, respondem 404.
og:image é escolhida nesta ordem.
- A primeira imagem anexada à publicação, ou a capa de um artigo (o texto alternativo dela vai para
og:image:alt). Não é usada para uma publicação ou um artigo marcado como sensível, nem para uma publicação com aviso de conteúdo. - A imagem de cabeçalho do perfil ou, na falta dela, o avatar (
og:image:alté “Imagem de cabeçalho de {name}” ou “Avatar de {name}”). - A imagem de prévia da instância (a configuração da instância
preview_image, em “Pré-visualizações de links” em Configurações → Geral da administração;og:image:alté o textopreview_image_alt, ou “Imagem de {nome da instância}” se não houver). - A miniatura da instância (a configuração da instância
thumbnail, a imagem da página Configurações → Geral;og:image:alté o textothumbnail_alt, ou “Imagem de {nome da instância}” se não houver). - A versão de prévia de link do logotipo da própria instância (logotipo e ícone), um PNG de 1200x630
em
https://<host>/brand/<revision>/preview-1200x630.png(og:image:alté “Imagem de {nome da instância}”). - A imagem padrão incluída (
https://<host>/preview-image.png, um PNG de 1200x630 do logotipo do mycroblog sobre branco, sem o nome da instância;og:image:alté “O logotipo do mycroblog”).
Os números 3 a 6 são a imagem da instância. Assim, uma página que mostra uma prévia sempre tem og:image e og:image:alt.
As imagens de 1 a 4 são a variante large da mídia processada, e a largura e a altura são os valores do processamento.
Se preview_image não está definida, ainda está sendo processada, falhou no processamento ou não é uma imagem, usa-se a miniatura, depois o logotipo
e depois a imagem incluída. As configurações da instância são lidas a cada requisição, então my instance set preview_image ... entra em vigor
sem reiniciar (para o procedimento, veja as configurações da instância).
A imagem incluída faz parte do binário (cerca de 20 KB). Ela é servida com Cache-Control: no-cache e um ETag.
- A resposta leva
Cache-Control: public, max-age=60, stale-while-revalidate=300. Uma exclusão, uma mudança de visibilidade ou a publicação ou despublicação de um documento permanece nos caches compartilhados por no máximo esse tempo. - O ETag é montado a partir das versões do template, dos assets e das configurações da instância, do idioma, da versão
(revisão) da publicação, da visibilidade efetiva, da versão do perfil e da imagem escolhida (para a página inicial, a página de
informações, as páginas de documentos e a página sobre o rastreador: o endereço da página, o título, a descrição da instância e a imagem escolhida;
para o shell genérico: o nome da instância, a descrição dela e a imagem da instância).
If-None-Matchrecebe304. - Se você colocar uma CDN na frente, inclua
Acceptna chave de cache (para que o JSON do AP e o HTML não se misturem).
Verificação manual
Seção intitulada “Verificação manual”Verifique cada serviço em um dispositivo real após uma atualização ou uma mudança nas configurações de prévia. Você precisa de uma instância acessível de fora por HTTPS (os
bots de prévia não alcançam localhost).
Preparação
Seção intitulada “Preparação”-
Com uma conta de teste, prepare estas publicações.
- Uma publicação
publiccom uma imagem paisagem (por exemplo 1200x630) e texto alternativo - Uma publicação
publicsem imagem (de uma conta que tem imagem de cabeçalho) - Uma publicação
publiccujo corpo tem mais de 200 caracteres e contém emoji (como 👨👩👧👦) - Uma publicação
unlisted - Uma publicação
private - Uma publicação de uma conta cujo nome de exibição contém
"><script>alert(1)</script>
- Uma publicação
-
Verifique o HTML de cada URL.
Janela do terminal curl -sS -D - -H 'Accept: text/html' https://<host>/@alice/status/<post ID>-
O status é 200 e as meta tags da tabela acima estão lá. A publicação
unlistedtemnoindex. -
Uma publicação
privatee um ID inexistente dão o mesmo corpo 404 comX-Robots-Tag: noindex, noarchive(enoai, noimageaitambém, quando as configurações recusam IA).Janela do terminal diff <(curl -sS https://<host>/@alice/status/<private post ID>) <(curl -sS https://<host>/@alice/status/0192f3a4-7b1c-7d2e-9f00-1a2b3c4d5e6f) -
O
<script>no nome de exibição é escapado como<script>.
-
- Cole a URL da publicação com imagem na tela de composição (ou em uma mensagem direta).
- Verifique que o cartão de imagem grande (
summary_large_image) mostra o título, o domínio e a imagem. - Para a URL da publicação sem imagem, verifique que o cartão mostra a imagem de cabeçalho. Para uma conta sem imagem de cabeçalho
nem avatar, verifique que o cartão grande mostra a imagem padrão (
preview_image, ou a imagem incluída quando ela não está definida). - Para uma conta com apenas um avatar quadrado, verifique que o cartão é o de imagem pequena (
summary).
O X guarda cartões em cache. Para verificar uma mudança, cole a URL com uma query (como ?v=2) para que ela conte como uma URL diferente.
Mastodon
Seção intitulada “Mastodon”- A partir de uma conta em outra instância, faça uma publicação que contenha a URL da publicação com imagem.
- Verifique que um cartão de prévia aparece sob a publicação com o título, a descrição e a imagem.
- Verifique que a conta de teste (
fediverse:creator) é mostrada como “autor” sob o cartão e que você consegue ir ao perfil dela.
O Mastodon guarda o cartão em cache em cada servidor que o buscou. Para gerá-lo de novo, publique com uma URL nova (com uma query).
Discord
Seção intitulada “Discord”- Cole a URL da publicação com imagem em um canal.
- Verifique que o embed mostra o nome do site (o nome da instância), o título, a descrição e uma imagem grande.
- Para uma publicação com mais de 200 caracteres, verifique que a descrição termina com
…e que nenhum emoji é cortado no meio.
- Cole a URL da publicação com imagem em um canal.
- Verifique que a prévia expandida mostra o nome do site, o título, a descrição e a imagem.
- Verifique que uma prévia também aparece para a URL de uma publicação
unlisted(noindexé para mecanismos de busca e não impede as prévias).
O Slack também guarda prévias em cache. Para verificar uma mudança, adicione uma query à URL.
- Envie a URL da publicação com imagem em um chat.
- Verifique que aparece uma prévia com o título, a descrição e a imagem.
O LINE também guarda prévias em cache. Para verificar uma mudança, adicione uma query à URL.
O que não deve ficar visível
Seção intitulada “O que não deve ficar visível”Em todos os serviços, verifique que a URL de uma publicação private e a URL de uma publicação inexistente dão a mesma prévia genérica
(apenas o nome da instância, ou nada) e que nenhum corpo, nome de exibição ou imagem aparece.
Cartões de links em publicações
Seção intitulada “Cartões de links em publicações”Para mostrar um cartão para um link em uma publicação, o job deste servidor busca a página vinculada e a imagem dela, e obedece ao que o site vinculado diz a respeito.
Suas requisições são my-linkcard/<version> (+https://<host>/) para a página, a imagem e o robots.txt. Toda outra requisição do servidor, inclusive a do proxy de mídia, continua my/<version> (+https://<host>/).
As requisições não enviam cookies nem Referer, e nada diz qual conta ou publicação vinculou a página.
A página para operadores de sites
Seção intitulada “A página para operadores de sites”https://<host>/about/crawler conta aos operadores dos sites vinculados o que o rastreador requisita, o que ele envia, com que frequência e como optar por sair, e que eles podem pedir que você pare de buscar do domínio deles. Qualquer pessoa pode lê-la sem uma conta. A seção “Mecanismos de busca e IA” da página de informações da instância (/about) liga a ela; o User-Agent nomeia apenas https://<host>/.
Ela diz o que este servidor faz, a partir de link_cards e link_cards_ignore_robots_txt, e mostra o contato da instância (contact_account, contact_email). Defina um contato, para que um site tenha a quem pedir: sem um, a página diz que este servidor não publica nenhum.
Com link_cards_ignore_robots_txt ativado, a página diz que um site não pode recusar este servidor no robots.txt.
robots.txt
Seção intitulada “robots.txt”O nome no robots.txt é my-linkcard, em qualquer caixa. Sem um grupo com esse nome, o grupo * se aplica, como diz a RFC 9309. Allow, Disallow, * e $ são lidos, vencendo a correspondência mais longa e, em caso de empate, Allow; Crawl-delay e outros registros não são lidos.
O robots.txt é lido até 512 KiB em 10 segundos, e o que foi lido de um arquivo maior é usado. O servidor guarda apenas as regras de my-linkcard, por origem (esquema, host e porta).
Resposta para robots.txt |
O que o servidor faz | Guardado por |
|---|---|---|
| 200 | Obedece ao arquivo | 24 horas |
| 4xx exceto 429 | Sem arquivo: busca | 24 horas |
| 429, 5xx, uma falha de rede ou um redirecionamento que o servidor recusa | Não busca nada da origem | 1 hora |
| Mais de 5 redirecionamentos | Sem arquivo: busca | 24 horas |
- A URL da página é verificada antes de ser requisitada, seja qual for a visibilidade da publicação. O mesmo vale para cada URL para a qual ela redireciona, contra o
robots.txtda origem dessa URL, e um redirecionamento para uma URL recusada termina ali: o servidor não a requisita e não cria cartão. - Uma URL que o
robots.txtproíbe não é buscada de novo por 24 horas, como qualquer outra falha de uma página. Quando o arquivo apenas não pôde ser lido, o servidor tenta a página de novo uma hora depois, até o limite de tentativas do job. - Uma imagem é verificada da mesma forma contra a própria origem. Uma imagem proibida deixa um cartão sem imagem. Quando o arquivo apenas não pôde ser lido, uma imagem registrada antes permanece, e uma imagem nova fica de fora até a próxima nova busca.
- Uma nova busca, que uma publicação pode causar 14 dias após a última busca, remove o cartão quando o
robots.txtproíbe a URL dele. Quando o arquivo apenas não pôde ser lido, o cartão permanece. - O servidor não percorre os cartões para verificá-los de novo, então um site que muda suas regras perde um cartão na próxima nova busca desse cartão.
link_cards_ignore_robots_txt (configurações da instância) desativa tudo isso: o servidor não busca nem usa o robots.txt. Ele ainda se identifica como my-linkcard, e os sites vinculados então não podem recusar as buscas com o robots.txt: restam apenas as diretivas das páginas deles e um pedido a você de uma regra no domínio deles, como a página para operadores de sites informa.
Diretivas de uma página
Seção intitulada “Diretivas de uma página”O servidor também lê as diretivas da página que buscou: <meta name="robots"> e <meta name="my-linkcard"> no <head>, e X-Robots-Tag sem o nome de um bot ou com my-linkcard:. Diretivas para outro bot não se aplicam. Quando há várias, vence a mais restritiva.
Elas se aplicam seja qual for o valor de link_cards_ignore_robots_txt.
| Diretiva | Cartão |
|---|---|
nosnippet, max-snippet:0 |
Sem descrição |
noimageindex, max-image-preview:none |
Sem imagem, que não é buscada |
noindex, nofollow, noarchive, none e as demais |
Sem mudança |
O título, o nome do site e o autor permanecem em todas as diretivas; um site que não os quer recusa a busca no robots.txt.
As diretivas só são conhecidas depois que a página é buscada, então não impedem a requisição da página. Uma nova busca aplica as diretivas que a página tiver então.
Limites por host
Seção intitulada “Limites por host”O rastreador é gentil com cada host, seja qual for o valor de link_cards_ignore_robots_txt. Um host é o nome na URL, sem a porta, então um site vinculado e o host de suas imagens têm limites separados.
- Ele faz uma busca por vez em um host, e a seguinte começa pelo menos 1 segundo depois que a última terminou. Uma busca é uma requisição com seus redirecionamentos e, quando precisa ser lido, o
robots.txtde que precisa. Uma página e sua imagem são duas buscas, também em um só host. - Um
429ou um503interrompe as buscas no host que respondeu, também quando ele respondeu a um redirecionamento, a uma imagem ou aorobots.txt. Elas param peloRetry-Afterdele, em segundos ou como data, por pelo menos 1 segundo e no máximo 1 hora. UmRetry-Afterausente ou ilegível significa 1 minuto. - Um job que precisa esperar a sua vez volta mais tarde. Nenhum worker espera, e ele não usa nenhuma das tentativas do job, então mesmo uma rajada de links para um só site termina com todos os cartões e nenhum job com falha. Os jobs de um host acordam cerca de um por segundo.
- Uma URL cujo host interrompeu o rastreador mantém o cartão, não é lembrada como falha e é buscada quando a pausa termina. Depois de 5 respostas assim para uma URL em 24 horas, a página conta como falha, como qualquer outra que não seja
200, e uma imagem fica de fora do cartão. - Um cartão que espera pela imagem guarda o que leu da página por até 2 horas, para que a página não seja requisitada de novo.
- As regras em um domínio e as ações de domínio vêm primeiro: nada espera por um host do qual nada é buscado.
Os limites ficam no armazenamento chave-valor e todos expiram: um worker que para no meio de uma busca libera o host dele em 2 minutos. Esses números não são configurações. Para ver os limites em ação:
my.link_card.host_pausesconta as pausas pelo status que o host respondeu, e cada pausa registralink card host pausedemINFOcomhost,statusepause_seconds.my.job.durationcommy.job.type="content.fetch_link_card"emy.outcome="postponed"conta as execuções que voltaram mais tarde. Um número grande significa muitos links para poucos sites ou uma pausa longa, não uma falha.
Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt