Gerador de incorporação do X (Twitter)

Introdução

O Gerador de incorporação do X (Twitter) da Toollect transforma qualquer URL de post no código de incorporação oficial que o X publica para mostrar publicações noutros sites – o blockquote twitter-tweet mais o widgets.js – com um clique, uma pré-visualização ao vivo antes de copiar e todas as opções de apresentação que a interface do X oferece. Cole um link, escolha as opções, pré-visualize, copie, cole. Todo o ciclo demora segundos.

A fricção que elimina é familiar a quem já incorporou um post à mão. A janela do publicador do X produz o código, mas espalha as suas escolhas por ecrãs separados, não expõe controlos para ocultar mídia nem para alinhamento, e não dá às incorporações de vídeo qualquer controlo numérico de largura. Escrever o blockquote à mão funciona até que um atributo mal escrito deixe o post como um link nu para sempre. Esta ferramenta monta a marcação exata que o widgets.js espera, traduz as suas opções nos atributos data-* corretos e mostra-lhe o render real antes que algo chegue à sua página.

O gerador oferece dois modos atrás de uma barra de separadores. Publicação constrói o cartão clássico para qualquer post – texto, fotos, pré-visualizações de links – com tema, largura de 220 a 550 px, idioma da interface, alinhamento, visibilidade de conversa e mídia, Do Not Track e uma opção para omitir a tag script partilhada. Vídeo otimiza o mesmo post para o seu player, com uma largura até 1920 px escrita no atributo data-media-max-width que os clipes grandes merecem. Ambos os modos falam diretamente com o endpoint oEmbed público do X – sem chave de API, sem registo e sem servidor Toollect no meio.

Casos de uso

Incorporar conteúdo do X aparece em mais lugares do que numa entrada de blog, e os dois modos dividem o trabalho naturalmente.

Blogs e conteúdo editorial

Um artigo de comentário que cita uma figura pública, um artigo técnico com o post de anúncio incorporado, um blog desportivo com o clipe do momento – os casos clássicos. O modo Publicação com as predefinições cobre posts de texto; passe para o modo Vídeo quando o post é sobretudo um clipe e o player deve dominar a coluna.

Redações e cobertura em direto

Jornistas trazem posts de testemunhas oculares e comunicados oficiais para a cobertura contínua. A velocidade conta, e a verificação também – o gerador normaliza qualquer link que o contacto no terreno partilhe, seja um link de partilha da app com parâmetros de rastreio, formas legacy de twitter.com ou variantes de vista de foto, numa referência canónica do post, e a pré-visualização confirma que o post ainda renderiza antes de a peça sair. Ocultar conversa mantém um fio centrado na declaração citada em vez da discussão acima dela.

Documentação e escrita técnica

Notas de lançamento, changelogs e tutoriais citam cada vez mais threads de engenheiros como fontes primárias. Ocultar mídia colapsa as pré-visualizações de links em texto para uma leitura mais calma, o seletor de idioma apresenta os botões de ação e os carimbos de tempo no idioma da documentação, e Omitir script mantém livres de tags duplicadas as páginas que já carregam o widgets.js globalmente – bibliotecas de componentes, temas de documentação.

Sites de marketing e portefólios

Posts de elogios de clientes como prova social, threads de fundadores como história de marca. O alinhamento Centro coloca um único testemunho numa coluna estreita; Do Not Track sinaliza respeito pela privacidade ao público europeu; a pré-visualização verifica cada cartão antes do envio.

Como funciona

A ferramenta corre em quatro passos:

