Series Configuration

It's possible to group series configuration in one place, using a {series} block and a JSON file. This series data will be used for Next Up stories and in the Next Up roadblock.

The {series} block should be configured for each story in a series. The advantage here is that the same block can be copied into each story. When the underlying JSON file is updated, every story will get the same update at once.

Main Configuration:

{series}
url: https://www.gannett-cdn.com/usat-storytelling/marx/_series.json
{}

Required properties and options

Value	Purpose	Required
`url`	A URL pointing to a JSON file on the CDN	Yes

About the JSON

One way to create a series in In-Depth is to create a single JSON file listing all elements in a project.

The main JSON

value	purpose	required	default
`title`	A short name or project title	No.	-
`image`	Some components that display series data will use an overview image for the project. This should be an absolute URL to an image on the CDN.	No.	-
`boostLocal`	If `true` then stories in this project deemed "local" to the reader will be served up before others.	No.	`false`
`boostLocalState`	If `true` then stories from the same state as the reader will be served up before others.	No.	`false`
`items`	A list, or array/`[]`, of story items.	Yes	-

Stories/items

Each item in the items array supports these properties. Not all components that use series data will use all of them.

value	purpose	required	default
`label`	An optional kicker to be displayed above the main story headline.	No.	-
`image`	Most, but not all, series components use a story image. Supply one here as an absolute URL to the CDN.	No.	-
`title`	The article headline	Yes	-
`link`	The absolute URL to the article or content	Yes	-
`prestoID`	Some stories can be provided as a presto ID	No	-
`buttonText` .	The link button text.	No	"Read more"
`isPrimaryStory`	If set to `true`, the article will be treated as a mainbar when `boostLocal` is in use	No	`false`
`isSportsPlus`	Use for premium sports stories; if set to `true`, the article will get a "FOR SUBSCRIBERS" label and the Sports+ icon.	No	`false`
`isLive`	Some components will display "coming soon" links (which must be supplied by `link` url)	No	-

Example

Save your JSON file with a .json extension and upload using the In-Depth editor file uploader. The uploaded JSON file should look like this:

{
    "title": "The Migrants",
    "image": "https://www.gannett-cdn.com/presto/2019/09/20/USAT/b1bd33f5-30c2-4387-a69b-5caeaacbd286-XXX_MigrantCrisis_ORNELAS_0009.JPG",
    "boostLocal": true,
    "boostLocalState": true,
    "items": [
        {
            "label": "Story",
            "image": "https://www.gannett-cdn.com/presto/2019/09/20/USAT/b1bd33f5-30c2-4387-a69b-5caeaacbd286-XXX_MigrantCrisis_ORNELAS_0009.JPG",
            "title": "One deadly week reveals where the immigration crisis begins — and where it ends",
            "link": "https://www.usatoday.com/in-depth/news/2019/09/23/immigration-crisis-migrants-us-mexico-border/2022670001/",
            "prestoID": "2022670001",
            "buttonText": "Read more",
            "isPrimaryStory": true
        },
        {
            "label": "Story in Spanish",
            "image": "https://www.gannett-cdn.com/presto/2019/09/23/USAT/189bc00c-bdc0-4313-ac6c-3a054f7a6a62-XXX_MigrantCrisis_ORNELAS_0035_1.JPG",
            "title": "Una semana mortal revela dónde comienza la crisis migratoria - y dónde termina",
            "link": "https://www.usatoday.com/in-depth/news/nation/2019/09/23/la-frontera-mexico-eeuu-migrantes-immigracion-oscar-martinez-ramirez/2377925001/",
            "buttonText": "Leer más",
            "skipNextUp": true
        },
        {
            "label": "Story",
            "image": "https://www.gannett-cdn.com/presto/2019/08/15/USAT/952012f3-054e-434a-88f8-4814faa4eab4-IMG_7716.jpg",
            "title": "College football boosters help propel 'arms race' for coaches. It's out of control.",
            "link": "https://www.usatoday.com/in-depth/sports/ncaaf/2022/10/13/college-football-highest-paid-coaches-boosters/8130346001/",
            "buttonText": "Read more",
            "isSportsPlus": true
        }
    ]
}

Tip

If you get errors trying to upload the file, try checking your data for mistakes/errors using any of the myriad JSON tools available online, such as JSONLint. The necessary formatting/syntax is specific in certain ways and writing data like this can be tricky. Don't hesitate to reach out in the In-Depth channel in Microsoft Teams for help.

Next Up with series configuration

When using the {series} block, Next Up will automatically be configured for each story. A reader starting on the first story will see each part of the series in the order defined in the JSON file (unless that story has "skipNextUp": true set).

Move local stories to the front of the line

For a network-wide series that contains one or more local stories, it's possible to move the local stories to the front of the line so that they load next. For example, a Storyline created in Presto with several usatoday.com stories and a single desmoinesregister.com story near the end would load the desmoinesregister.com story first. To accomplish that, the boostLocal variable can be configured in the series data JSON or in the series configuration in In-Depth, but the JSON value is preferred.

For regional or national series, it may be helpful to the reader to see stories about their own state's affairs first. Use the boostLocalState switch in the JSON to configure that. Then, if a series includes stories from dailyamerican.com in Pennsylvania and app.com in New Jersey, a reader from northjersey.com would see the app.com story next.

To make sure a more important story is queued up next before local stories, such as one or more mainbar stories, label them with isPrimaryStory in the series data JSON file.

With all these different domains, you don't have to worry about users hitting paywalls on other sites. We automatically switch article links to relative links so their home subscription unlocks other articles in the series.

Value	Purpose	Required
`isPrimaryStory`	Set to "true" to load this story first	No
`boostLocal`	Set it to "true" to load local stories first, but after primary stories	No
`boostLocalState`	Set it to "true" to load same-state stories after local stories	No

Skipping stories

In the above JSON file, the Spanish version is excluded from the Next Up sequence. Set "skipNextUp": true to take a story out of the Next Up chain.

Series roadblock

When using the Next Up roadblock and {series} configuration together, the roadblock will show additional stories in the series as a way to highlight the value of a subscription.

Series roadblock

This adds additional configuration options to the Next Up roadblock:

Value	Purpose	Default	Required
`enable`	turn on the roadblock; defaults to true	`true`	Yes
`label`	text above the roadblock headline		No
`headline`	main headline on the roadblock		No
`buttonText`	text on the button		No
`buttonURL`	point to an offers page	(will auto-generate if blank)	No
`limit`	how many paragraphs to show before the roadblock		No
`seriesHeader`	series title	`title` field in the series JSON file	No
`seriesSubheader`	override the default subheading in the series roadblock	"This series includes:"	No

See Next Up roadblock for more on the non-series roadblock options.