Posted To: Press Releases

J-Lab partners with CUNY to create e-guide

Washington, D.C.– “Law for Media Startups,” a new resource for entrepreneurs launching news ventures and educators teaching students how to do it, was published today by CUNY’s Tow-Knight Center for Entrepreneurial Journalism.

The 12-chapter web guide was written by Jan Schaffer, J-Lab executive director, and Jeff Kosseff, media lawyer for Covington & Burling LLP law firm in Washington, D.C. The Tow-Knight Center supported the research, writing and production as part of its suite of entrepreneurial journalism resources.

“This guide goes beyond traditional First Amendment law to address every-day issues news entrepreneurs confront,” Schaffer said. “From native advertising to labor law and fair use, it supplies what I found missing for my students.”

"Every day, innovators are developing new ways to deliver news and content to consumers," Kosseff said. "I hope this guide helps them identify the legal issues that they should be considering as they build their business models."

Small digital news startups are facing a range of legal issues as they set up their business operations, gather and report the news, protect their content, and market and support their news ventures. They need to know classic First Amendment law – and much more. This guide offers an introduction to many of those issues, from hiring freelancers and establishing organizational structures, to native advertising and marketing, to maintaining privacy policies and dealing with libel accusations. It seeks to help jumpstart the launch of news ventures and help entrepreneurs know when to seek professional legal help.

“The news ecosystem of the future will be made up of enterprises of many sizes, shapes, and forms, including journalistic startups that need help with their businesses and the law” said Jeff Jarvis, Director of the Tow-Knight Center. “Jan Schaffer and Jeff Kosseff provide an invaluable guide to help them recognize legal pitfalls. It complements other research from Tow-Knight on a variety of business practices.”

Jeff Kosseff is a communications and privacy attorney in Covington & Burling’s Washington, D.C. office, where he represents and advises media and technology companies. He is co-chair of the Media Law Resource Center’s legislative affairs committee. He clerked for Judge Milan D. Smith, Jr. of the U.S. Court of Appeals for the Ninth Circuit and Judge Leonie M. Brinkema of the U.S. District Court for the Eastern District of Virginia. He is an adjunct professor of communications law at American University, where he teaches in its MA in Media Entrepreneurship program. Before becoming a lawyer, Kosseff was a journalist for The Oregonian and was a finalist for the Pulitzer Prize and recipient of the George Polk Award for national reporting.

Jan Schaffer is executive director of J-Lab, an incubator for news entrepreneurs and innovators, and Entrepreneur in Residence at American University’s School of Communication, where she also teaches in its MA in Media Entrepreneurship program. She launched J-Lab in 2002 to help newsrooms use digital technologies to engage people in public issues. It has funded 100 news startups and pilot collaboration projects and it has commissioned and developed a series of online journalism resources that include Launching a Nonprofit News Site, Top Ten Rules for Limited Legal Risk and The Journalist’s Guide to Open Government. As the federal court reporter for The Philadelphia Inquirer, she was part of a team awarded the Pulitzer Gold Medal for Public Service for a series of stories that won freedom for a man wrongly convicted of five murders and led to the civil rights convictions of six Philadelphia homicide detectives.

The “Law for Media Startups” guide also invites media lawyers around the country to contribute information on state-specific laws that apply to news entrepreneurs, following the guide’s template for laws in Virginia.

J-Lab is a journalism catalyst that has provided funding and resources for news startups. It has funded 100 startups and pilot projects since 2005.

The Tow-Knight Center for Entrepreneurial Journalism offers educational programs, supports research, and sponsors events to foster sustainable business models for quality journalism. It is part of the City University of New York's Graduate School of Journalism, and funded by The Tow Foundation and The Knight Foundation.

Suyeon Son and David Eads re-worked the authentication mechanism for accessing Google Spreadsheets with the NPR Visuals App Template. This is a significant change for App Template users. Here’s why we did it and how it works.

Most App Template developers only need to consult the Configuring your system and Authenticating sections of this post, provided someone on your team has gone through the process of creating a Google API application and given you credentials.

Why OAuth?

Prior to this change, the App Template accessed Google spreadsheets with a user account and password. These account details were accessed from environment variables stored in cleartext. Storing a password in cleartext is a bad security practice, and the method led to other dubious practices like sharing credentials for a common Google account.

OAuth is a protocol for accessing online resources on behalf of a user without a password. The user must authenticate with the service using her password to allow the app to act on her behalf. In turn the app receives a magic access token. Instead of directly authenticating the user with the service, the application uses the token to access resources.

There are many advantages to this approach. These access tokens can be revoked or invalidated. If used properly, OAuth credentials are always tied to an individual user account. An application can force all users to re-authenticate by resetting the application credentials. Accessing Google Drive resources with this method is also quite a bit faster than our previous technique.

Setting up the Google API application

