Skip to main content

Integrating on your site

With Coral setup and running locally you can find your Embed code under Configure > Organization > Site Details (when logged in as an ADMIN). It should look something like this, but with your domain in place of CORAL_DOMAIN_NAME. You can test placing the comment stream embed on your page with this sample embed script:

<div id="coral_thread"></div><script type="text/javascript">  (function () {    var d = document,      s = d.createElement("script");    var URL = "{{ CORAL_DOMAIN_NAME }}";    s.src = "//" + URL + "/assets/js/embed.js";    s.async = false;    s.defer = true;    s.onload = function () {      Coral.createStreamEmbed({        id: "coral_thread",        autoRender: true,        rootURL: "//" + URL,      });    };    (d.head || d.body).appendChild(s);  })();</script>`;

Options#

Options object for createStreamEmbed:

  • id - [string] (required): ID of a DOM element on the page into which the comment stream will be rendered.
  • rootURL - [string] (required): The root URL of the coral installation.
  • storyID - [string] (optional): ID for the story. May alternately specify via storyURL or allow Coral to scrape and determine automatically.
  • storyURL - [string] (optional): URL for the story. May alternately specify via storyID or allow Coral to scrape and determine automatically.
  • accessToken - [string] (optional): Access token to log in a user via SSO.
  • refreshAccessToken - [function] (optional): Callback to obtain a new access token when the current one has expired. A parameter nextAccessToken is passed as the first argument that should be called with the next access token.
  • bodyClassName - [string] (optional): HTML class name to add to the body of the stream embed iframe for CSS targeting.
  • customCSSURL - [string] (optional): URL for a custom stylesheet to be included for this stream. To configure a custom stylesheet for all streams, see advanced configuration options in the admin.
  • autoRender - [boolean] (optional): Render the comment stream automatically when the element is scrolled into the viewport
  • title - [string] (optional): Title for the coral iframe. Defaults to "Coral Stream Embed".
  • amp - [boolean] (optional): enable support for Accelerated Mobile Pages

NOTE: Replace the value of {{ CORAL_DOMAIN_NAME }} with the location of your running instance of Coral.

Story Creation#

Lazy Story Creation enables stories to be automatically created when they are published from your CMS. Triggering the embed script above renders the comment stream iframe on your page. By default that script dynamically generates Stories in Coral for seamless integration.

storyURL#

If you do not specify a storyURL when rendering the embed, the storyURL is first inferred from the Canonical link element, which takes the form of a <link> element in your <head> of the page:

<!DOCTYPE html><html>  <head>    <link rel="canonical" href="https://example.com/page" />  </head>  <body>    ...  </body></html>

The URL must reference an existing Permitted Domain. If your articles/stories always have unique URLs, then you will not need to modify the default behavior.

If this tag is not present, or if the canonical URL references a different URL than your site such as a wire service, you can specify the storyURL parameter in the render function.

The URL will be used by Coral to build user facing links, and should reference the location where you would direct a user back to this particular story or article.

storyID#

To more tightly couple Coral with your CMS you can provide your CMS's unique identifier to Coral by including a storyID parameter in the render function. Doing so will allow you to target the Story for later updates via Coral's Graphql API, such as updating the URL if it changes.

Integration via API#

Story creation can also be controlled by direct calls to Coral's API. When Lazy Story Creation is disabled embed streams can only be created by data migration or API POST request.

See GraphQL API Overview for help with the API.

Story Scraping#

By default, stories have their metadata scraped when they are loaded. This provides the easiest way for newsrooms to integrate their CMS’s into Coral in a simple way. We use the following meta tags on the target pages that allow us to extract some properties.

Metadata scraping is performed by the scraper job which is enabled by default.

If your production site is behind a paywall or otherwise prevents scraping, you might need to configure a Scraper Proxy URL. When specified it allows scraping requests to use the provided proxy. All requests are then passed through the appropriate proxy as parsed by the npm proxy-agent package.

Asset PropertySelector
titleSee metascraper-title
descriptionSee metascraper-description
imageSee metascraper-image
authorSee metascraper-author
publication_dateSee metascraper-date
modified_datemeta[property="article:modified"]
sectionmeta[property="article:section"]