Descobrindo programaticamente o código de compartilhamento com oEmbed

Publicados: 2022-03-10

Resumo rápido ↬ Muitos sites hospedam mídia e conteúdo que podem ser compartilhados em outros lugares pelo uso de algum código HTML incorporado. O que acontece se você tiver apenas o URL do item e precisar encontrar uma versão incorporável da mídia sem intervenção humana? É aí que entra o Embed.

A web está cheia de serviços que hospedam conteúdo rico, como vídeos, imagens, músicas e podcasts, mapas e gráficos, e todo tipo de delícias diferentes. As chances são de que, quando você adiciona seu conteúdo a um site, ele oferece uma maneira de incorporar esse conteúdo em uma página da Web em outro lugar.

Sites como o YouTube têm seu próprio player incorporável que é popular para usar em postagens de blog e até em páginas de produtos. O Soundcloud tem um código para incorporar o player de música no site da sua banda. Os angariadores de fundos de caridade podem enviar a rota de sua grande corrida para um site como o Strava e querer compartilhá-lo em seu site de angariação de fundos para mostrar a seus patrocinadores.

Tudo isso é feito encontrando a opção Compartilhar no site de hospedagem e copiando algum código que normalmente é uma mistura de HTML e JavaScript. Esse código geralmente pode ser colado na página de destino, e o site de hospedagem apresentará uma representação rica do conteúdo para todos os seus amigos, clientes e contatos verem.

Até agora, tudo bem, e isso cobre muito bem a opção de incorporação manual de conteúdo. No entanto, há um segundo caso de uso distinto, em que o resultado é o mesmo, mas o caminho para ele é muito diferente.

Mais depois do salto! Continue lendo abaixo ↓

Compartilhando programaticamente

Vamos imaginar que você está criando um aplicativo ou site que aceita conteúdo de um usuário. Isso pode ser algo tão simples como uma página de intranet básica para a equipe compartilhar notícias com colegas de trabalho, ou algo enorme como uma rede social inteira onde as pessoas podem se inscrever e começar a postar.

Em ambos os casos, você precisa descobrir o que fazer se o usuário adicionar uma URL como parte desse conteúdo. Você pode imaginar o cenário:

 Check out this video! https://youtu.be/jw7bRnFbwAI

Neste ponto, como um sistema de publicação, você precisa descobrir o que fazer. A primeira opção é não fazer nada e apenas deixar a URL como texto simples. Essa não é uma ideia brilhante, pois os usuários geralmente desejam clicar no URL e o texto simples não os ajudará a chegar à página do outro lado.

A segunda opção é transformá-lo em um link. Esse é um próximo passo sólido, pois os usuários podem seguir o link e acessar o conteúdo. Mas, ao fazer isso, eles saem do seu site e podem não voltar com pressa.

A melhor experiência do usuário pode ser buscar o player para esse conteúdo e incorporá-lo ali mesmo, em vez de apenas o URL. Isso permitiria que os usuários experimentassem o conteúdo diretamente em seu site, como fariam no Facebook, por exemplo.

Isso coloca o problema. Dado um URL, como posso transformá-lo no código de incorporação HTML/JavaScript necessário para mostrar um player avançado na página?

Se for um site conhecido como o YouTube, eu poderia escrever algum código que usa a API do YouTube para buscar as informações do vídeo e obter ou construir o código de incorporação dessa maneira. Eu poderia fazer o mesmo para outros serviços de vídeo como Vimeo e VIVO. Posso escrever código para reconhecer URLs do Flickr e do Instagram e usar suas APIs para buscar boas versões incorporáveis de fotografias. E o mesmo para Twitter e tweets. Mas isso está soando como muito trabalho!

O ideal seria se houvesse uma maneira padronizada de ir de uma URL de um conteúdo a um bloco de código de incorporação para mostrar esse conteúdo em uma página. Se você estiver prestando atenção, perceberá que a resposta para isso é oEmbed.

A origem do oEmbed