To use the new OAuth feature of the App Template, you will need to create a Google API project and generate credentials. Typically, you’ll only need to do this once for your entire organization.

Visit the Google Developer’s Console and click “Create Project”.

Give the project a name for the API dashboard and wait for the project to be created:

Give the project a name again (oh, technology!) by clicking “Consent screen” in the left hand toolbar:

Enable the Drive API by clicking “APIs” in the left hand toolbar, searching for “Drive” and enabling the Drive API:

You can optionally disable the default APIs if you’d like.

Finally, create client credentials by clicking “Credentials” in the left hand toolbar and then clicking “Create New Client ID”:

Make sure “Web application” is selected. Set the Javascript origins to “http://localhost:8000”, “http://127.0.0.1:8000”, “http://localhost:8888” and “http://127.0.0.1:8888”. Set the Authorized Redirect URIs to “http://localhost:8000/authenticate/”, “http://127.0.0.1:8000/authenticate/”, “http://localhost:8888/authenticate/” and “http://127.0.0.1:8888”.

Now you have some credentials:

Configuring your system

Whew! Happily, that’s the worst part. Typically, you should only do this once for your whole organization.

Add some environment variables to your .bash_profile or current shell session based on the client ID credentials you created above:

export GOOGLE_OAUTH_CLIENT_ID="825131989533-7kjnu270dqmreatb24evmlh264m8eq87.apps.googleusercontent.com"
export GOOGLE_OAUTH_CONSUMER_SECRET="oy8HFRpHlJ6RUiMxEggpHaTz"
export AUTHOMATIC_SALT="mysecretstring"

As you can see above, you also need to set a random string to act as cryptographic salt for the OAuth library the App Template uses.

Authenticating

Now, run fab app in your App Template project and go to localhost:8000 in your web browser. You’ll be asked to allow the application to access Google Drive on behalf of your account:

If you use multiple Google accounts, you might need to pick one:

Google would like you to know what you’re getting into:

That’s it. You’re good to go!

Bonus: Automatically reloading the spreadsheet

Any route decorated with the @oauth_required decorator can be passed a refresh=1 querystring parameter which will force the latest version of the spreadsheet to be downloaded (e.g. localhost:8000/?refresh=1).

This is intended to improve the local development experience when the spreadsheet is in flux.

Behind the scenes

The new system relies on the awesome Authomatic library (developed by a photojournalist!).

We provide a decorator in oauth.py that wraps a route with a check for valid credentials, and re-routes the user through the authentication workflow if the credentials don’t exist.

Here’s an example snippet to show how it works:

from flask import Flask, render_template
from oauth import oauth_required

app = Flask(__name__)

@app.route('/')
@oauth_required
def index():
    context = {
        ‘title’: ‘My awesome project’,
    }
    return render_template(‘index.html’, **context)

Authomatic provides an interface for serializing OAuth credentials. After successfully authenticating, the App Template writes serialized credentials to a file called ~/.google_oauth_credentials and reads them when needed.

By using the so-called “offline access” option, the credentials can live in perpetuity, though the access token will change from time-to-time. Our implementation hides this step in a function called get_credentials which automatically refreshes the credentials if necessary.

By default, credentials are global – once you’re authenticated for one app template project, you’re authenticated for them all. But some projects may require different credentials – perhaps you normally access the project spreadsheet using your USERNAME@YOURORG.ORG account, but for some reason need to access it using your OTHERUSERNAME@GMAIL.COM account. In this case you can specify a different credentials file in app_config.py by changing GOOGLE_OAUTH_CREDENTIALS_PATH:

GOOGLE_OAUTH_CREDENTIALS_PATH = '~/.special_project_credentials'

Finally, the Google Doc access mechanism has changed. If you need to access a Google spreadsheet that’s not involved with the default COPY rig, use the new get_document(key, file_path) helper function. The function takes two parameters: a spreadsheet key and path to write the exported Excel file. Here’s an example of what you might do:

from copytext import Copy
from oauth import get_document

def read_my_google_doc():
    file_path = 'data/extra_data.xlsx'
    get_document('0AlXMOHKxzQVRdHZuX1UycXplRlBfLVB0UVNldHJYZmc', file_path)
    data = Copy(file_path)

    for row in data['example_list']:
        print '%s: %s' % (row['term'], row['definition'])

read_my_google_doc()

Multivariate and AB testing are generally used to iterate on products over time. But what do you do when your product is always different, like the visual stories we tell?

For the past year, NPR Visuals has been iterating on a story format for picture stories that works like a slideshow, presenting full-width cards with photos, text and any other HTML elements. We have made various tweaks to the presentation, but since each story is substantially different, it’s hard to know definitively what works.

With three stories approaching launch in the middle of February (“A Brother And Sister In Love”, “Life After Death” and “A Photo I Love: Thomas Allen Harris”), we decided to test different ways to get a user to take action at the end of a story. We wanted to encourage users to support NPR or, in the case of “A Brother And Sister In Love” and “A Photo I Love”, to follow our new project Look At This on social media.

