Custom embedded code

Warning

This is an advanced feature requiring intermediate programming skills. It wouldn't hurt to mention it early to the Storytelling Studio. Vaya con dios.

Arbitrary markup can be injected directly into the story, effectively becoming part of the in-depth article. This includes HTML content, <script> tags and <link> elements, such as stylesheets. Presto only understands images and video. In-Depth can swap those items for custom-built interactives. You design and build an app, deploy it to the CDN and put it right into an in-depth story.

Examples of storytelling embeds:

How do I make one?

TL;DR: However you like. Just put it on the CDN.

Choose your own tools and processes. Use your own methods. Develop and edit locally, independent of the in-depth production. As long as you can produce a single HTML snippet with all the needed markup and put it on the the Gannett CDN (aka Google Cloud Storage).

For security reasons, the CDN is the only place from which In-Depth will pull code. Each storage bucket must be added to the Allowed List. Presently, only a few buckets are supported, but we can add more: https://www.gannett-cdn.com/usat-storytelling and https://www.gannett-cdn.com/labs are chief among them.

Assuming you are working with the labs bucket, your code must be uploaded to /labs/master/{project_dir}/ and the file with the code you want injected into the story should be at /labs/master/{project_dir}/embed.html. You can have as many different embed files in project directory as you like, but each will need to be configured in the in-depth story individually.

Where should I put my code?

TL;DR: GITHUB!

Detailed version: GITHUB! Seriously! It's difficult to consult and collaborate on projects with code that only lives on your personal computer. Please use git repositories to let the Storytelling Studio help you. Remember that your code is part of an existing <article>.

Your code should include only what your app needs to run. An in-depth article already is a complete web page. Your code does not need an <html>, <head> or <body> tag, nor does it need (probably) any <meta> tags. Perhaps you have built an interactive using SvelteJS. Your embed code would look something like:

<div id="app"></div>
<script src="https://www.gannett-cdn.com/path/to/bundle.js">
<link href="https://www.gannett-cdn.com/path/to/bundle.css">

Avoid collisions

In-depth exists inside an existing framework — Universal Web — with its own naming conventions and styles. To make your life easier, it's recommended you namespace your styles and avoid common classnames. For example, if your graphic is a database, then the CSS class .db-container would be preferable to just .container which already has defined properties.

Similarly, bundled javascript and/or code wrapped in an immediately invoked function will ensure your code doesn't negatively interact with the existing page functions.

Use absolute paths

All linked assets — including javascript, stylesheets and images — should use absolute URLs. Relative links will break.

Use the in-depth framework

In-depth uses a series of techniques, including css variables, to create a flexible and consistent experience. By using these techniques in your design, your content will automatically adapt to the visual styles configured by the in-depth producer.

Colors

Use the following css variables to pickup style choices automatically:

CSS Variable Purpose
--theme-color The article's configured accent color
--background-color This is the article's configured background.
--font-color This is the article's text color and will match the dark/light theme selection.

Typography

Consistent typography is one of the most important ways to create a seamless, unified experience for our readers. You don't need to do much styling of your typography, which includes font choices. In-depth uses Gannett's custom fonts "Unify" and "Unify Sans." YOU DO NOT NEED TO LOAD THESE FONTS YOURSELF. In-depth already comes does that and offers these css variables any place you would set a CSS font-family:

CSS Variable Purpose
--fonts-serif The main serif typefaces. The top option is Georgia.
--fonts-sans-serif The main sans-serif typefaces. The top option is Unify Sans.

You should use these fonts in nearly all cases.

Content alignment

Uniform content alignment creates a clean presentation. The main content well in an in-depth story is created with padding on the main article element using padding: 0 var(--article-padding-horiz). By default, your content will stretch from screen edge to edge in its full-width container. To align with the content width, add this padding to you container. There is a companion variable, --article-padding-horiz-neg, which can be used as a negative margin to stretch an element full width.

Analytics

One of the great added values of working with storytelling embeds, instead of iframes, is analytics. By default, in-depth supports click/tap events on any HTML element with a data-analytics-event-on-click="event-string" attribute. That's all you need to track your buttons and links. If you have other UI elements needing tracking, such as scrolling elements or sliders, then hit up someone in the Storytelling Studio. We'll always make time to help add tracking.

Test test test!

Test your embed in an actual in-depth story as early as possible. There surely will be modifications needed. It's best to find those out early. If you need help, someone from the Storytelling Studio can assist.

Deploying your code

Feel free to use any method you like to get your code onto the CDN. The Storytelling Studio uses the official Google Cloud Storage command line utility and some version of this script. It's pretty straightforward, but requires modification to work with your CDN bucket and needs your project directory to be structured a certain way:

  1. Assume you have a project directory project_dir
  2. Put the deploy script in there (project_dir/deploy.sh) and make it executable.
  3. This script will deploy anything in project_dir/public/, so if you don’t have a public directory, then make one.
  4. Any scripts, stylesheets, node_modules and other stuff in project_dir is just for you and will not deploy. Anything in project_dir/public should be the final, working files and will end up on the CDN, publicly available. cd into project_dir. Run the terminal command ./deploy.sh to put everything in project_dir/public at https://gannett-cdn.com/{bucket}/dev/project_dir.
  5. Run the terminal command ./deploy.sh --production to put everything in project_dir/public at https://gannett-cdn.com/{bucket}/master/project_dir

You will need to set one environment variable, probably best done in your .bash_profile or .env. CDN_AUTH should be the authorization key for your CDN bucket. Using this script will bust the cache for you, too, which will save you from lots of headaches.

Configuring in-depth

Embeds are placed using the targeted-asset approach, so an asset needs to be placed into the story in Presto (more on that in "What about Google ..."). This asset will be replaced by the code in your embed file.

Allowed CDN buckets

CDN Bucket Config value
Storytelling (default) n/a
Delaware delaware-online
USAT Graphics/Experiments experiments-www-gannett-cdn-com
Innovation Lab labs-www-gannett-cdn-com
West Production Hub west-hub-production

If you have a different CDN bucket you want to use, then contact the Storytelling Studio. If you are using Amazon storage (AWS, S3, etc.) then for sure reach out. We don't support Amazon CDN, but we can talk about it.

Example markup

{assets.123456}
storytellingEmbed: test-project/filename.html
bucket: labs-www-gannett-cdn-com
{}

What about Google AMP, Facebook and Apple News?

The content of the embed will not appear on Apple News, Google Amp or Facebook articles. To ensure maximum exposure, you’ll need something in presto to ensure all audiences are exposed to your content. There are a couple of recommended ways to do this (though certainly not the only solutions):