Este foi exatamente o problema que Leah Culver teve enquanto trabalhava no Pownce (um site de rede social realmente inovador que foi o Betamax do VHS do Twitter). Pownce queria incorporar representações ricas de conteúdo no fluxo de atualização de um usuário, mas não queria limitar o suporte apenas aos serviços com os quais eles escreveram especificamente o código para integração. Em um jantar com o colega Mike Malone, assim como Cal Henderson (que liderou a engenharia do Flickr – um dos maiores provedores de tal conteúdo na época) e Richard Crowley, eles juntos tiveram uma ideia para um padrão aberto para obter código de incorporação de um URL. Henderson foi embora e elaborou algo com base na discussão, e o Embed nasceu.

Usando oEmbed

Aqui está como funciona.

Ele começa com a URL que aponta para um único item de conteúdo. Pode ser um vídeo do YouTube, uma imagem ou qualquer outra coisa. Normalmente, isso será fornecido por um usuário do seu site ou aplicativo como parte de algum conteúdo que deseja publicar. O primeiro passo é buscar o conteúdo da página nesse URL, que deve ser uma página HTML.

Se o site que hospeda o conteúdo suporta oEmbed, na seção <head> dessa página deve haver um elemento de link com um tipo de conteúdo oembed :

 <link rel="alternate" type="application/json+oembed" href="https://youtube.com/oembed?url=https%3A%2F%2Fyoutu.be%2Fjw7bRnFbwAI&format=json" title="Inclusive Components with Heydon Pickering" />

Uma observação sobre XML: oEmbed oferece suporte a respostas nos formatos XML e JSON. Para este artigo, estou considerando apenas JSON, porque não somos selvagens. Se você estiver na infeliz posição de precisar trabalhar com XML, esteja ciente de que é um formato compatível com a especificação oEmbed, embora você possa descobrir que alguns provedores oferecem apenas respostas JSON.

Essa tag de link como o atributo rel definido como alternate e um type definido como application/json+oembed ou text/xml+oembed . É esse atributo que nos indica o fato de que a URL fornecida no href é na verdade um endpoint da API oEmbed para recuperar os detalhes do conteúdo.

Esse URL geralmente terá dois parâmetros: url e format .

Parâmetro	Valor
`url` (obrigatório)	O endereço da Web codificado por URL do item de conteúdo
`format`	O formato em que você deseja a resposta. Um de `json` ou `xml`

Parâmetros de URL comuns para a solicitação inicial do consumidor

A especificação completa entra em muito mais detalhes aqui (e você deve fazer referência a isso se estiver criando sua própria implementação), mas esses são os dois parâmetros que você provavelmente verá mais.

Então, temos uma URL, buscamos a página, encontramos uma tag de link oEmbed com outra URL para um endpoint de API. Em seguida, solicitamos esse novo URL, e isso retorna todas as informações que o serviço precisa fornecer sobre esse conteúdo.

 { "author_name": "Smashing Magazine", "width": 480, "title": "Smashing TV: Inclusive Components with Heydon Pickering (Nov 7th 2019)", "provider_name": "YouTube", "height": 270, "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/jw7bRnFbwAI?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>", "provider_url": "https://www.youtube.com/", "thumbnail_url": "https://i.ytimg.com/vi/jw7bRnFbwAI/hqdefault.jpg", "type": "video", "thumbnail_height": 360, "author_url": "https://www.youtube.com/channel/UCSDtqcJ8ZXviPrEcj1vuLiQ", "version": "1.0", "thumbnail_width": 480 }

Agora estamos a falar! A resposta nos dá muitas informações sobre o conteúdo. A version deve no futuro próximo ser 1.0 , que é a versão atual da especificação oEmbed. As outras informações retornadas dependem muito do valor de type .

Tipos de resposta

O valor da chave de type na resposta informa que tipo de mídia você incorporará.

Valor do `type`	O que esperar
`photo`	Uma foto estática que oferece um `url` , `width` e `height` que podem ser usadas para uma tag `img` básica
`video`	Um player de vídeo, com `html` especificando o código necessário para incorporar um player em uma página, embora com `width` e `height`
`link`	A melhor maneira de lidar com esse conteúdo é apenas fornecer um link, afinal. A resposta pode ter outras informações úteis, como um título, mas deve ser apenas vinculada.
`rich`	Algum tipo de player de conteúdo rico, que, assim como o tipo de vídeo, retorna `html` , `width` e `height`

