Migrating to Google+ Sign-in in 5 minutes

Are you looking to understand the available strategies for migrating your existing Google login solution to Google+ Sign-in? Well… You’ve certainly come to the right place

If you're using OpenID1, OpenID2, OAuth1 or OAuth2Login then we have a detailed migration guide: https://developers.google.com/+/api/auth-migration

I strongly recommend reading it. Or at least skimming it since the social login market is bigger and more complicated than it seems. The following is merely a high-level restatement of the migration guide for people who aren't really sure which of the aforementioned technologies they're using.

If your existing system captures the user's email address using a Google identity solution then you can just:

• migrate to Google+ sign-in
• ask for the email OAuth scope
• fetch the user's email address using one of our recommended approaches
• look up the user in your database by email
• associate them with the existing record that matches that email address since Google guarantees that the email addresses are valid

If your existing system doesn't capture the user's email address then life gets interesting.

If you're sure you're using OAuth1+OpenID2 then you can follow the instructions here: https://developers.google.com/+/api/auth-migration#oid2 which tell you how to fetch your old identifier and find out the equivalent identifier with Google+ Sign. Once that's done you can just associate the new identifier with the existing record and the user can sign-in in future with Google+ Sign-in.

If you're using something else then you can ask the user to sign-in twice: firstly with your existing Google identity solution then with Google+ Sign-in. Now that you have both identities you can associate them in your database. Once a critical mass of your users have gone through this process then you can stop using the legacy identity solution. If you have to use this option then I would also recommend reading Michael Mahemoff's experience report from Player.fm's migration: http://softwareas.com/migrating-user-accounts-from-google-openid-to-google-oauth-to-google-plus since I got the idea from him.

Beyond the NASCAR

People in the identity world worry a lot about the NASCAR problem. 

They worry that showing a large set of buttons will hurt conversion rates (because of the paradox of choice) and confuse users who don't remember which IDP (identity provider) they used on a particular site+device combination. 

I don't think that's a big problem nowadays. 

That's because we're down to a fairly small set of viable identity providers (henceforth known as IDPs). Most of the others are either dead(MyOpenId), new (Amazon Login) or only useful in specific niches (GitHub, Instagram, Tumblr, LinkedIn etc).

If we look at Stack Overflow's data we see that 5 IDPs are used by 98.6% of visitors but everybody has to deal with the cognitive load of choosing between the 12 buttons and 1 form field. 

Reducing the set of buttons to 3 would still give users a choice whilst reducing cognitive load. By cutting down to just these 3 IDPs they'd have covered the vast majority (in Stack Overflow's case 92.02%) of potential users of their site and greatly simplified the experience. 

However if you prioritise providing access for 100% of your users over providing the best possible experience for the majority then you have several alternative strategies available to you:

• create your own username/password system (but then you have the responsibility of building a first-class security system)
• use AccountChooser
• build your own equivalent of AccountChooser or something equally clever
• use Mozilla Persona (although it has various issues that I'll probably write about in the future)

If your goal is optimising the percentage of users who sign-in and making sure those people get the best possible experience then here's what I suggest:

• Use Google+ and Facebook buttons (there are also going to be scenarios where Weibo/Renren/VKontakte are appropriate additions). 
• Then use checkSessionState() and FB.getLoginStatus() to find out if the user is already signed in to Google or Facebook. The mobile SDKs have equivalent APIs.
• Then suggest whichever account the user is already using by putting that button first and/or making it bigger. 

We've even published a guide to handling the scenario where the user is signed-in to both IDPs and you can automatically bypass the sign-in screen. 

However there's still the situation where a user prefers different IDPs on different machines: for instance if they work in a company that blocks Facebook at the firewall or they prefer Google+ on Android but Facebook on iOS. For those users a naive NASCAR implementation leaves them with one account on your service per IDP. 

The easiest solution to is to ask for the user's email address and use that to correlate all the accounts they use to login to your service. That way the user never has to worry about creating duplicate accounts. Of course this does restrict you to IDPs who can offer a verified email address. 

The only IDP this excludes is Twitter. If you are using Twitter as an IDP then you'll have to either capture (and verify) the user's email address in a post-registration step. 

Sometimes you have to do things the hard way. Usually it's because you have large numbers of accounts with unverified email addresses (for instance if you used a standard OpenID IDP or used Twitter without capturing and verifying email addresses) or you're migrating users from one IDP to another. 

In that case you have to provide a 'connect flow.' This is where the user signs-in to your service with one IDP and you ask them to 'connect' with additional IDPs. Afterwards you know that the same person owns that set of accounts even if they have different email addresses associated with them. 

The heuristics above mean that the NASCAR anti-pattern doesn't have to harm conversion rates or UX.

If you'd like to learn more about this stuff I'll be attending Over The Air 2013 where I'll be walking people through examples of these heuristics in production and talking about the multi-device multi-platform post-NASCAR future of identity. Join me. 

Why do we bother with APIs?

Sometimes people wonder why we bother building APIs since it seems they can end up being used in ways that compete with our own products.

There are idealistic reasons for building APIs, as outlined by Jonathan Rosenberg, but there are also commercial benefits even if you don't share that philosophy. The main one is that APIs reduce the friction involved in making your services more valuable. They make it easier for other people to add data to your services. 

They also attract more users to your services by effectively advertising them on other people's sites. As well as increasing your visibility APIs also ensure that users are more likely to try your services since the risk of lock-in is reduced. If you have at least a CRUD API potential users know that there will be a  mechanism for extracting their data if something better comes along or if your services change in ways they don't like.

The other benefit of APIs is that they lower the cost of experimentation and increase the set of potential experimenters. These experiments can serve your users in two ways. Firstly they can handle niche use cases without cluttering the user interface of the application. Secondly some of these niche use cases may turn out, after a period of refinement, to be useful for mainstream users or for attracting completely new sets of users.

Another thing we've learned the hard way is that if you don't give people an API or you give them an insufficient API they'll resort to screen-scraping and hacking in order to unlock the value in your product. This can create dependencies on things that were never meant to be stable or it can lead to the emergence of widely-used but unofficial APIs. 

That behaviour can harm your product, your developers and your users. For example it can lead to a mismatch in expectations when some developers believe they're using an official API with established deprecation and change management policies. You also have to ensure that the APIs you create don't damage the product, for instance, by making it very easy to spam or game your system.

Providing an API, no matter how good, is just the start. The next challenge is to make something valuable enough that developers will use it in the absence of some extrinsic compulsion.

Firstly this involves making something that's easy to experiment with. So it should be easy to copy-paste a personalised URL into a browser and see a pretty-printed dataset.

Then you have to offer a path from there. The path starts with letting people play even if they don't understand your service all the way to the point where they understand your abstractions and the specifications you're using.

People should be able to go from playing in the browser to playing at a terminal with curl/wget to playing with an OAuth-enabled HTTP client to playing with your specialized wrapper libraries for your API to building businesses upon your platform.

But you can't just stop there. If you want to go from merely offering an API (typically a set of CRUD operations on your product's datasets) to building a viable platform you need to solve some difficult problems:

• how does your platform, as opposed to your product, generate revenue or value for you?
• how does your platform generate revenue or value for those who build upon it?
• how do you respond to and/or incorporate the innovations that will be built upon your platform?
• how do you nudge developers into creating more value than they capture from your users and your platform?
• what happens to this surplus value? Is it being re-invested in the platform or siphoned off?

Even if you solve all these problems you don't have any guarantees of long-term success. The transition from API to platform to ecosystem is difficult and most APIs don't make it. However APIs can still help developers create new possibilities along the way.

What is Developer Experience?