1. Analisar e canonizar o URL – a entrada é comparada com a gramática de links do X para posts – um nome de utilizador (sem @, 1–15 letras, dígitos ou underscores), a rota status e um ID snowflake de 15–19 dígitos em x.com ou twitter.com com prefixos opcionais www./mobile./m. Parâmetros de consulta como ?s=20&t=… são ignorados em vez de limpos – o URL canónico reconstruído simplesmente nunca os inclui. Rotas sem nome de utilizador como /i/web/status/… do cliente web são rejeitadas com uma mensagem dedicada porque o endpoint oEmbed não as consegue resolver.
2. Construir o pedido oficial – as suas opções tornam-se parâmetros de consulta no endpoint oEmbed público do X (publish.x.com/oembed?url=…) – maxwidth, theme, lang, hide_thread, hide_media, align, dnt, omit_script. O endpoint é sem chave e propositadamente sem limite de taxa – existe precisamente para que os CMS convertam URLs em incorporações.
3. Obter a marcação oficial – um único GET HTTPS devolve o HTML do blockquote exatamente como o X o formata, com as suas opções já cozidas como atributos data-*. O seu navegador fala diretamente com o X; nenhum servidor Toollect toca no pedido.
4. Pós-processar e pré-visualizar – a tag script do servidor é removida e gerida separadamente (para que a pré-visualização carregue o widgets.js exatamente uma vez independentemente de quantas vezes regenere), o modo Vídeo reescreve o atributo de largura no cliente (veja abaixo porquê), e o blockquote entra na área de pré-visualização. A ferramenta vigia o iframe renderizado e informa honestamente se ele nunca aparece.

Mudar qualquer opção regenera toda a cadeia – novo pedido, marcação fresca, pré-visualização refeita – assim o código que copia corresponde sempre ao que está a ver.

Formatos de URL compatíveis

O gerador aceita qualquer forma de URL que identifique um post com o seu nome de utilizador, e rejeita todo o resto com uma mensagem específica.

Formatos aceites

Variantes de vista e parâmetros espúrios após o ID do post são simplesmente ignorados – a incorporação aponta sempre para o post em si, que renderiza os seus próprios media. O prefixo https:// e a barra final são opcionais.

Formatos rejeitados

O caso sem nome de utilizador sob /i/web/status/… merece ênfase porque é a surpresa mais comum. O X entrega essa forma quando a URL de um post é copiada do cliente web sem o abrir. O gerador recusa-a deliberadamente – passá-la ao endpoint produziria uma falha silenciosa – e pede-lhe o link completo. O Analisador de URL do X (Twitter) deste site resolve esses links para a sua forma canónica se preferir reparar o URL em vez de voltar a copiá-lo.

Anatomia do código de incorporação

A saída é o mesmo código que a maquinaria do X produz, com as suas opções aplicadas. Uma incorporação de publicação com as predefinições parece-se com isto (conteúdo abreviado):

<blockquote class="twitter-tweet" data-width="550">
  <p lang="en" dir="ltr">Just setting up my twttr</p>
  &mdash; Jack (@jack)
  <a href="https://x.com/jack/status/20?ref_src=twsrc%5Etfw">21 de março de 2006</a>
</blockquote>
<script async src="https://platform.x.com/widgets.js" charset="utf-8"></script>

Percorrendo as partes:

• A classe do blockquote – twitter-tweet é o gancho que o widgets.js procura. Cada elemento com esta classe na página torna-se um cartão renderizado.
• data-width (publicações) – a largura máxima de renderização em pixels. O X comprime o valor internamente para cerca de 250–550 independentemente do que estiver escrito – o gerador por isso mantém o valor escolhido na gama honesta.
• data-media-max-width (vídeos) – quão larga a mídia pode expandir-se dentro do cartão, até 1920 px. Presente apenas no modo Vídeo – veja Publicação contra vídeo para saber por que o gerador escreve este atributo ele próprio.
• data-theme="dark" – presente apenas quando Escuro está escolhido. Renderiza texto claro sobre fundo escuro com o aspeto de cartão escuro.
• data-lang – presente sempre que é selecionado um idioma concreto, inglês incluído. Localiza os textos próprios do widget – formato de data, a ponte Ler mais, rótulos de ações – mas nunca o texto do próprio post. Apenas Automático omite o atributo; o widgets.js recai então no idioma da página.
• data-conversation="none" – adicionado por Ocultar conversa numa resposta. Sem ele, o widgets.js antepõe um resumo recolhido da publicação pai.
• data-cards="hidden" – adicionado por Ocultar mídia. As pré-visualizações de links, fotos e vídeos ficam recolhidas; apenas o texto renderiza.
• data-align – faz o cartão flutuar à esquerda ou à direita, ou centraliza-o, relativamente ao seu contentor. Ausente com alinhamento Nenhuma.
• data-dnt="true" – adicionado pela recusa de personalização. Diz ao X para não usar a incorporação nem as suas vistas de página para sugestões personalizadas ou publicidade personalizada.
• O parágrafo com a linha de autoria – o conteúdo visível antes de o widgets.js correr – texto do post, autor, e um link para a publicação. É a experiência permanente para visitantes sem JavaScript ou com o script bloqueado, e degrada graciosamente numa citação normal.
• A tag script – o widgets.js de platform.x.com, carregado async. Um por página chega para quantas incorporações quiser – exatamente o propósito da opção Omitir script.