To find out, we conducted live experiments using multivariate testing, a research method that allows us to show users slightly different versions of the same page and assess which version people respond to more positively.

In multivariate testing, you determine a control scenario (something you already know) and form a hypothesis that a variation of that scenario would perform better than the control.

(Note: You will see the term multivariate testing, A/B testing or split testing to discuss experiments like this. While there is a technical difference between the implementation of these various methods, they all seek to accomplish the same thing so we are not going to worry too much about accuracy of the label for the purposes of discussing what we learned.)

In the control scenario we presented a user with a link to either 1) support public radio or 2) follow us on social media. We hypothesized that users would be more likely to take action if we presented them with a yes or no question that asked them how the story made them feel.

We call this question, which changed slightly on each project, the “Care Question”, as it always tried to gauge whether a user cared about a story.

The overall test model worked like this:

The test exposed two possible paths to users

When we ran the test, we showed half of users (who reached the final slide) the Care Question with two buttons, “Yes” and “No”. Clicking Yes brought them to one of the two actions listed above, clicking No revealed a prompt to email us feedback. The control group was shown the action we wanted them to take, without a preceeding question.

We were able to run these tests at about equal intervals with a small amount of code.

In this blog post, we will show the results, how we determined them and what we learned.

Process

When a user reached the conclusion slide, we sent an event to Google Analytics to log which set of tests ran.

We also tracked clicks on the “Yes” and “No” buttons of the Care Question, and clicks on the subsequent actions (support link, each of the follow links, and the feedback email link).

The Care Question used in A Brother And Sister In Love

Determining whether the results were statistically significant required some pretty complex calculations, which you can read about here. Luckily, Hubspot provides a simple-to-use calculator to determine the statistical significance of your results.

Significance is determined by the confidence interval, or how confident you can be that your numbers are not determined simply by randomness. Usually, a 95% confidence interval or greater is high enough to draw a conclusion. Using the calculator, we determined whether the difference in conversion rates (where conversion rate is defined as clicks over the number of times a particular test was run) was statistically significant.

“A Brother And Sister In Love”

The test for “A Brother And Sister In Love” was actually two separate A/B tests at the same time: whether a user was prompted to follow Look At This on social media or support NPR by donating. For each scenario, users were prompted with the Care Question or not. The Care Question was “Did you love this story?”

This breaks down into two tests, a “follow test” and a “support test”, with a control and variation scenario for each:

Follow test, control

Follow test, variation

Support test, control

Support test, variation

Finally, if a user clicked no, we provided a prompt to email us feedback.

If a user answered “No” to the Care Question, we asked them to email us feedback.

We were able to determine with 99.90% confidence that prompting a user with a question before asking them to “Support Public Radio” was more successful. We converted 0.184% of users who did not receive the Care Question and 1.913% of users who did, which makes a user who received the Care Question 10 times more likely to click the support link.

“Life After Death”

One week later, after we had seen the preliminary results of our test from “A Brother And Sister In Love”, we ran another test on “Life After Death”. This was not a story associated with Look At This, and there was not an equivalent NPR property to follow, so we decided to hone our test on converting users to the donate page.

We wanted to confirm that users would convert at a higher percentage when presented with a Care Question first, so we kept the same control scenario. Instead of only using one question, we decided to run a multivariate test with four possible different phrasings. The control scenario and the four question variations each received ~20% of the test traffic. The four possible questions were:

• Did you like this story?
• Did you like this story? (It helps us to know)
• Does this kind of reporting matter to you?
• Does this kind of reporting matter to you? (It helps us to know)

For this test, we tested each question against the control scenario – presenting the user with a support button without showing them a question first.

Once again, we determined that presenting users with a Care Question before asking them to support public radio was a more successful path. Each of our four questions outperformed the control scenario at > 95% confidence intervals. Of the four questions, the two asking “Does this type of reporting matter to you?” were the best performers, which perhaps suggests that tailoring the Care Question to the content is the best course of action. Life After Death is a harrowing, intense story about a devastated village in Liberia, so perhaps asking a user if they “liked” a story was offputting in this case.

“A Photo I Love: Thomas Allen Harris”

A week later, we were able to run another test on a very similar story. It was a slide-based story that was also driven by the audio. We decided to rerun our original test, but fix our errors when logging to Google Analytics to create a better testing environment.

We left the same Care Question, “Did you love this story?”, and maintained our Look At This follow links.

Once again, we determined that giving users a question before a prompt to take action is a more successful path to conversion (1.7 times better for the Follow action and 13.5 times for the Support action).

Lessons Learned

We learned a lot in a short amount of time: some things about the stories themselves, a lot about the running of live tests and the math behind it. A few insights:

• With our third test confirming that the Care Question has a positive impact on performance of actions presented at the end of stories, we feel confident implement this behavior by default going forward.

• We also demonstrated that the language used to frame the Care Question matters. So far, aligning the tone of the question with the tone of the story has proven most successful.

• Running the same test twice helped us simply validate that everything was working as planned. We are new to this, so it’s not a bad idea to double check!

• Given the nature of the traffic for our stories (2-4 days of high volume followed by a long tail of decreased traffic), we need to make sure statistical significance is achieved within the first few days, as running a test for a longer period of time doesn’t add much at all.

• Calculating the right sample size for a test is always a concern and particularly difficult when you don’t have a reliable cadance for what traffic to expect (since it varies from story to story), so we found we don’t need to do that at all. Instead, we can simply expose the entire audience for a story to the test we run and make the most of it as soon as possible.

• We made several mistakes while analyzing the data simply because this is not something we do every day. Having multiple people look at the analysis as it was happening, helped us both correct errors and get a better understanding of how to make sense of the numbers.

• Google Analytics automatically samples your default reports if your organization’s overall sessions exceed 500,000. To analyze tests like these you will want to make sure you have a full picture of your audience, so request an unsampled report (available from GA Premium only) so you can ensure your test is valid and reliable.

• Also, with Google Analytics dropping support for custom variables, use distinct events to identify the variations of your test instead.

Hey!

Are you a student?

Do you design? Develop? Love the web?

…or…

Do you make pictures? Want to learn to be a great photo editor?

If so, we’d very much like to hear from you. You’ll spend the summer working on the visuals team here at NPR’s headquarters in Washington, DC. We’re a small group of photographers, videographers, photo editors, developers, designers and reporters in the NPR newsroom who work on visual stuff for npr.org. Our work varies widely, check it out here.

Photo editing

Our photo editing intern will work with our digital news team to edit photos for npr.org. It’ll be awesome. There will also be opportunities to research and pitch original work.

Please…

• Love to write, edit and research
• Be awesome at making pictures

Are you awesome? Apply now!

Design and code

This intern will work as a designer and/or developer on graphics and projects for npr.org. It’ll be awesome.

Please…

• Our work is for the web, so be a web maker!
• We’d especially love to hear from folks who love illustration, news graphics and information design.

Are you awesome? Apply now!

What will I be paid? What are the dates?

The deadline for applications is March 20, 2015.

Check out our careers site for much more info.

Thx!

• Trip for two to Paris
• Tanzanian Safari for two
• Trip to Iceland
• WWDTM Trip to Chicago
• Galapagos trip
• Rome and Florence trip
• Mercedes Benz

Posted To: Press Releases

Washington, D.C. – Four media startups proposed by entrepreneurs over 50 have been selected to receive $12,000 each in encore media entrepreneur funding, J-Lab announced today. The projects are a single-topic magazine on Medium.com, a Connecticut hyperlocal FM/streamed radio station, daily Internet radio newscasts and podcasts for a Pacific Northwest blog network, and an Hispanic crowd-sourced initiative on border-crossing deaths.

The four initiatives were among 82 applications received in J-Lab’s Masters Mediapreneurs initiative to help seed media startups launched by Baby Boomers, aged 50-plus. 

“We could easily have funded several more worthy projects,” said J-Lab director Jan Schaffer. “The ideas were creative, the energy striking, and the applicants’ eagerness was quite pronounced.”

“Many who applied tipped their hats to this opportunity to validate ideas from mature news creators and help them make them happen.”

The winners are: 

Midcentury/Modern, an online magazine “following Boomers into their Third Act,” launched in late December by hyperlocal news entrepreneur Debra Galant, the founder of Baristanet and now director of the NJ News Commons. Instead of creating a stand-alone website, the magazine is publishing on Medium, a social journalism blogging platform that allows people to recommend and share posts Twitter-like. It is one of the first publications receiving independent funding to launch on Medium, which is also offering technical and revenue support. “This online magazine explores how the definition of aging shifts when it happens to the cohort that defined itself by its youthfulness,” Galant said.

The LP-FM New-Media Newsroom, a new FM/web-streamed radio station for New Haven, CT, shepherded by New Haven Independent founder Paul Bass in partnership with La Voz Hispana, the local Spanish-language weekly. Daily four-hour news programs, to start, will be in English and Spanish and feature local African-American hosts. “We're excited about launching an FM/web-streamed community radio station in the fall,” Bass said. “We envision this as one model for not-for-profit, public-interest local news sites like ours to expand on the journalism we do and broaden our racial and ethnic makeup and outreach.”

SoKing Internet Radio, daily newcasts to feature content from South King Media company’s six community blogs covering South King County near Seattle. Scott Schaefer, founder of the B-Town Blog and South King Media is leading the project. “This will allow us to start up a truly innovative new program – daily hyperlocal newscasts that will live not only on our 24/7 streaming radio station, but also as podcasts posted to South King Media’s six local blogs and Facebook pages,” Schaefer said.

