Blog

Inside the Minds of the Machine

APIs, Inside IEG

PBS Logins on Thirteen.org = THIRTEEN Passport

The smart people at the Public Broadcasting Service have built a system to provide video-on-demand for members of PBS stations on PBS.org. We call this system ‘Passport‘ — since it’s a benefit for members of individual PBS stations, we refer to it at WNET/Thirteen as ‘THIRTEEN Passport’, while another station such as Oregon Public Broadcasting calls it ‘OPB Passport’. This system lets a user login via Google, Facebook, or ‘Sign in with email’. Then some clever backend systems check against the member lists of PBS stations, and if he or she is a member, allow that member to access additional streaming video content that isn’t available to non-members.

At THIRTEEN, we’ve put a lot of effort into making a great user experience on our station website, THIRTEEN.ORG, so we worked as a beta partner with PBS while they were developing this system so that we could integrate it into our WordPress installation and our custom Thirteen Explore app. It took a lot of careful thought and hard work juggling oAuth, APIs from PBS and vendors, not to mention careful design work and adapting quickly to support feedback from our members. We’ve been very pleased with the results, which have led to thousands of new members joining WNET/Thirteen since we launched n Dececember 15, 2015.

And in an effort to help the PBS system overall, we’ve put most of the system into a WordPress plugin that we’re sharing with other PBS stations for free.

What is Passport?

As you can imagine, a lot of thought and discussion also went into the policy decisions behind Passport that aren’t really suited to a tech blog post. But for the purposes of how the system works, the reader should understand that when a PBS station broadcasts a program, there are previously negotiated rights for broadcast and streaming that usually mean that the video is often only available to stream to the general public for a limited period of time after it was aired. For example, about 2 weeks after an episode of Downton Abbey episode airs, we can no longer make it available for free streaming. Passport is a benefit that gives members of PBS stations who support the station for a minimum of $60 access to stream programs for an extended additional period.

That leads us to the core challenge we’re faced — providing a means to

  1. identify the current visitor to the website or app, then
  2. determine if that visitor is a current member of a PBS station, and
  3. if not, give the visitor a way to become a member.
    Once those challenges are resolved,
  4. serving the member-only content
    is relatively straightforward.

Let’s go through how it works.

Warning: this is pretty detailed and will get a little technical.

Identifying the current visitor

The first step of any permissions system (online or otherwise) is to find out who the visitor is by authenticating the identity who the visitor claims to be. oAuth has become the de facto standard for authenticating the identity of website visitors; with oAuth, we can delegate this authentication step to websites such as Google or Facebook and piggyback on how people use those very popular systems to maintain their online identities. This is the same approach that PBS has taken for the ‘PBS Account‘ system.

pbs_signinA somewhat simplified description would go like this: On PBS.org, the visitor is shown a link to (for example) ‘Sign in with Facebook’. This special link leads to a form on Facebook.com where the visitor is prompted to login to Facebook (if they aren’t already). Once the visitor has logged into Facebook.com, the visitor is redirected back to PBS.org along with a one-time-use code. PBS.org then sends that code back to Facebook to get basic information about the person. This means that when visitors log in with Google or Facebook, PBS doesn’t store (or even have access to) visitor passwords, and any changes to their Google of Facebook accounts are automatically reflected in their experience on PBS.

There is a third option labeled ‘Sign in with PBS Account’ (or ‘Sign in with email’) that visitors can use if they wish to create a new username and password just for use with PBS; in that case PBS does store the password, of course.

This PBS Account system is how people sign into PBS.org and related iOS and Android apps. Once the visitor initially signs in with a login provider (Google, Facebook, or ‘Sign in with email’) they are assigned a unique identifier (UID) within the PBS Account system, and that UID is reused any time he or she logs back in with that login provider. If I sign in with Google on PBS.org using Internet Explorer on my work computer, and then sign in with Google in the PBS app on my iPhone, I’ll have that same PBS Account UID in both places, or on any other browser, computer, or device.

At WNET/Thirteen, we worked closely with PBS to make it possible for us (and for other PBS stations) to integrate the PBS Account system into our own website and apps. The details are complex, but the result is that since the visitor is logging in via the PBS Account system that visitor will have the same authenticated identity — the PBS Account UID — whether logged into Thirteen.org, PBS’s apps or websites, our own Thirteen Explore apps, or any other platform that uses the PBS Account system.

Here’s what our signin page on Thirteen.org looks like:
thirteen_signin

Is the visitor a member of WNET/Thirteen?