Publicação contra vídeo

Dois separadores, um post, dois trabalhos diferentes. Mudar de separador regenera imediatamente – não há estado obsoleto.

Por que a ferramenta escreve ela própria o data-media-max-width? Porque o endpoint oEmbed do X não o consegue fazer. Testes confirmam que o endpoint comprime cada parâmetro maxwidth – incluindo posts com vídeo – para a gama de publicação 220–550, e nunca emite o atributo data-media-max-width que as incorporações de vídeo transportam. Esse atributo pertence ao fluxo interno de publish.x.com, onde o gerador de vídeo incorporado decora a marcação a posteriori. O gerador reproduz exatamente essa decoração – remove o data-width comprimido do servidor e escreve a largura escolhida em data-media-max-width, assim uma incorporação de clipe de 1200 px é realmente 1200 px de largura na sua página.

Na prática a regra de decisão é simples. Se o post se lê bem como cartão – Publicação. Se remover o player o esvazia – Vídeo, e dê ao player o espaço de que precisa.

Opções de incorporação

Cada controlo mapeia para um atributo ou um parâmetro de pedido. Predefinições entre parênteses.

Idioma (predefinição: o idioma da página) – oferece Automático mais os 34 idiomas que o X fornece para textos do widget. Cada seleção concreta, inglês incluído, é enviada como parâmetro lang e escrita em data-lang – assim o chrome do widget fica igual onde quer que cole o código. Localiza carimbos de tempo e rótulos de ações à volta do post, nunca as palavras do post. Automático omite tanto o parâmetro como o atributo – o widgets.js renderiza então no idioma declarado pela página anfitriã; serve para sites multilingues, mas torna a saída dependente do local onde é colada.

Tema (Claro, apenas separador Publicação) – Escuro envia theme=dark e escreve data-theme="dark". Claro é a ausência do atributo.

Largura (550 publicação, 560 vídeo) – digitada como número exato, comprimida para a gama válida assim que sai do campo. Publicações enviam maxwidth; vídeos comandam a reescrita client-side do data-media-max-width. Valores fora da gama de um separador não sobrevivem ao campo – 9999 em Publicação torna-se 550, 100 em Vídeo torna-se 560.

Alinhamento (Nenhuma) – Esquerda, Direita ou Centro escrevem align no pedido e data-align no blockquote. Centro é a forma discreta de colocar um único cartão num artigo largo; Direita deixa o texto do artigo fluir à volta dele.

Ocultar conversa (desligado, apenas separador Publicação) – envia hide_thread=true, que o servidor traduz em data-conversation="none". Significativo apenas em respostas; num post isolado não muda nada.

Ocultar mídia (desligado, apenas separador Publicação) – envia hide_media=true, traduzido em data-cards="hidden". A incorporação torna-se uma pura citação.

Omitir a tag script do widgets.js (desligado) – envia omit_script=true e suprime a tag script na saída. Para sites que já carregam o widgets.js uma vez globalmente – várias incorporações, um script. Se a sua página não tem widgets.js, deixe isto desligado; o blockquote sozinho renderiza para sempre como texto estático.

Recusar a personalização do X (desligado) – envia dnt=true e escreve data-dnt="true". O X documenta isto como exclusão da incorporação e das suas páginas de sugestões personalizadas e publicidade personalizada.

Uso