EncuentrosMortales.org, a Spanish-language website and database to collect public records and media reports of undocumented people killed during interactions with law enforcement officers along the southern border of the U.S. It is a project of D. Brian Burghart, who created an English version, FatalEncounters.org, and is editor and publisher of the Reno News & Review. “I’m very excited to be able to move forward with EncuentrosMortales.org.  Law-enforcement-involved homicides along the U.S. border is an important and underreported issue, and I hope we can bring together technology, languages and volunteers to get a much better idea of our government’s activities,” he said.

The Masters Mediapreneurs progam is funded with grants from the Ethics and Excellence in Journalism and the Nicholas B. Ottaway Foundations.

Participating in the judging the applications were Ju-Don Roberts, Director of the Center for Cooperative Media, Montclair State University; Tiffany Shackelford, Executive Director, Association for Alternative News Weeklies; Jody Brannon, Digital Media Strategist and former National Director News 21, and Jan Schaffer, Executive Director, J-Lab.

J-Lab, founded in 2002, is a journalism catalyst. It funds new approaches to news and information, researches what works and shares practical insights with traditional and entrepreneurial news organizations. Jan Schaffer is also Entrepreneur in Residence at American University.

Do you use our dailygraphics rig to create and deploy small charts? We’ve introduced a new feature: The latest version of copytext.py (0.1.8) allows users to inject serialized JSON from a Google Spreadsheet onto their page with one line of template code.

Benefits:

• Store your text and your data in the same Google Spreadsheet, making editing a little simpler.
• The data is baked right into your page, so there’s one fewer file to load.

(Thanks to Christopher Groskopf and Danny DeBelius for making this work.)

If you’re already using dailygraphics, pull the latest code from GitHub (we’ve updated libraries and made other bugfixes in recent weeks), and update requirements:

pip install -Ur requirements.txt

You can see this at work in a graphic published today on NPR.org.

Here’s How It Works

The following examples assume that you are using our dailygraphics rig. Both examples point to this Google Spreadsheet.

The spreadsheet has three tabs:

• labels: Text information (headline, credits, etc.)
• data_bar: The data for the bar chart example below
• data_line: The data for the line chart example below

Note: Copytext works best when all values (even numeric ones) are cast as text/strings in the Google Spreadsheet, rather than numbers or dates. You can convert them to their proper types later in JavaScript.

Bar Chart (Source code on GitHub)

In child_template.html, add a <script></script> tag above all the other JavaScript embeds at the bottom of the page, and then declare the variable for your data.

<script type="text/javascript">
    var GRAPHIC_DATA = {{ COPY.data_bar.json() }};
</script>

• GRAPHIC_DATA is the variable name you’ll use to reference this data
• COPY refers to the overall spreadsheet
• data_bar is the name of the specific sheet within the spreadsheet (in this case, the spreadsheet has three sheets)

The result looks like this, with the keys corresponding to the column headers in the table:

<script type="text/javascript">
    var GRAPHIC_DATA = [{"label": "Alabama", "amt": "2"}, {"label": "Alaska", "amt": "4"}, {"label": "Arizona", "amt": "6"}, {"label": "Arkansas", "amt": "8"}, {"label": "California", "amt": "10"}, {"label": "Colorado", "amt": "12"}, {"label": "Connecticut", "amt": "14"}];
</script>

In js/graphic.js, don’t bother with declaring or importing GRAPHIC_DATA — just go straight to whatever additional processing you need to do (like, in this case, explicitly casting the numeric values as numbers).

GRAPHIC_DATA.forEach(function(d) {
    d['amt'] = +d['amt'];
});

Line Chart (Source code on GitHub)

In child_template.html, add a <script></script> tag above all the other JavaScript embeds at the bottom of the page, and then declare the variable for your data.

<script type="text/javascript">
    var GRAPHIC_DATA = {{ COPY.data_line.json() }};
</script>

• GRAPHIC_DATA is the variable name you’ll use to reference this data
• COPY refers to the overall spreadsheet
• data_line is the name of the specific sheet within the spreadsheet (in this case, the spreadsheet has three sheets)

The result looks like this, with the keys corresponding to the column headers in the table:

