Compartilhamento social e favicons
A única coisa que importa
og:image e og:url devem ser URLs absolutas em um host acessível publicamente.
O rastreador as busca de seus próprios servidores. Ele não tem contexto de página, nem cookies, nem referer, e não faz ideia do que seu caminho relativo é relativo a. Um caminho como /assets/og.jpg ou assets/og.jpg resolve para nada e o cartão retorna em branco.
<!-- morto: renderiza um cartão vazio em qualquer lugar -->
<meta property="og:image" content="assets/images/og-image.jpg">
<!-- funciona -->
<meta property="og:image" content="https://exemplo.com/assets/images/og-image.jpg">
Este é o motivo mais comum para uma prévia não funcionar. Antes de depurar qualquer outra coisa, confirme que a URL é absoluta e carrega em uma janela privada.
O corolário: prévias não funcionam em localhost ou file://. Nada que você faça localmente produzirá uma prévia real. Faça o deploy primeiro, depois valide.
O conjunto de tags
<link rel="canonical" href="https://exemplo.com/">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Marca">
<meta property="og:locale" content="pt_BR">
<meta property="og:url" content="https://exemplo.com/">
<meta property="og:title" content="Marca - o que é">
<meta property="og:description" content="Uma frase. Cerca de 110 caracteres.">
<meta property="og:image" content="https://exemplo.com/og-image.jpg">
<meta property="og:image:type" content="image/jpeg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="O que está na imagem.">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Marca - o que é">
<meta name="twitter:description" content="Uma frase. Cerca de 110 caracteres.">
<meta name="twitter:image" content="https://exemplo.com/og-image.jpg">
<meta name="twitter:image:alt" content="O que está na imagem.">
Três detalhes que são fáceis de errar:
og: usa property=, twitter: usa name=. Misturá-los é ignorado silenciosamente, então as tags parecem presentes no código fonte e não fazem nada. Alguns parsers toleram name= em og:, mas não confie nisso.
twitter:card deve ser summary_large_image. O padrão é um cartão quadrado pequeno com a imagem como miniatura ao lado do texto, o que desperdiça uma imagem de 1200x630.
Declarar og:image:width e og:image:height faz o cartão renderizar imediatamente. Sem eles, a plataforma precisa baixar a imagem antes de saber a proporção, então a primeira pessoa a compartilhar o link geralmente vê um cartão só de texto. Elas devem corresponder ao arquivo real. Meça, não suponha.
Comprimento da cópia: títulos são cortados por volta de 60 caracteres, descrições entre 110 e 200 dependendo da plataforma. Coloque o significado no início.
A imagem de compartilhamento
1200x630 (1.905:1). JPEG a menos que o design precise de alpha, o que não precisa, já que toda plataforma compõe sobre branco. Mantenha abaixo de 1 MB; os limites máximos são 8 MB (Facebook) e 5 MB (X), mas arquivos grandes excedem o tempo limite durante a raspagem.
Renderize na proporção alvo, não recorte uma captura de tela
Tirar uma captura de tela arbitrária e cortar para 1.905:1 joga fora a composição que o designer escolheu. Renderize a fonte na proporção:
# 1440x756 é exatamente 1.905:1, então reduz para 1200x630 sem recorte
chrome --headless --disable-gpu --hide-scrollbars --virtual-time-budget=8000 \
--window-size=1440,756 --screenshot=og-src.png "file://$PWD/index.html"
A armadilha da viewport curta
Se a página tem um hero de altura total (100vh / 100svh), renderizar diretamente em 1.905:1 dá uma viewport muito mais curta do que uma tela de desktop real. Qualquer mídia com object-fit: cover corta muito mais do que no uso real, e elementos que normalmente se afastam colidem - tipicamente um logotipo no cabeçalho pousando na cabeça do assunto.
Renderize em uma viewport mais alta para que a mídia corte como no uso real, depois recorte a janela de 1.905:1:
chrome --headless ... --window-size=1440,1000 --screenshot=og-src.png "file://$PWD/index.html"
ffmpeg -i og-src.png -vf "crop=1440:756:0:0" -q:v 2 og-crop.png # ancorado no topo
Compare um recorte ancorado no topo com um centralizado antes de escolher. O ancorado no topo geralmente mantém os elementos da marca (barra de utilitários, navegação, logotipo); o centralizado geralmente mantém o assunto e a chamada para ação. Você não pode ter ambos, porque um hero de altura total é mais alto do que 1.905:1 permite.
Enquadramento
Os cartões renderizam com cerca de 500 px de largura em um feed, e cada plataforma corta de forma diferente (LinkedIn e Slack são mais apertados que o Facebook). Mantenha qualquer coisa que deve sobreviver dentro dos 80% centrais, e defina qualquer tipo grande o suficiente para ser lido pela metade do tamanho. Detalhes finos de UI desaparecem; um logotipo grande e uma imagem forte não.
Favicons
A armadilha da fonte
Não coloque <text> em um favicon SVG.
<!-- quebra: renderiza na fonte de fallback que o visualizador tiver -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>
O SVG renderiza na máquina do visualizador, onde sua webfont não existe. Extraia o glifo como um path para que seja independente de fonte e de resolução. Veja o script abaixo.
A armadilha da transparência
Um glifo escuro em um fundo transparente desaparece contra o chrome escuro do navegador, e um claro desaparece no claro. Desenhe o ícone em um tile preenchido. Também dá à marca uma silhueta consistente em barras de abas, favoritos e telas iniciais.
O conjunto de arquivos
| Arquivo | Tamanho | Por que |
|---|---|---|
/favicon.ico | 16, 32, 48 | navegadores solicitam este caminho implicitamente mesmo quando você declara outros; mantenha na raiz web |
favicon.svg | escalável | o que navegadores modernos preferem, e permanece nítido em qualquer tela |
apple-touch-icon.png | 180 | tela inicial do iOS |
icon-192.png | 192 | manifesto |
icon-512.png | 512 | manifesto, telas de inicialização |
icon-maskable-512.png | 512 | máscaras adaptáveis do Android |
<link rel="icon" href="/favicon.ico" sizes="32x32">
<link rel="icon" href="/assets/icons/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/assets/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">
A zona segura maskable
O Android recorta ícones em formas arbitrárias (círculo, squircle, gota). Um ícone maskable deve manter tudo significativo dentro do círculo central de 80%, o que significa que cerca de 40% da borda do tile é padding descartável. Reutilizar o ícone normal fará com que suas bordas sejam cortadas.
Na prática: se o glifo cobre 60% do tile no ícone padrão, reduza para cerca de 40% no maskable. Envie ambos, com "purpose": "any" e "purpose": "maskable" como entradas separadas. Nunca coloque ambos os propósitos em um único arquivo.
Manifesto web
{
"name": "Marca",
"short_name": "Marca",
"start_url": "/",
"scope": "/",
"display": "standalone",
"background_color": "#f7f6f4",
"theme_color": "#0a0a0a",
"icons": [
{ "src": "/assets/icons/favicon.svg", "type": "image/svg+xml", "sizes": "any" },
{ "src": "/assets/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
{ "src": "/assets/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
{ "src": "/assets/icons/icon-maskable-512.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
]
}
theme_color tinge o chrome do navegador móvel, então deve corresponder ao que está no topo da página, não à cor principal da marca. Se a página abre em uma barra de utilitários preta, use esse preto. Uma incompatibilidade parece um bug de renderização. Espelhe em <meta name="theme-color">.
background_color é a tela de inicialização atrás do ícone antes da primeira pintura, então deve corresponder ao fundo da página.
Script de geração
Precisa de pillow e fonttools. Produz o conjunto completo de ícones mais a imagem de compartilhamento.
import os
from PIL import Image, ImageDraw, ImageFont
from fontTools.ttLib import TTFont
from fontTools.pens.svgPathPen import SVGPathPen
from fontTools.pens.boundsPen import BoundsPen
FONT = "marca.ttf" # a fonte real da marca, no peso que o logotipo usa
CHAR = "G"
INK = "#0a0a0a" # tile
PAPER = "#f2f1ed" # glifo
COVER = 0.60 # altura do glifo como fração do tile
OUT = "assets/icons"
os.makedirs(OUT, exist_ok=True)
# ── SVG: glifo como path real, para não depender das fontes do visualizador ──
f = TTFont(FONT)
gs = f.getGlyphSet()
name = f.getBestCmap()[ord(CHAR)]
bp = BoundsPen(gs); gs[name].draw(bp)
x0, y0, x1, y1 = bp.bounds
pen = SVGPathPen(gs); gs[name].draw(pen)
d = pen.getCommands()
VB = 64
s = (VB * COVER) / (y1 - y0)
tx = (VB - (x1 - x0) * s) / 2 - x0 * s
ty = (VB + (y1 - y0) * s) / 2 + y0 * s # y inverte: fontes são y-up, SVG é y-down
open(f"{OUT}/favicon.svg", "w").write(
f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {VB} {VB}">'
f'<rect width="{VB}" height="{VB}" fill="{INK}"/>'
f'<path transform="translate({tx:.3f} {ty:.3f}) scale({s:.5f} -{s:.5f})" '
f'd="{d}" fill="{PAPER}"/></svg>')
# ── Tiles rasterizados ────────────────────────────────────────────────────────────
def tile(px, cover=COVER):
img = Image.new("RGB", (px, px), INK)
dr = ImageDraw.Draw(img)
fnt = ImageFont.truetype(FONT, px * 2)
bb = dr.textbbox((0, 0), CHAR, font=fnt)
fnt = ImageFont.truetype(FONT, int(px * 2 * (px * cover) / (bb[3] - bb[1])))
bb = dr.textbbox((0, 0), CHAR, font=fnt)
dr.text(((px - (bb[2] - bb[0])) / 2 - bb[0],
(px - (bb[3] - bb[1])) / 2 - bb[1]), CHAR, font=fnt, fill=PAPER)
return img
tile(180).save(f"{OUT}/apple-touch-icon.png", optimize=True)
tile(192).save(f"{OUT}/icon-192.png", optimize=True)
tile(512).save(f"{OUT}/icon-512.png", optimize=True)
tile(512, cover=0.42).save(f"{OUT}/icon-maskable-512.png", optimize=True) # zona segura de 40%
tile(256).save("favicon.ico", sizes=[(16, 16), (32, 32), (48, 48)])
# ── Imagem de compartilhamento: recorte uma renderização mais alta na proporção, depois reduza ──
src = Image.open("og-src.png").convert("RGB") # ex. 1440x1000
src.crop((0, 0, 1440, 756)).resize((1200, 630), Image.LANCZOS).save(
"assets/images/og-image.jpg", quality=88, optimize=True, progressive=True)
Nenhuma fonte da marca disponível? Qualquer grotesca geométrica funciona para um monograma. Rasterizar um logotipo PNG existente no tile também é aceitável; apenas centralize dentro da mesma fração COVER e mantenha a variante maskable menor.
Verifique antes de enviar
import re, json, os
from PIL import Image
s = open("index.html").read()
tags = dict(re.findall(r'(?:property|name)="((?:og|twitter):[^"]+)"\s+content="([^"]+)"', s))
for t in ("og:url", "og:image", "twitter:image"):
assert tags[t].startswith("http"), f"{t} não é absoluto: {tags[t]}"
w, h = Image.open("assets/images/og-image.jpg").size
assert (str(w), str(h)) == (tags["og:image:width"], tags["og:image:height"]), "tamanho declarado está errado"
assert tags["twitter:card"] == "summary_large_image"
m = json.load(open("site.webmanifest"))
for i in m["icons"]:
assert os.path.isfile(i["src"].lstrip("/")), f"ícone faltando {i['src']}"
print("ok")
Lista de verificação:
-
og:imageeog:urlabsolutos, no host real, carregando em uma janela privada -
og:image:width/heightdeclarados correspondem ao arquivo real -
twitter:cardésummary_large_image - Tags
og:usamproperty=, tagstwitter:usamname= - Todo domínio placeholder substituído (procure por ele; geralmente há quatro)
-
favicon.icona raiz web, não apenas em uma pasta assets - Favicon SVG contém um
<path>, sem<text> - Tile do ícone é preenchido, para sobreviver ao chrome claro e escuro do navegador
- Ícone maskable com padding para os 80% centrais
-
theme_colorcorresponde à borda superior da página
Cache
Toda plataforma faz cache agressivamente e continuará servindo o cartão antigo após você corrigi-lo. Re-raspe:
- Facebook, Instagram, WhatsApp: https://developers.facebook.com/tools/debug/
- X: https://cards-dev.twitter.com/validator
- LinkedIn: https://www.linkedin.com/post-inspector/
O LinkedIn faz o cache mais forte e efetivamente ignora mudanças por cerca de 7 dias a menos que você execute o inspetor. Se uma URL já foi amplamente compartilhada com um cartão quebrado, adicionar uma string de consulta (?v=2) força uma raspagem nova.
Favicons também são fortemente cacheados no navegador. Teste em uma janela privada; um recarregamento normal geralmente continuará servindo o antigo.
Domínios placeholder
Quando o domínio real ainda não é conhecido, use um subdomínio de example.com (https://marca.example.com). A RFC 2606 o reserva, então é inequivocamente um placeholder e nunca pode apontar acidentalmente para um domínio que outra pessoa possui. Nunca deixe um domínio plausível mas não pertencente a você em metadados enviados.
Coloque a instrução de substituição em um comentário diretamente acima do bloco e no README do projeto, e diga quantas ocorrências existem. Normalmente são quatro: canonical, og:url, og:image, twitter:image.