1. Cole a URL do post no campo de entrada – qualquer formato aceite da tabela acima.
2. Prima Gerar (ou Enter). O código aparece na caixa de saída e a pré-visualização abre-se automaticamente com o render real do X.
3. Escolha o separador – Publicação para o cartão padrão, Vídeo para posts centrados no clipe. Mudar regenera com as opções e a gama de largura desse separador.
4. Ajuste as opções – idioma, tema, largura, alinhamento, as caixas de visibilidade. Cada mudança volta a pedir e a renderizar; a caixa de código nunca diverge da pré-visualização.
5. Confira os diagnósticos – se nenhum cartão aparecer, o aviso acima da saída diz se o script do X estava bloqueado ou se o post não pode ser incorporado.
6. Copie o código e cole-o no HTML da sua página onde o post deve aparecer.

Uma entrada que corresponda a nenhum formato aceito limpa a saída e explica-se – ou a mensagem de link inválido ou, para rotas sem nome de utilizador, o pedido do link completo. Limpar reinicia entrada, código e pré-visualização num passo.

Tutorial

Siga um link real através dos dois separadores.

Passo 1 – Cole um link de partilha da app. Copie a URL de um post tal como a app móvel a partilha, parâmetros de rastreio incluídos:

https://twitter.com/new27brigade/status/2090248985391014324?s=20&t=FakeNonce

Prima Gerar. O analisador lê para lá do domínio legacy e dos parâmetros s e t direto ao post em si – new27brigade, estado 2090248985391014324 – e o código gerado aponta para a forma canónica. A pré-visualização abre-se e o cartão renderiza.

Passo 2 – Escureça. Ponha o Tema em Escuro. O código ganha data-theme="dark" e a pré-visualização renderiza na paleta escura. Note o novo pedido – o tema é cozido no servidor, razão pela qual cada mudança de opção chama novamente o endpoint em vez de editar a cadeia localmente.

Passo 3 – Estreite. Digite 350 em Largura e prima Enter. O atributo passa a data-width="350" e o cartão encolhe. Experimente digitar 9999 e clicar noutro lado – o campo volta a 550, porque o X aí comprimiria de qualquer forma.

Passo 4 – Localize a interface. Ponha o Idioma em japonês (日本語). O código ganha data-lang="ja" e o carimbo de tempo na pré-visualização reformata-se segundo a convenção japonesa. O texto do post fica exatamente como está – a definição governa só os rótulos próprios do X.

Passo 5 – Passe para Vídeo. Clique no separador Vídeo. A ferramenta pede de novo com o conjunto de parâmetros de vídeo e reescreve a marcação – o data-width desaparece, o data-media-max-width="560" aparece, e o seletor de tema abandona o painel. Arraste a largura até 1200 – o player expande-se. Este post é um clipe de exercício militar, por isso o modo Vídeo lhe convém; para um anúncio de texto voltaria atrás.

Passo 6 – Copie e envie. Prima Copiar e cole numa página HTML simples. Abra-a – o player renderiza em largura plena. Esse é o contrato completo – o mesmo código, o mesmo render, na sua página.

Pré-visualização e diagnóstico

A pré-visualização executa o verdadeiro widgets.js do X contra o seu blockquote exato, por isso falha exatamente onde a sua página falhará. Dois avisos, dois significados distintos:

Ambos os avisos disparam só após esperas generosas – vinte segundos para a descarga do script, quinze mais para o render – para que ligações lentas não produzam falsos alarmes. Um post incorporável renderiza bem dentro dessas janelas.

Um detalhe mecânico que vale mencionar – a primeira geração descarrega o widgets.js e guarda-o para a sessão. As regenerações – novas opções, mudanças de separador – reutilizam-no e convidam-no a processar o novo blockquote, assim as pré-visualizações seguintes aparecem mais depressa do que a primeira.

Dicas de profissional