<script type="text/javascript">
    var GRAPHIC_DATA = [{"date": "1/1/1989", "One": "1.84", "Two": "3.86", "Three": "5.80", "Four": "2.76"}, {"date": "4/1/1989", "One": "1.85", "Two": "3.89", "Three": "5.83", "Four": "2.78"}, {"date": "7/1/1989", "One": "1.87", "Two": "3.93", "Three": "5.89", "Four": "2.81"}, {"date": "10/1/1989", "One": "1.88", "Two": "3.95", "Three": "5.92", "Four": "2.82"} ... [and so on] ...;
</script>

In js/graphic.js, don’t bother with declaring or importing GRAPHIC_DATA — just go straight to whatever additional processing you need to do (like, in this case, explicitly casting the dates as dates).

GRAPHIC_DATA.forEach(function(d) {
    d['date'] = d3.time.format('%m/%d/%Y').parse(d['date']);
});

Related Posts

• Creating And Deploying Small-Scale Projects
• Responsive Charts With D3 And Pym.js
• Making Data Tables Responsive
• Introducing copytext.py: your words are data too
• Introducing Pym.js

For election night 2014, we wanted to do something different.

We guessed that the dedicated wonks — the ones who want to drill down into detailed data and maps — would probably go to sources like the New York Times or Washington Post. Rather than reproduce that work, what could NPR do that would be unique, and would serve a broader audience?

To start, we had our organization’s thoughtful reporting and on-air coverage — a live event we could build something around. We had the results “big boards” we make every election year for the hosts in the studio (and shared publicly in 2012 — a surprise success). We had a devoted audience.

So we decided to throw a party — and put radio on TV.

We built an app that people could pull up on their TVs or laptops or mobile phones and leave on in the background during their election parties. We imagined users muting cable news and listening to us instead — or even replacing cable news entirely for some users. We built in Chromecast support and made reaching out to cord-cutters part of our marketing pitch.

Did it work? Here’s what we learned.

Note: The usage figures cited below refer to a one-day slice of data: Nov. 4, 2014 (EST). The practice of measuring web usage is an inexact science — time on site is particularly problematic — so all of these figures are best read as estimates and used for relative comparison, not absolutes.

Traffic / Usage

(Chrome usage likely also includes Chromecast. Safari (in-app) figures reflect users opening links within iOS apps, such as Twitter and Facebook.)

Browser usage of our app generally tracked with that of the overall NPR.org site. Exceptions: The share of Chrome users was a few percentage points higher for our app; the share of Internet Explorer users, a few percentage points lower.

Non-Interactivity

This project involved a lot of a little experiments aimed at answering one larger question: Will users appreciate a more passive, less-interactive election night experience?

As it turns out, this is a remarkably difficult thing to measure. We can’t know if our users put their laptop down on the coffee table, if they were with friends when they used it or if they plugged their laptop into their TV. Instead, we have to make inferences based on session duration and our relatively meager event tracking.

Overall, the feedback we received was quite positive. We prompted people to email us, and most of the folks who did so said they were happy with the experience.

Slide Controls

Although we optimized for a passive user experience, we needed to include some controls. From the very beginning our stakeholders asked for more control over the experience. We made an effort to balance this against our belief that we were building more for a distracted audience.

For passive users, each slide included a countdown spinner to signal that the display would change and to indicate how much time remained until the app would auto-advance to the next slide.

For more active users, we included “previous” and “next” buttons to allow users to skip or return to slides. 27 percent of users clicked the “next” button at least once to skip, while 18 percent used the “previous” button. 11 percent figured out that they could skip slides using their keyboard arrow keys. (We didn’t include any clue to this feature in the UI.) About a third of those who emailed us said they would have liked even more control, such as a pause button.

Audio Controls

The live radio broadcast would auto-play when users entered the app. 8 percent of users clicked the mute button. (Not including users who may have used the audio controls on their devices.)

Personalization

We guessed that, in addition to national election results, users might also want to see results for their state.

Our original plan was to ask our users to choose their state when they arrived. But as we learned from user testing and fine-tuned the welcome process, we killed the intermediary “pick your state” screen. Instead the site would guess the user’s location, and users could change their state via the controls menu.

6 percent of users interacted with the state dropdown. The list of top states users switched to hints at interest in certain contentious races (Senate seats in Kentucky and Colorado, for example), regardless of where the user was actually located.

• Kentucky
• Colorado
• California
• Florida
• Arkansas

We heard feedback that some users who did use the dropdown were unsure of its purpose. If we had more time, we might have put more time into this feature. We hoped that if our attempt at presenting location-specific results worked seamlessly for most users, it would be okay.

The Chromecast Hypothesis

Our working theory was that Chromecast users would be the most passive in their interaction with the app — likely throwing it up on the TV and just letting it run — and therefore they would spend more time with it. And that theory held true: Chromecast users spent an average of 19 minutes and 53 seconds on the site (compared to the overall average of 7 minutes and 1 second).

That said, the Chromecast audience was pretty small: In only 0.7 percent of visits did a user initiate a Chromecast session by clicking on one of our “Cast This” buttons. (This does not include users who may have cast the page using the Chrome browser extension.) But we heard from many Chromecast users who seemed very excited that we built something for them: 15 percent of the feedback emails we received and 13 percent of tweets talking about the app mentioned Chromecast.

(We originally intended to also support Roku and AirPlay “casting,” but the native Chromecast experience proved to be far superior to the “mirrored” offered by other devices. We hope to continue experimenting in this arena.)

On a related note, one surprise: 3 percent of users clicked the fullscreen button — more than double our Chromecast users. And these users stayed on the site even longer, an average of 31 minutes, 38 seconds.

Conclusion

This project gave us some useful insights into how users interact (or not) with an app designed to be experienced passively.

We also learned a lot about user analytics, from what behavior to track to how to query for results. Our insights were limited somewhat by the tools we had and our ability to understand them — Google Analytics can be pretty opaque.

On all these counts, we’ll continue to try new things and learn with future projects. We look forward to refining this experiment as we plan for the 2016 elections.

Editor’s Note: Core Publisher is a content management system that staff at many NPR member stations use to maintain their websites. This post is written for that audience, but may be useful for users of other CMSes.

Over time, many member stations have created maps, graphics and other projects for their websites that were sized to fit Core Publisher’s fixed-width layout. But with the responsive mobile-only sites, and Core Publisher going to a fully responsive design, these elements either don’t work or won’t resize correctly to the screen.

Now you can use Pym.js to iframe responsively-built projects within Core Publisher stories.

Achievement unlocked: I think I just got pym.js working on my CorePub mobile site https://t.co/AiP59h1UME

— Jim Hill (@ejimbo_com) December 2, 2014

(Note: NPR Digital Services, the team behind Core Publisher, doesn’t maintain or support Pym.js and can’t help you use it. But they didn’t raise any concerns about this workaround.)

I Was Ready Yesterday, What Do I DO?

I like that enthusiasm. First of all, let’s get a few assumptions out of the way: We’re assuming you are familiar with working in Core Publisher, know the post building process, comfortable with working in the source code view in the WYSIWYG with HTML, and that you have a separate web space to host all of your files (KUNC, like the NPR Visuals team, uses Amazon’s S3 service).

1) Download Pym.js.. Follow the instructions to integrate it into your project. (In Pym.js terms: Your project is the “child” page, while the Core Publisher story page it will live on is the “parent” page.)