Just because I know a person’s identity doesn’t necessarily mean I know if that person is authorized to have access to something. PBS has created a database they call the ‘Membership Vault’ where individual PBS stations can securely store lists of their members. Each station has their own list of members (one station can’t see the list of another station), and each member record can be associated with a PBS Account UID. Through a process called ‘activation’, each individual member is provided a unique activation code by the station; the member enters the activation code on a form; and then the user is prompted to log into the PBS Account system, which connects the resulting PBS Account UID to the member’s Membership Vault record.

It’s worth noting that a UID can’t be associated with more than one member record per station, but can be associated with member records in multiple stations. For instance, my Google login can be associated with only one WNET/Thirteen member record, but my same Google login could also be associated both with a record for a member of WTTW/Chicago and a record for a member of Oregon Public Television.

On PBS.org, PBS can see if a logged in visitor has a corresponding Membership Vault account by looking for records that have that PBS Account UID. PBS has also provided stations with the ‘Membership Vault API’ that lets us create, update, and look up membership records. In our system on Thirteen.org and in our apps, we use this API to see if there’s a member record with the visitor’s UID (though we can only look for that UID in the records of WNET/Thirteen members). In any case, once the corresponding member record is found, we can base what we show to the member on the info in that member record.

But what if we can’t find the visitor’s member info?

If the authenticated visitor can’t be found in the Membership Vault, there are two possibilities. Either the visitor isn’t a member, or the visitor is a member who hasn’t gone through the ‘activation’ process of entering a unique activation code into a form and creating the connection between PBS Account UID and Membership Vault record.

We leave it to the visitor to decide whether to become a member or to get the activation code that they haven’t yet used.

If the visitor chooses to become a member, we direct them to an ‘instant viewer gratification’ donation form. Once the donation has been successfully submitted, the ‘thank you’ receipt page has an embedded script that uses the Membership Vault API to instantly create a member record, and provides a link for the member to complete the activation process and gain access to content right away.

The other case is when a visitor is already a member but hasn’t been activated. The member may never have recieved an activation code; like most PBS stations, WNET/Thirteen doesn’t have email addresses on file for a large proportion of our eligible members, as they’ve been giving via postal mail or call-in pledge drives for years. And although the activation code and instructions were sent via postal mail or email, it could easily have been discarded as junk.

Our solution to this problem is our “I’m already a member” form where we require the visitor to enter both their postal address and email address, and optionally the member ID that we print on the ‘MemberCard’ we distribute to our visitors. We check what the visitor enters against the data we have on file, and if we find a match we email the activation code and instructions to the email address provided. If we don’t find a match, or if the visitor is a lapsed member, we email them that information and provide a link to our ‘instant viewer gratification’ donation form.

Showing station member-only video

Now that we have our visitor’s member information, we can show the visitor to our website or app content based on that information. The most obvious content to show is member-exclusive video!

PBS runs all streaming video through a custom platform called COVE, and provides a ‘Partner player’ that allows websites to embed specific videos. Each video object within COVE includes metadata as to whether the video is available to the general public or is restricted to PBS station members (or even members of a specific PBS station). Additionally, PBS provides a COVE API that allows stations to retrieve all of the metadata about a video, or all of the videos associated with a particular series.

Thirteen.org displays PBS video on hundreds of ‘program pages’ on our site. For some years we’ve had a system that uses the COVE API to automatically generate and update the Partner Player video embeds for all of the programs we show on our website. We promote those pages to our members and viewers, and integrate those pages with community-relevant content.

We adjusted our program page to generate/update some logic that reads from the COVE API as to whether a video is available to the public, all PBS members, or just WNET members; this logic then adds a data element to the HTML tag that we wrap around the Partner Player which indicates the availability. That extra data element (just a string in the HTML like ‘data-window=”all_members”‘) is read by the Javascript in our plugin that we use to see the visitor’s login and member status. Additionally, PBS has updated the Partner Player so that if you append the PBS Account UID of the visitor to the embed code, if that visitor is allowed to authorized to watch that video, it will play. Our plugin’s Javascript appends that UID if the visitor is logged in.

The result: if a visitor to Thirteen.org is authenticated and is an authorized current member, that member sees and can watch exclusive video content. If the visitor is not logged in, hasn’t ‘activated’, or is logged in and activated but his or her membership has expired, instead of showing the Partner Player, we show a screenshot from the video behind an overlay with links to login, activate, or become a member. That will look something like this:

masterpiece_passport

Following any of those links and successfully completing whichever process returns the authenticated, authorized member directly to the Partner Player and a playable video.

On PBS.org, there is a very similar experience — here’s a screenshot:

pbs_org_passport

We think the experience on Thirteen.org is a little nicer.

What are the results?

The system launched on both PBS.org and Thirteen.org on December 15, 2015. As of mid-March, we’ve had over 17,000 members “activate” — authenticate via PBS Account and enter an activation code on either PBS.org or on Thirteen.org.