• Emparelhe-o com o analisador de URL. O analisador examina e limpa um link – tipo, ID snowflake, chaves de rastreio; o gerador transforma o link limpo em código. Arquive com o analisador, publique com o gerador.
• Uma tag script, muitas incorporações. Páginas com vários posts devem carregar o widgets.js uma vez – marque Omitir script em cada saída exceto a primeira, ou carregue-o você na template do site e omita-o em toda a parte.
• Ocultar mídia transforma o post em citação. Para citações editoriais onde uma pré-visualização de link distrai, Ocultar mídia mais Ocultar conversa deixam apenas as palavras e a autoria.
• Centralize testemunhos individuais. Alinhamento Centro num layout largo lê-se como design intencional; o alinhamento à esquerda, predefinição de cada CMS, raramente é o que uma página de marketing quer.
• Iguale o idioma do widget ao idioma da página. Uma página japonesa com botões RETWEET em inglês parece inacabada – os idiomas concretos fixam o chrome, a parte de que é responsável; se o mesmo embed corre em templates multilingues, escolha antes Automático e deixe o widgets.js seguir cada página anfitriã.
• Ative o Do Not Track para páginas viradas para a UE. A flag está documentada pelo X e propaga-se pela incorporação – um sinal de um clique de que o cartão respeita a privacidade do visitante.
• Desenhe para a coluna, depois fixe a largura. As publicações terminam fisicamente aos 550 px; a pré-visualização mostra o resultado real ao tamanho do seu contentor antes de se comprometer.

Alternativas

De que outras maneiras pode pôr um post numa página?

A janela de partilha do X é a alternativa mais próxima e a fonte do mesmo blockquote – mas a sua personalização pára no idioma, ocultar conversa, opt-out de personalização e um tamanho de vídeo grosseiro, e não oferece caminho para hide_media, align ou um maxwidth preciso. A rota API compra controlo total a preços pay-per-use e ainda lhe deixa a renderização. Serviços de terceiros interpõem os seus próprios scripts. O gerador ocupa o meio-termo prático – marcação oficial, opções completas, confirmação visual imediata.

Contra as APIs oficiais

Três superfícies oficiais tocam na incorporação de posts, e o gerador é construído diretamente sobre a mais benigna.

O gerador chama o endpoint oEmbed exatamente como documentado – o mesmo pedido que um plugin de CMS faria, feito pelo seu navegador. Acrescenta o que falta ao endpoint – normalização de entrada, a decoração data-media-max-width do modo vídeo, gestão de tags script e diagnósticos. A X API v2 está deliberadamente fora – desde que a sua alteração de preços de fevereiro de 2026 eliminou o nível gratuito, ler posts através dela custa dinheiro por capacidades que o endpoint gratuito já cobre para fins de incorporação.

Gerador de incorporação contra analisador de URL

A Toollect entrega duas ferramentas do X que aceitam os mesmos links, e a divisão do trabalho merece um olhar:

O analisador é o analista; o gerador é o construtor. Um fluxo de publicação usa legitimamente ambos por ordem – analisar para identificar e normalizar para onde um link caótico aponta, depois gerar para o pôr na página. Concordam gramaticalmente por construção – um link que o analisador aceita como post é um link que o gerador incorpora.

O que ele não faz

Os limites, nomeados para que nunca se confie demais na ferramenta:

• Não incorpora cronologias, perfis, listas, spaces nem hashtags. São outras superfícies do X com outra marcação; o suporte de perfis do endpoint oEmbed produz âncoras de cronologia, não cartões de post, e o gerador recusa-as. Uma ferramenta dedicada seria o veículo honesto se houver procura.
• Não resolve links sem nome de utilizador. /i/web/status/… chega sem o nome de utilizador que a forma canónica exige, e a ferramenta não adivinha. Abra o link, copie o URL completo.
• Não resolve encurtadores t.co. Um link encurtado nu não transporta identidade de post; cole o destino.
• Não contorna privacidade nem eliminação. Contas protegidas, posts eliminados e autores que desativaram a incorporação produzem código correto que não renderiza nada. Nenhuma ferramenta pode mudar isso.
• Não verifica posts antes do pedido. A validação é gramatical. Se o post existe responde-o apenas a resposta do endpoint – um post indisponível emerge como pedido falhado.
• Não estiliza o widget. Cores, tipos de letra e chrome dentro do cartão renderizado são assunto do X. Só a colocação (alinhamento, largura) e a presença (conversa, mídia) são suas.
• Não instala o código. O que copia é o que cola; a ferramenta não pode alcançar o seu CMS ou page builder.