2) Publish your project to the service of your choice. Note the URL path: You’ll need it later.

3) Build a post as normal in Core Publisher and then switch to the source code view and locate in the code where you want to place your iframe.

4) Core Publisher often strips out or ignores tags and scripts that it doesn’t recognize when it publishes. We’re going to get around that by using tags that CP does recognize. We’ll use Pym.js’s “auto-initialize” method, rather than inline JavaScript, to embed our project on the page. But, contrary to the example code in the docs, don’t use <div> tags to indicate where the iframe will go — use <p> tags instead. You’ll also need the URL path to your project from step 2: That will be your data target. The tag will look like this: <p data-pym-src="http://example.com/project/"></p>. Your target code for the iframe should look something like this:

<p>Bacon ipsum dolor amet cupim cow andouille tenderloin biltong pork belly corned beef meatball swine pastrami alcatra.</p>
<p data-pym-src="http://example.com/project/">&nbsp;</p>
<p>Cupim beef ribs ribeye swine tail strip steak drumstick venison bacon salami pig chicken.</p>

Beware: Core Publisher often will ignore paragraph tags <p> that are empty when it publishes. To avoid this, insert a non-breaking space   between the opening and closing <p> tags for your pym target. Sometimes the CP WYSIWYG hobgoblins will insert this for you as well.

5) Next, point to the Pym.js script file. <script> tags are sometimes hit-or-miss in Core Publisher, so you should save your work right now.

(Note: If you’re embedding multiple Pym.js iframes on a page, you only need to include this script tag once, after the last embed.)

6) Did you save?

7) Good, let’s place that script tag now. It should follow the last iframe target in your post and should only appear once. You’ll need your URL path to pym from step 2. The full tag will look like this: <script type="text/javascript" src="http://example.com/project/js/pym.js"></script>.

8) Your complete code should now look like this:

<p>Bacon ipsum dolor amet cupim cow andouille tenderloin biltong pork belly corned beef meatball swine pastrami alcatra.</p>
<p data-pym-src="http://example.com/project/">&nbsp;</p><script type="text/javascript" src="http://example.com/project/js/pym.js"></script>
<p>Cupim beef ribs ribeye swine tail strip steak drumstick venison bacon salami pig chicken.</p>

Most of the time the script tag should be fine since it is a simple one — only the tag and URL, and no other arguments. Sometimes Core Publisher will still strip it out. This should be the last thing you place in your post before you save to preview or publish.

If you go in later and edit the post, double-check that the script wasn’t stripped out.

A good sign that the script wasn’t dropped? The following text might appear in the normal WYSIWYG text view: {cke_protected_1}. Don’t delete it: That’s script code.

Take a look at your post and revel in how cool that Pym.js-inserted element is. Or take a look at this example or this one.

What Gives? Your Example Isn’t On The Responsive Theme.