Developer Experience (#devexp) is an aspirational movement that seeks to apply the techniques of User Experience (UX) professionals to the tools and services that we offer to developers. Developer Experience can be boiled down to 4 main ideas.

1. Apply UX techniques to developer-facing products.

These techniques and ideas include:

• Personas
• Lo-fi prototyping and sketching
• Usability testing by watching people try to use your products without interfering so that you can get a realistic understanding of how people will actually respond. Some companies set up usability labs or run hackathons in order to get this kind of data.
• A wider range of techniques from UX research practitioners
• GOMS

2. Focus on the '5 minute Out Of Box experience'

The idea here is that if you provide a library, developers should be able to go from downloading to "Hello World" in 5 minutes. You should test this with a stopwatch or even a screencast to prove this is possible. Ideally they should then be able to take the code from this 5 minute experience and evolve it as their requirements grow in sophistication without having to start over. Making a library that supports the same user from unsure novice to sophisticated expert is hard but pays off in terms of increased adoption and fewer questions on the mailing list.

3. Use convention over configuration

This was most clearly stated by the Ruby On Rails community but is rooted in a simple insight. When someone first starts using your API or library they have the least knowledge so that's the worst time to ask them to make lots of complicated decisions with far-reaching implications. This is why you, the developer of the library or API, should make the initial decisions for them by establishing conventions that can be overridden with configuration options.

4. Try to "design away" common problems rather than documenting workarounds

For instance if your users struggle with getting OAuth working then create abstractions that handle it for them rather than documenting the 6 most common problems or writing up the 'simple 12 step process' for getting it working.

This is inspired by Don Norman's work on perceived affordances which says that things should be designed in ways that immediately suggest how you should use them. If you walk up to a door it should be obvious without reading any signs, whether you should pull, push or slide the door to open it. If the door needs to be documented with a sign then it was badly designed.

This theory of affordances applies just as well to developer tools and APIs. They should be designed to have affordances that encourage correct usage rather than documented to make up for deficiencies in usability.

---

The phrase (developer experience) and the hashtag (#devexp) comes from Michael Mahemoff but it's not a new idea. Its roots are in ideas and practices such as:

• Microsoft's usage of developer personas
• David Heinemeier Hansson's usage of screencasts to announce the Ruby On Rails framework and to show off the smoothness of their Out-Of-Box-Experience.
• The Ruby community's widespread application of convention over configuration
• Nat Pryce's OSJam presentation based on the insight that "programmers are people too"
• Jeff Atwood's 2005 blog post stating that "developers are users too."
  
• Steven Clarke's research and blog on the experiences developers have with development tools and frameworks.
• Josh Bloch's work on the impact of good API design
• My session at O'Reilly's Open Web Foo conference about "making APIs usable"
• Pamela Fox's crowd-sourced survey on the elements of a positive developer experience

It's a set of ideas we would like to see more people, projects and companies adopt. We don't claim to be paragons and we're looking to learn from other people's examples.

That's why we've set up http://developerexperience.org/
We hope to use it to point to examples of great developer experiences as well as aggregating relevant tweets using the #devexp hashtag.

Please join us. You can start by using the tag "devexp" whenever and whereever you write about developer experience. Over time this will help us build up a body of knowledge that will do for developers what UX has done for users.

---

Add comments on Buzz

The irony and the tragedy of OAuth scopes

I was taking a look at my PeerIndex profile when I got the above screen. I was surprised since the button I clicked said "sign in with Twitter" and didn't mention anything about updating my data. I did a little digging and it seems that I'm not the only one who has this reaction.

In my case it was especially ironic since one of the things that I've been trying to do with the Buzz APIs is encourage developers to ask for the minimum set of permissions that they need.

The idea is that an app which is just going to use its access to your account to gather metrics shouldn't also be able to post messages on your behalf. That's why we expose 3 different scopes. These are read-only, read-write and a special scope for photos because those tend to be especially sensitive.

However developers will often just ask for the maximum set of scopes in order to give themselves the freedom to implement new features later on without having to ask the user to re-authorise them. They do this because it's easier for them and because they believe it results in a better user experience since the user isn't constantly being asked to give permission.

Unfortunately what many developers don't notice are the users who get to the authorisation screen and then close the tab because they don't understand why your app needs write-access to their account. The point is that asking for overly broad permissions, just like the password anti-pattern, repels users.

In the case of the Twitter API the problem seems to be that any HTTP POST API call is considered a write and so services like PeerIndex end up needing to ask for read-write access even though they're well-behaved.

The tragedy is that all parties are trying to create the best possible user and developer experience (by avoiding complicating the user interfaces with lots of options and removing the need to constantly ask the user for new permissions) but the end result is bad for all concerned.

---

Add comments on Buzz