Solução de problemas

Privacidade e tratamento de dados

Esta ferramenta é honesta quanto ao seu tráfego, maior do que o das irmãs de zero pedidos mas ainda assim direto ao X.

• Gerar envia a URL do post ao X, uma vez por ação. Premir Gerar ou mudar qualquer opção faz exatamente um GET HTTPS a publish.x.com/oembed com a URL canónica do post e as suas opções. O pedido vai do seu navegador à infraestrutura do X – nenhum servidor Toollect o proxya, o regista ou o vê.
• A pré-visualização carrega a maquinaria própria do X. Renderizar o cartão busca o widgets.js em platform.x.com, o iframe renderizado na infraestrutura de sindicação do X e a mídia nos seus hosts de imagens – precisamente o tráfego que o código copiado produzirá nos navegadores dos seus leitores.
• Do Not Track propaga-se. Com a opção ativa, o código gerado transporta data-dnt="true", o sinal documentado pelo X para excluir a incorporação e as suas vistas de página de sugestões e publicidade personalizadas.
• Sem conta, sem armazenamento, sem analytics. A ferramenta não guarda estado entre visitas; fechar o separador termina tudo.
• Publicar o código significa que os seus visitantes falam com o X. Essa é a natureza de incorporar – vale a pena dizê-lo com clareza. Se precisar de um fluxo de trabalho do X estritamente offline, o Analisador de URL do X (Twitter) deste site cumpre todo o seu trabalho com zero pedidos de rede.

Especificações técnicas

Detalhes:

• Endpoint – GET https://publish.x.com/oembed?url={canonical}, sem chave, resposta JSON, sem limites de taxa documentados; parâmetros maxwidth, theme, lang, hide_thread, hide_media, align, dnt, omit_script
• Gramática de entrada – hosts x.com / twitter.com com prefixos opcionais www. / mobile. / m.; nome de utilizador [A-Za-z0-9_]{1,15}; ID do post de 15–19 dígitos; esquema, barra final, variantes de vista (/photo/1, /video/1, …) e cadeias de consulta toleradas e descartadas
• URL canónica de saída – https://x.com/{username}/status/{id}
• Contrato de largura de publicação – 220–550 px inclusive (o endpoint comprime valores exteriores; histórico predefinido 325, predefinido da ferramenta 550); largura de vídeo 560–1920 px aplicada client-side ao data-media-max-width porque o endpoint não a consegue emitir
• Idiomas – Automático ou qualquer uma das 34 localidades do widget do X; cada seleção concreta escreve data-lang, inglês incluído – só Automático o omite
• Gestão de scripts – as tags script do servidor são removidas; https://platform.x.com/widgets.js carregado uma vez por sessão com um timeout de 20 segundos; o vigia de render pergunta ao iframe a cada 500 ms até 15 segundos, e depois reporta
• Política de novo pedido – cada mudança de opção ou separador emite um novo pedido oEmbed; pedidos idênticos em curso são colapsados por um guard de ocupação
• Auto-hospedar a saída requer – script-src e frame-src permitindo https://platform.x.com (mais https://platform.twitter.com para snippets legacy) e img-src permitindo https://abs.twimg.com e https://pbs.twimg.com
• Suporte de navegadores – todos os navegadores modernos (clipboard API; runtime ES5 exigido pelo próprio widgets.js)

Recursos

• Gera o código de incorporação oficial do X (Twitter) a partir de qualquer URL de post com um clique – modos de publicação e vídeo numa única ferramenta
• Espelha as opções do próprio publicador do X – tema claro/escuro, Automático mais 34 idiomas de interface, largura precisa, alinhamento, ocultar conversa, ocultar mídia
• Veja uma pré-visualização ao vivo renderizada pelo widgets.js oficial do X antes de colar o código
• Controle a largura com precisão – 220–550 px para publicações, 560–1920 px para vídeos via data-media-max-width
• Respeite os seus visitantes – interruptor Do Not Track integrado e uma opção para omitir tags widgets.js duplicadas
• Gerador gratuito no navegador com diagnósticos claros quando o script do X está bloqueado – sem chave de API, sem registo

Perguntas frequentes