Twitter @Anywhere Revisited
By Richard Shepherd
06 September 2010 | Category: Code, JavaScript, PHP
I must be honest, I was pretty unimpressed with Twitter @Anywhere when it first launched earlier this year. Of course I hadn’t bothered to check it out, but it seemed like ‘Integration Lite’ - just a very simple way for bloggers to include Twitter on their site.
As Wired reported back in March Twitter’s Evan Williams promised @Anywhere would “reduce friction.”
“You could be reading your favourite columnist [and] you can easily tweet from the column itself if […] you may just want to follow the columnist […] without going back to Twitter.”
Amongst the launch partners for @Anywhere were Digg, Huffington Post and The New York Times. And one of the most high profile users the little known Follow Finder from The Mighty Google.
But alas, it was more a fizzle than a firework and like many at the time I was rather nonplussed.
I’m pleased to say I’ve been completely converted. Not only is playing with Twitter inherently a cool thing to do, it can add real power to your website and more importantly your web applications. Indeed, it’s the scope for easily including Twitter functionality in web applications that’s really exciting.
So let’s take a look at some of this functionality and how you can use it. You’ll be up and running in just minutes, and after briefly looking at some of the simpler methods we’ll dive straight in to integrating Twitter right into your web app.
Registering for @Anywhere
The first thing you need to do is register for an Application ID. It’s ridiculously simply to get, but perhaps worth some explaining to the uninitiated. First head on over to http://dev.twitter.com/anywhere and click on the ‘Start using it now’ button.
You’ll be swiftly taken to a one-page form where you register your app. The first question, particularly to those new at this whole API game, is ‘what if I don’t have an app?’.
Let’s say you just want to use hovercards on your blog. Or let’s say you want your users to be able to tweet about your blog articles by providing them a tweet box at the footer of each page. Not really an ‘app’ is it? More of a feature, a widget perhaps.
Well, in the big wide world of APIs what you have is a web app my friend and you need to accept it! Even the humble ‘Linkify’ method (automatically turning all Twitter usernames into links to their profiles) makes your humble blog post a web application of sorts. Deal with this fuzzy distinction and move on. We need that app ID!!
NB: For the rest of this article I’ll use the term app/application, but it equally applies to your site/blog
Completing the Form
Application Name
Name your application wisely because users will see this name when they are asked to authorise your app; although it’s worth noting that certain functionality, like linkifying and hovercards, doesn’t require users to see this name.
Callback URL
If you intend to use some of the @Anywhere functionality which requires users to authenticate your app then Twitter needs to know which page to send the API response to (which includes lots of handy data about the user that we can tap into using JavaScript!). The callback URL is most likely the very same page that has called the authentication.
If you’re only using simple @Anywhere methods like linkify you can just put your site’s homepage in here.
Default Access Type
This defaults to Read-only, but we want to use some advanced @Anywhere methods so make sure you change this to Read & Write.
Basic functions
Okay, we’ve filled up this car with petrol/gas so it’s time to take it out for a spin! Open a new HTML document and in the <head> of the document include the following line of code:
1 | <script src="http://platform.twitter.com/anywhere.js?id=YOUR-APP-ID-GOES-HERE&v=1"></script> |
Don’t forget to add your app ID into the URL.
Before I go on I feel I must address those of you who now resemble Yosamite Sam, with steam coming out of their ears at the idea of ever including a JavaScript file at the top of a page. But including the anywhere.js file in the head makes a lot of sense for a number of reasons, outlined by Twitter themselves:
- It’s small. Less than 3kb to be exact, gzipped up into a tiny package.
- All dependencies for @Anywhere features are loaded asynchronously, so you only get what you need when you need it.
- Most importantly, when a user logs in and authenticates your app the Twitter login page redirects back to the callback URL. This happens in a pop-up window, so if anywhere.js is at the bottom of the page it’ll mean that the user sees your site in that pop-up before it disappears. Which looks bad and, as Twitter put it, ‘is a poor user experience’.
So leave it in the <head> and let’s move on. Now we need to initialise the a global @Anywhere object which we do with:
1 2 3 | <script> twttr.anywhere(); </script> |
For those who have tried to run that script, you’ll see that nothing happens. That’s because we need to give it a callback function of some sort. For example, to linkify every Twitter username on a page you simply need:
1 2 3 4 5 | <script> twttr.anywhere(function(T) { T.linkifyUsers(); }); </script> |
What’s with the capital ‘T’? Well that’s just Twitter’s convention so we’ll stick with it, but you’re welcome to change it to a more descriptive name. An instance of the API client is passed into T for us to then call methods on, just as we’ve done above.
Run that puppy on a page which has a username in the markup and watch it magically turn into a link. It was roughly about now that I gave up on @Anywhere earlier this year, but stick with me here – it get’s better.
Hovercards
Another method that works in a similar way is Hovercards, which work in the same way.
1 2 3 4 5 | <script> twttr.anywhere(function(T) { T.hovercards(); }); </script> |
With linkifying and hovercarding under our belts its worth looking at another couple of handy features.
Scope
You can limit the scope of a method by passing in a CSS selector. A lot of you will spot that this looks a lot like jQuery and that’s because it’s using the same Sizzle selection engine.
For example, to linkify usernames only in the DIV with an ID of ‘sidebar’ you could use the following code
1 2 3 4 5 | <script> twttr.anywhere(function(T) { T(‘#sidebar’).linkifyUsers(); }); </script> |
Configuration Options
There are a number of option that we can pass to these methods, which we do in an object literal. Again, if you’ve used jQuery before then this will be nothing new to you:
1 2 3 4 5 | <script> twttr.anywhere(function(T) { T(‘#sidebar’).hovercards({ expanded: true}); }); </script> |
Adding {expanded: true} does exactly what it says – it renders the Hovercard in it’s expanded form from the off, rather than waiting for the user to click ‘more’.
Moving Swiftly On
I’m going to skip a bit here, which relates to some of the other configuration options you can use with the various “Anywhere methods. I highly recommend Twitter’s own documentation which you can find at http://dev.twitter.com/anywhere/begin.
Getting more Advanced
If you’ve spent much time surfing the interweb you’ve at some point seen that pop-up window asking you if you authorise an app or a site to play with your Twitter account.
If, like me, you blindly click yes you give that site direct access to lots of your personal (albeit public) information. Normally this isn’t a problem, but with great power comes great responsibility – as James Cunningham of Twifficiency fame (more at TechCrunch).
There are a couple of ways @Anywhere uses this connectivity. The first is with built in functions like the Tweet Box and the Follow button. Both need the user to login to Twitter and authorise your app, so both will cause the authorisation pop-up. We can call both like so:
1 2 3 4 5 6 | <script> twttr.anywhere(function(T) { T('#follow-button').followButton("richardshepherd"); T('#tweet-box').tweetBox(); }); </script> |
This places a follow button in the element with an ID of ‘follow-button’ (and which is set to follow my Twitter account!), and a tweetbox in the element with an ID of ‘tweet-box’.
You’ll can find further details of the Tweet Box and Follow Buttons in the official documentation, but I think it get’s much more exciting to look at connecting your app with someone’s Twitter account and pulling information from their public profile. So let’s go ahead and crank things up! It’s surprisingly simple.
1 2 3 4 5 | <script> twttr.anywhere(function(T) { T(‘#connect’).connectButton({ size: “medium” }); }); </script> |
And that’s it. Try it out, and you’ll see the familiar pop-up asking for you to authorise your app (the name you gave it when you signed up). You can change the size be replacing ‘medium’ with ‘small’, ‘large’ or ‘xlarge’.
Medium is the default, so if you’re happy with that you can remove it from the code. But how about your own custom connect button – how cool would that be? It turns out that the Twitter API has a signIn method which we can attach to any element: text, image or whatever you fancy.
Let’s say you have created your own CSS rollover button, applied to a span with and ID of twitterLogin. Here’s how you’d use JavaScript and the Twitter API to hook the signIn method to that span:
1 2 3 4 5 6 7 | <script> twttr.anywhere(function(T) { document.getElementById(‘twitterLogin’).onclick = function() { T.signIn(); } }); </script> |
We are now freed from the shackles of Twitter’s own graphics and buttons, which makes it possible to create a unique experience for your own app or site. If the user is logged in, the pop-up window will simply ask them to authorise your app. If they aren’t logged in to Twitter it will also ask them for their login details.
I Can Haz your Details?
So your web app now has a connect button, and let’s assume your user has clicked it and logged in/authorised your app. Sweet. What next?
You should have set the Twitter callback URL to the same page as your web app, which means the pop-up will disappear and your page will be sent a bunch of new data (think of it as an AJAX request and response). This means you can use Javascript to check if the user is connected with the rather handy isConnected method. And, assuming it’s all gone to plan, the currentUser property contains lots of handy information.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <script> twttr.anywhere(function(T) { if (T.isConnected()) { // This user is connected. Awesome! var user = T.currentUser; var screenName = user.data(‘screen_name’); alert(‘Hi there ‘ + screenName); } else { // the user isn’t connected, so probably best to show them // a connect button! T(‘#twitterLogin’).connectButton(); } }); </script> |
Admittedly the use of a JavaScript alert here is almost criminal, but you get the idea. Include jQuery and you can start injecting the DOM with lots of Twitter goodness, personalising the user’s experience.
So what other properties can we access, apart from Screen Name? Well, pretty much all of the user’s public profile information is up for grabs. Here are some of the most useful:
- description
- followers_count
- following
- profile_image_url
- location
- name
- time_zone
And you can check out a full like at http://dev.twitter.com/anywhere/begin#user-properties
So using our example above you could access the profile image with:
1 | var imageHTML = ‘<img src=”’ + user.data(‘profile_image_url’) + ‘“ />’; |
What Next?
Of course @Anywhere is no substitute for server side integration with the Twitter API, but it’s a lean way of enhancing your web app/web sites experience for Twitter users.
Have you started to use @Anywhere? If so, tell us how and whether you think it’s enhanced your web application or site. And which features would you like to see in @Anywhere in future releases?
Further reading
Have you been bitten by the @Anywhere bug? If so, here are some great places to find out more…
I also really like this integration of Twitter Hovercards into a WordPress blog comments
Follow @thinkvitamin on Twitter Please check out Treehouse
