O Discourse tem a capacidade de incorporar os comentários de um tópico em um site remoto usando uma API Javascript que cria um IFRAME. Para um exemplo disso em ação, confira o blog Coding Horror. O blog é executado via Ghost, mas os comentários são incorporados do seu fórum Discourse.
Uma coisa importante a notar com essa configuração é que os usuários precisam navegar até o seu fórum para postar respostas. Isso é intencional, pois acreditamos que a interface de postagem em um fórum Discourse é atualmente muito mais rica do que o que poderíamos incorporar via Javascript.
Este guia mostrará como configurar a incorporação de comentários no seu próprio blog ou site.
Como funciona
No Discourse, um tópico é composto por várias postagens. Quando você está incorporando o Discourse em outro site, você está vinculando um documento (entrada de blog, página HTML, etc.) a um único tópico. Quando as pessoas postam naquele tópico, seus comentários aparecerão automaticamente na página em que você o incorporou.
Você tem a opção de fazer com que o Discourse crie os tópicos automaticamente quando uma nova incorporação é encontrada, ou pode criar os tópicos você mesmo com antecedência.
Configurando o Discourse para Incorporação (configuração simples)
A configuração a seguir incorporará um feed de comentários em uma página com a URL de um blog falso de http://example.com/blog/entry-123.html, a partir de um fórum discourse executado em =DISCOURSE=.
Domínio para
Domínio para
-
Visite Admin > Personalizar > Incorporação na sua instalação do Discourse. https://=DISCOURSE=/admin/customize/embedding
-
Crie pelo menos um Host Incorporável (Embeddable Host). Este deve ser o nome do host (domínio) onde você deseja incorporar seus comentários. Neste caso, o host é
=BLOG=– note a ausência dehttp://e caminho.-
Lista de Permissão de Caminhos (Path Allowlist) permite que você especifique os caminhos no host remoto que aceitarão sua incorporação.
-
Postar na Categoria (Post to Category) - se você fornecer uma categoria junto com o host que está inserindo, as postagens importadas daquele host acabarão automaticamente naquela categoria. Diferentes hosts podem postar em diferentes categorias.
-
Tags - você pode atribuir tags para serem aplicadas automaticamente aos tópicos criados a partir de um determinado host.
-
Autor da Postagem (Post Author) - você pode opcionalmente substituir o usuário de criação do tópico com base no host. Se não for definido, o padrão da guia Postagens e Tópicos (Posts and Topics) será usado.
-
-
Navegue até a guia Postagens e Tópicos (Posts and Topics) e preencha o campo Nome de Usuário para criação de tópico (Username for topic creation). Este é o usuário que criará tópicos quando novas incorporações forem encontradas. Vamos supor que nosso discourse tenha um usuário chamado eviltrout, então o valor é
eviltrout. -
Insira o seguinte HTML na página da web em
http://=BLOG=/blog/entry-123.html
<div id='discourse-comments'></div>
<script type="text/javascript">
DiscourseEmbed = {
discourseUrl: 'https://discourse.example.com/',
discourseEmbedUrl: 'http://example.com/blog/entry-123.html',
// className: 'CLASS_NAME',
};
(function() {
var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
d.src = DiscourseEmbed.discourseUrl + 'javascripts/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
})();
</script>
As partes configuráveis do snippet estão no objeto DiscourseEmbed. discourseUrl é o caminho completo para a base do seu discourse, incluindo a barra final. O discourseEmbedUrl é o documento que está atualmente incorporando um feed de comentários.
Se você configurar isso corretamente, na primeira vez que visitar http://=BLOG=/blog/entry-123.html ele tentará carregar os comentários para a postagem do blog. Como não há nenhum, ele informará ao fórum Discourse para criar um novo tópico em segundo plano. Um novo tópico será criado por eviltrout e o conteúdo da primeira postagem será rastreado do seu blog e o texto será extraído automaticamente.
Assim que o novo tópico for criado, os usuários poderão postar nele, e seus comentários serão exibidos automaticamente na próxima vez que http://=BLOG=/blog/entry-123.html for visitado.
className é opcional e adicionará uma classe de sua escolha à incorporação para que você possa personalizá-la com CSS.
Dica: Se o seu blog tiver vários autores, você pode adicionar uma tag
<meta name="discourse-username" content="author_username">a cada página. Quando o Discourse rastrear a página para criar o tópico, ele usará esta meta tag para determinar o autor da postagem, substituindo o nome de usuário padrão definido nas configurações de administração.
Incorporando em mais de uma página
No exemplo acima, codificamos nossa URL http://=BLOG=/blog/entry-123.html ao incorporar o trecho de Javascript. Isso geralmente não será suficiente, pois muitos sites têm muitas páginas geradas automaticamente. Por exemplo, em um blog, cada entrada geralmente recebe sua própria página. Para suportar isso, coloque o mesmo snippet em cada página em que deseja exibir comentários, mas substitua o valor passado para discourseEmbedUrl pela URL da página atual. No meu blog, eu uso o seguinte valor para discourseEmbedUrl: 'http://eviltrout.com<%= current_page.url %>' – à medida que novas páginas de blog são criadas, novos tópicos serão criados para elas automaticamente no Discourse.
Estilizando seu conteúdo incorporado
Você tem a capacidade de adicionar uma folha de estilos para seus comentários incorporados. Use a seção CSS Incorporado (Embedded CSS) do editor de Tema em Admin > Personalizar > Temas > [seu tema] > Editar CSS/HTML e você pode adicionar uma folha de estilos personalizada que será servida com seus comentários incorporados. Por padrão, achamos que o layout fica bom em um fundo branco, mas se o seu site tiver um layout exclusivo, você vai querer estilizá-lo você mesmo.
(Opcional) Adicionando um Feed para Sondagem (Polling)
Conforme mencionado acima, o Discourse rastreará automaticamente qualquer site em que esteja incorporado. No entanto, às vezes o HTML pode ser difícil de analisar e pode não extrair o conteúdo de suas postagens corretamente. Muitos blogs e sites suportam feeds RSS/Atom para sindicação, e o Discourse pode usar isso para extrair o conteúdo de suas postagens de blog com mais precisão.
O Discourse vem com o plugin de Sondagem RSS (RSS Polling plugin) (incluído por padrão). Se você tiver um feed RSS ou Atom configurado no site em que está incorporando o Discourse, poderá ativar a configuração do site rss_polling_enabled e adicionar a URL do seu feed via Admin > Plugins > Sondagem RSS (RSS Polling). Assim que o URL do feed for adicionado, o Discourse analisará o feed e publicará suas postagens na categoria apropriada com base nos Hosts Permitidos que você adiciona às suas configurações de Incorporação.
(Configuração Alternativa) Vinculando a tópicos existentes
Algumas pessoas preferem não fazer com que o Discourse crie tópicos para elas automaticamente em seus fóruns. Elas gostariam de criar os tópicos elas mesmas e, em seguida, simplesmente informar ao código de incorporação qual tópico desejam associar. Você pode fazer isso alterando ligeiramente seu código de incorporação:
<div id='discourse-comments'></div>
<script type="text/javascript">
window.DiscourseEmbed = {
discourseUrl: 'https://=DISCOURSE=/',
topicId: 12345
};
(function() {
var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
d.src = window.DiscourseEmbed.discourseUrl + 'javascripts/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
})();
</script>
A única diferença aqui é que substituímos discourseEmbedUrl pelo ID de um tópico do Discourse. Se você fizer isso, nenhum tópico será criado e os comentários daquele tópico serão exibidos automaticamente.
Definindo a política de remetente (referrer policy)
Devido a mudanças recentes (setembro de 2020) na política de remetente padrão definida pela maioria dos navegadores, o Discourse agora define explicitamente a política de remetente do iframe como "no-referrer-when-downgrade". Se, por razões de segurança, seu site exigir uma política de remetente mais rigorosa, ela pode ser definida adicionando um valor discourseReferrerPolicy ao objeto DiscourseEmbed do script de incorporação. Por exemplo:
DiscourseEmbed = { discourseUrl: 'https://forum.example.com/',
discourseEmbedUrl: '<your_posts_canonical_URL>',
discourseReferrerPolicy: 'strict-origin-when-cross-origin'};
Consultando programaticamente os detalhes da Incorporação
Temos um endpoint de API para consultar os detalhes da Incorporação usando o embed_url como parâmetro:
curl 'https://meta.discourse.org/embed/info?embed_url=https://blog.discourse.org/2021/04/discourse-team-grows-to-50' -H 'API-KEY: logapikeygoeshere' -H 'API-USERNAME: apiusernamehere'
E a resposta é:
{
"topic_id": 187794,
"post_id": 925017,
"topic_slug": "discourse-team-grows-to-50-blog",
"comment_count": 2
}
Incorporando comentários de um site privado
Para instâncias privadas do Discourse, se o Discourse estiver em um subdomínio do domínio do blog, os comentários serão exibidos para usuários que estão logados no Discourse. Usuários que não estão logados no Discourse verão uma mensagem de ‘recusado a conectar’. Se o Discourse e o blog estiverem em domínios completamente separados, nenhum comentário será exibido para fóruns privados.
Solução de problemas
O problema mais comum que os usuários encontram ao incorporar o Discourse é definir o valor correto para os hosts incorporáveis que você adicionou. Certifique-se de verificar novamente se é apenas o domínio do seu site e se não contém barras extras ou caracteres inválidos.
thanks!