Além do conteúdo de vídeo dedicado, o tipo mais comum que você provavelmente verá na natureza é rich . Mesmo o próprio Flickr, enquanto ainda envia uma resposta de photo , também fornece html para um rico 'player' incorporável para a imagem também.

Na maioria das vezes, incorporar o conteúdo em seu site é apenas um caso de usar o código fornecido como valor html .

Uma nota sobre segurança

Uma coisa com a qual você pode ser cauteloso é pegar uma resposta HTML e incorporá-la programaticamente em uma página que você hospeda. Sem a etapa humana de verificar novamente o código que você está colando, sempre há potencial para que esse código seja malicioso. Como tal, você deve tomar as medidas apropriadas para mitigar o risco.

Isso pode incluir filtrar os URLs para garantir que os esquemas e domínios correspondam aos esperados e colocar o código de sandbox em um iframe em um domínio diferente e sem cookies. Você deve acessar a situação em que está usando o código e certificar-se de que não está se expondo a riscos indevidos.

Começando

Por mais importante que seja entender o processo ao usar oEmbed, a realidade é que as linguagens mais comuns têm bibliotecas disponíveis que abstraem o processo e o tornam relativamente simples.

Por exemplo, o oembed empacotado npm fornece uma interface muito simples para fazer uma solicitação com base na URL do conteúdo e obter a resposta oEmbed de volta.

Primeiro instale o pacote em seu projeto:

 npm i oembed

E, em seguida, solicite o URL. Aqui estou usando a URL de uma apresentação no Notist que fiz sobre oEmbed. Como muito meta.

 const oembed = require('oembed'); const url = 'https://noti.st/drewm/ZOFFfI'; oembed.fetch(url, { maxwidth: 1920 }, function(error, result) { if (error) console.error(error); else console.log("oEmbed result", result); });

E a resposta:

 { type: 'rich', version: '1.0', title: 'Understanding oEmbed', author_name: 'Drew McLellan', author_url: 'https://noti.st/drewm', provider_name: 'Notist', provider_url: 'https://noti.st', cache_age: 604800, thumbnail_url: 'https://on.notist.cloud/slides/deck4179/large-0.png', thumbnail_width: 1600, thumbnail_height: 900, html: '<p data-notist="drewm/ZOFFfI">View <a href="https://noti.st/drewm/ZOFFfI">Understanding oEmbed</a> on Notist.</p><script async src="https://on.notist.cloud/embed/002.js"></script>', width: 960, height: 540 }

Se você quiser fazer o mesmo em PHP, um pacote prático chamado embed/embed está disponível para instalação via Composer.

 composer require embed/embed

E então no seu projeto PHP:

 use Embed\Embed; $info = Embed::create('https://noti.st/drewm/ZOFFfI'); $info->title; // "Understanding oEmbed" $info->authorName; // "Drew McLellan $info->code; // "<p data-notist="drewm/ZOFFfI"> ... </script>"

Como você pode ver, com o uso de uma biblioteca o processo se torna muito simples e você pode ir rapidamente de uma URL para o código de incorporação, pronto para mostrar uma rica representação do conteúdo do usuário.

Conclusão

oEmbed é uma solução muito elegante para um problema muito específico. Você seria perdoado por pensar que apenas alguns engenheiros trabalhando em grandes redes sociais se beneficiariam disso, mas, na realidade, sistemas de publicação em que um usuário pode inserir uma URL são surpreendentemente comuns. Encontre-me um engenheiro de back-end que em algum momento não precisou construir algum tipo de CMS. Podemos não pensar nisso nos mesmos termos, mas se você aceitar a entrada do usuário, deve pensar no que fazer se essa entrada contiver URLs.

Agora que você conhece o oEmbed (desculpe), você não tem desculpa para não considerar seriamente como você lida com URLs em seus projetos futuros.

o Especificação de incorporação
oembed para NodeJS
incorporar/incorporar para PHP
“Anunciando o OEmbed: um padrão aberto para conteúdo incorporado”, Leah Culver