Of those activated members, about 6,500 were new members who joined via “instant viewer gratification” forms on either PBS.org, Thirteen.org, or within our iOS Thirteen Explore app. We’ve also had over just under 1000 former members rejoin, and about 300 recently lapsed members renew. Of the members coming in through “instant viewer gratification”, slightly over 50% came in through PBS.org, slightly under 40% through Thirteen.org, and about 10% through Thirteen Explore.

We’re very pleased to have gotten the over 4,400 members who came in via PBS.org. All it took to get those members was to ‘enable’ our participation in Passport on PBS.org, and we recommend that every PBS station do so ASAP.

As we see it, if we had not integrated THIRTEEN Passport into Thirteen.org and our Thirteen Explore app, it is likely we’d be leaving the approximately 3,800 members who came in via those platforms ‘on the table’.

And we are continuing to get new, rejoining, and renewing members through THIRTEEN Passport at a consistent pace.

What ELSE will we do with this?

For the moment, the ‘content’ we show visitors based on their login and membership status is very basic (other than video). In the upper right corner of our site, if the visitor is logged in we show their first name, their social media ‘avatar’ from Facebook or Google (if it exists), and an icon representing their THIRTEEN Passport status — a current member sees the ‘compass rose’ icon that the PBS system identifies with Passport, while an expired member or a logged in visitor who hasn’t activated sees an exclamation point. Clicking on the first name or the icon sends a visitor to their user status page, and that includes either a confirmation of their THIRTEEN Passport status or links to renew or activate.

What will our next steps be? We’ll probably build ways for members to manage their membership information from the website. We’re also exploring ways for members to maintain watch lists, see their viewing history, and indicate preferences for what content they’d like to see bubbled up to the top of their website or app experience; these preferences etc would be tied to that PBS Account UID and therefore carry over onto any platform or app the member logs into.

Much more is possible, however. We have thousands of unique visitors to Thirteen.org who are logged in, activated members and who repeatedly visit the site. Any online community would be VERY pleased to start with that many verified members — people who we know believe enough in our mission to become members of THIRTEEN, are geographically concentrated in a specific community, and demonstrably come online to visit our website as logged-in visitors and watch our primary product.

Blue-skying, some theoretically possible ways to build on this could include

  • member polls for requests of specific classic PBS video to make available,
  • member-hosted events like ‘watch parties’,
  • community feedback on programming,
  • member-generated content,
  • etc. etc.

The necessary building blocks of technology and userbase are basically in place. That means that whether or not we (or other PBS stations) pursue any options like these will be driven first and foremost by whether policymakers determine that they fulfill the mission of the organization — as it should be!

Can other PBS stations do this?

THIRTEEN.ORG is built on WordPress, and we built as much as we could of this PBS Account integration into a portable, stand-alone WordPress plugin as we reasonably could.

Our plugin is available for download from GitHub at https://github.com/tamw-wnet/pbs-passport-authenticate, and we are sharing with any PBS station that would like to use it.

The plugin handles

  • Providing a login/logout system for PBS Account authentication with Google, Facebook, or ‘login with email’;
  • Retrieving the member record from a station’s Membership Vault account and making it available in a cookie, to some basic Javascript functions, and on the user info page;
  • An ‘activation’ form where a station member can enter his or her activation code, activate, and return to the page the visitor started on.

Our “I’m already a member” form is custom-coded to work with our specific membership database setup; and our “instant viewer gratification” donation form is also customized to our donation form software provider, Luminate Online. However, PBS provides a simplified ‘member lookup’ feature on PBS.org, and there are multiple software providers that work with PBS stations and have developed similar “instant viewer gratification” solutions. Custom “I’m already a member” systems or “instant viewer gratification” donation forms would also probably be within the capacities of most software developers comfortable with building something as complex as a custom WordPress plugin.

Our system for auto-generating program pages for all of the series that we air is part of our overall theme and site setup, and is really too custom to share. However, the javascript that looks for video embeds that have that ‘data-window’ element in their HTML is included in our plugin, so a station should be able to integrate the PBS Account logins from our plugin with their own means for getting COVE video on their site pretty easily.

WNET’s IEG group is also available to contract with stations for website design, visual and technical customizations — which could include such features as automated COVE video integration, or custom “I’m already a member” forms or “instant viewer gratification” forms similar to what we’ve done on Thirteen.org. Review our services, and contact us if interested!


IEG and WNET are not responsible for your or any third party’s use of code from this tutorial. All the information on this website is published in good faith “as is” and for general information purposes only; WNET and IEG make no representation or warranty regarding reliability, accuracy, or completeness of the content on this website, and any use you make of this code is strictly at your own risk.