We’ll be transitioning to the responsive design in a few months. In the meantime, KUNC has a lot of legacy iframes that we’ll be going back to and embedding with Pym.js. And Pym.js works like a champ on the already-responsive mobile site, so these projects will work better for the quickly-growing mobile audience. Always think mobile.

So, Does It Work On The Responsive Theme?

It sure does! Anna Rader at Wyoming Public Media was kind enough to let me try a Pym.js test post on their newly-transitioned responsive site. Everything worked like a charm and there was much excitement.

Will The Pym Code In A Post Carry Over The API For Station-To-Station Sharing?

I haven’t tested this yet. If you’d like to be a test subject, let me know and we can give it a try. Looking at the raw NPRML in the API for a post with the pym code it in, it all seems to be there.

Have any questions? Find me on Twitter @ejimbo_com and ask away.

The NPR year-end 2013 Book Concierge was a big hit. Instead of writing a bunch of lists, the books team solicited over 200 short reviews by critics and staff and put them into a single, beautiful website designed to make discovering great books fun. Readers loved it. For the 2014 Book Concierge, our goal was to build on last year’s success and resist the urge to rewrite the code or wildly redesign.

This is a catalog of small improvements, why we made them, and the difference they made. We’re using analytics for the first five days following the site’s launch. Overall, pageviews are slightly down from last year (337,000 in the first five days in 2014 versus 370,000 in 2013), but engagement appears to have increased fairly significantly.

Tag Styling

In the 2013 concierge the list of tags blends together, making them difficult to scan. To improve the tags’ legibility and click-ability, we tried different color combinations and styles with varying success. We tried alternating between 2 tag colors, as well as varying the tag length, but neither were satisfying.

Our final solution was to apply a color gradient over the list of tags. This transformed the tags into individually identifiable buttons that still feel like a cohesive unit. This year, there was an average of 2.7 tag selections per visit versus 2.3 in 2013, a 17% increase. In 5 days, about 86,000 people clicked the most popular tag (NPR Staff Picks), up from about 75,000 in 2013.

2013

2014

Modal Improvements

We changed the modal design to help encourage users to read more book reviews. We replaced the modal’s ‘previous’ and ‘next’ buttons — which were tucked away at the bottom of the review — with side paddles. This allows viewers to easily click through the reviews without having to hunt for the buttons at the bottom of each review. We also changed the modal proportions so that it fits into a wider range of screen sizes without forcing the user to scroll. By putting a max-width on the modal and limiting the book cover image size, we eliminated a lot of dead white space which improves the user’s reading experience. We believe these changes worked. This year, users viewed an average of 3.7 reviews per visit, up 54% from 2013.

2013

2014

Filter Button Location

In the 2013 concierge the filter button is positioned in the header above the ad on mobile devices, leaving a gap between the button and the book grid. In the 2014 version, we moved the filter button under the ad below the header, grouping the button with the content that it affects. Although the tag usage per viewer on mobile is similar for both years, we thought that this change created a more organized layout.

2013

2014

Social Buttons

We wanted to help users share their favorite books and reviews, so we added share buttons to the book modal. In the first 5 days, 6,110 reviews were shared through email, followed by facebook (2,866), pinterest (2,091) and twitter (559).

Links to Previous Years

It would have been cool to combine 2013 and 2014 into one big concierge, but we didn’t have time for that. We still wanted to reference last year’s concierge, as well as book lists from previous years, so we added these links to the header. Additionally, we added a link below the tags list to catch people who skipped past the header. On launch day, the 2013 concierge got 20,330 pageviews driven by the 2014 page.

2014

Lighten page load, improve performance

We’ve been able to realize significant performance gains in recent projects by using custom builds of our libraries and assets. We shaved over 300kb off the initial page load by using a custom icon font generated with Fontello rather than including all of Font Awesome. To further lighten the load, we dropped a few unnecessary libraries and consolidated all our scripts into a single file loaded at the bottom of the source.

In 2013 each book had two images, a thumbnail for the homepage and a bigger version for the modal. This year, we cut the thumbnail and aggressively optimized the full-size cover images. The page weight is almost identical, but instead of loading a thumbnail for the cover and a full sized cover when looking at a review, only a single image is loaded. This makes load time feel faster on the homepage, and helps load the reviews faster.

We also disabled CSS transitions at small viewport sizes to improve mobile performance and dropped all CPU intensive 3D CSS transitions.

Responding to users after launch

Finally, some librarians suggested to NPR Books that next year we should include a link to Worldcat, a site that will help you find a book at your local library.

2014

We thought this was a lovely idea and didn’t see why it needed to wait. So we used the Online Computer Library Center identifier API to get the magic book identifier used by Worldcat and added a “find at your library” link the day after launch. This quickly became the second most clicked exterior link after the “amazon” button.

It’s always awesome to make librarians happy.