First of all, make sure to download the AIR Example used in this Tutorial. The zip contains a Flash Builder 4 Project Folder as well as a Flex Project FXP File so you can import the code easily if wanted. If you don’t have Flash Builder 4 you can always just look at the code in the src folder within the zip. As you will notice, the example uses the awesome doomsdayconsole. The code for it is not included in the example but can be retrieved from its googlecode site. You will also need the AS3Crypto Library which also is not included in the example.

Without any further ado, here are the steps neccessary to get pinless OAuth working.

Let’s take a look at the important parts of tweetrAIR.as:

1
2
3
4
5
6
7
8
9
10
11
12
13

oauth = new OAuth();
oauth.consumerKey = "YOUR_CONSUMER_KEY";
oauth.consumerSecret = "YOUR_CONSUMER_SECRET";
oauth.callbackURL = "http://your.callback.url";
oauth.pinlessAuth = true; 
 
oauth.addEventListener(OAuthEvent.COMPLETE, handleOAuthEvent);
oauth.addEventListener(OAuthEvent.ERROR, handleOAuthEvent);
 
var rect:Rectangle = new Rectangle(50,50, 780, 500);
htmlLoader = HTMLLoader.createRootWindow(true, null, true, rect);
oauth.htmlLoader = htmlLoader;
oauth.getAuthorizationRequest();

As you see there’s not much to do configuration wise. First of all, we create a new OAuth instance and then assign our consumer key and consumer secret which we get from twitter (line 1-3).

The important parts here are the callbackURL and pinlessAuth at line 4 & 5. You need to set the pinlessAuth Boolean to true in order to enable (obviously) pinless authentication and you need to define a callback url for which your AIR app will be listening for. The callback url can be anything on the internet that does not redirect any further, for example “http://google.ch” or “http://yourdomain.com/static.html”. Twitter will append some GET parameters to this url for which your OAuth instance will be listening for.

Pinless Authentication for AIR Desktop Applications requires you to pass a HTMLLoader instance to your OAuth instance (see line 11 & 12). Once you have done that, you can call getAuthorizationRequest to start the entire process.

The OAuthEvent Handler Method will assign the oauth instance to twitter once an OAuthEvent.COMPLETE event is received, meaning that authentication was successful:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

private function handleOAuthEvent(event:OAuthEvent):void
{
    if (event.type == OAuthEvent.COMPLETE)
    {
        // removes the authentication window
        htmlLoader.stage.nativeWindow.close();
 
        tweetr.oAuth = oauth;
 
        // prints username, user id and the final tokens
        trace(oauth.toString());
    }
    else
    {
        trace("ERROR: "+event.text);
    }
}

And that’s it. From here on out you can call any tweetr method you want. Here’s a short video of the example code running:

_{WATCH IN 800 x 600}

First of all, make sure to download the AS3 Example used in this Tutorial. The zip contains a Flash Builder 4 Project Folder. If you don’t have Flash Builder 4 you can always just look at the code in the src folder within the zip. As you will notice, the example uses the awesome doomsdayconsole. The code for it is not included in the example but can be retrieved from its googlecode site. You will also need the AS3Crypto Library which also is not included in the example.

The Actionscript

The Pinless OAuth process in the library uses the ExternalInterface to communicate with the Webpage
that embeds your flash application. Let’s take a look at the important bits of tweetrAS3.as:

1
2
3
4
5
6
7
8
9
10

oauth = new OAuth();
oauth.consumerKey = "YOUR_CONSUMER_KEY";
oauth.consumerSecret = "YOUR_CONSUMER_SECRET";
oauth.callbackURL = "http://tweetr.swfjunkie.com/dev/verified.html";
oauth.pinlessAuth = true;
 
oauth.addEventListener(OAuthEvent.COMPLETE, handleOAuthEvent);
oauth.addEventListener(OAuthEvent.ERROR, handleOAuthEvent);
 
oauth.getAuthorizationRequest();

As you see there’s not much to do configuration wise. First of all, we create a new OAuth instance and then assign our consumer key and consumer secret which we get from twitter (line 1-3).

The important parts here are the callbackURL and pinlessAuth at line 4 & 5. You need to set the pinlessAuth Boolean to true in order to enable (obviously) pinless authentication and you need to define a callback url which will be opened once authentication has succeeded on twitters side. Last but not least we define some eventlisteners and call getAuthorizationRequest to start the entire process.

The HTML/Javascript

As i said earlier, the library uses the ExternalInterface to communicate with the browser back & forth, thereby we need to add a JS File to our HTML that embeds the Flash and some little snippet of JS Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<html>
<head>
    ... 
    <script language="JavaScript" type="text/javascript" src="js/tweetrOAuth.js"></script>
    ... 
</head>
 
<body>
 
    <div id="flashContentDiv">Your Flash might be in here..</div>
 
    <script type="text/javascript">
        OAuth.setFlashElement("myFlashID");
    </script>
 
</body>
</html>

As you see you have to include the tweetrOAuth.js file and (optimally at the end of your html) tell the OAuth Javasrcipt the ID of your flash element so that javascript can communicate with it by calling OAuth.setFlashElement.

When your Flash application calls getAuthorizationRequest from your oauth instance, it’s going to make an ExternalInterface call to the embedded javascript file which will open a popup window for you to be able to authorize the application. Once this is done, it will redirect to the callback url you have defined in your actionscript code. This Webpage should look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<html>
<head>
    ...
    <script language="JavaScript" type="text/javascript" src="js/tweetrOAuth.js"></script>
    ...
</head>
 
<body>
    ...
    <script type="text/javascript">
        OAuth.verify();
    </script>
    ...
</body>
</html>

As you see, once again we integrate our tweetrOAuth.js file. This time we call OAuth.verify since we should have received the required tokens from twitter back to our callback url. These tokens will be extracted and send back to our Flash application via ExternalInterface and the popup-window should be closed automatically.

And that’s it. When the javascript passes the token, your oauth instance will do the rest and eventually trigger an OAuthEvent.COMPLETE event in which you can pass your fully authorized OAuth instance to your tweetr instance, like so:

private function handleOAuthEvent(event:OAuthEvent):void
{
    if (event.type == OAuthEvent.COMPLETE)
    {
        tweetr.oAuth = oauth;
        // prints username, user id and the final tokens
        trace(oauth.toString());
    }
    else
    {
        trace("ERROR: "+event.text);
    }
}

Here’s a short video of the example code running:

_{WATCH IN 800 x 600}

What’s new

• Pinless OAuth for AIR (Desktop) and pure AS3 (Web)
• Javascript/HTML Template for Pinless OAuth for Web apps
• Minor bug fixes

You can grab the latest files as usual from the tweetr downloads page.

Notable Changes

This release marks the first time that we have two different SWC files. The tweetrWEB.swc is meant for Flex / AS3 Applications, while the tweetrAIR.swc is solely meant for Desktop AIR Apps.

It is discouraged to use the source code from this release on since it requires conditional compiling in order to get it working correctly. Use the specific SWC instead. I will continue providing the source code though in zip format.

The Documentation is now valid for all versions of the Library. AIR only methods and properties will be marked as such.

How to use pinless OAuth

Glad you asked, i’ve prepared two tutorials on how to use pinless OAuth:

• Pinless OAuth in AS3
• Pinless OAuth in AIR

What’s next

Next release will definitely include the Mobile AIR version. Any further plans are quite open since i have plans on refactoring the library to make it more modular, so you only integrate the bare minimum of what you actually use. Which will benefit mobile versions as of course all other versions as well. If you have any urgent requests of features you would like to see, please let me know via the google groups site.

That’s it for now, hope you enjoy the pinless freedom you are getting and as always, if you have any questions/suggestions you can post them on the google groups site if they are tweetr related. In any other case, leave a comment or contact me via mail or twitter.

The technique used is quite simple really. Tweetrs OAuth uses a ExternalInterface Bridge to communicate with Twitter and the redirect after successful authorization.

If you feel adventurous, feel free to try the above example yourself.

Since AIR, Web and Mobile versions all require a different approach for pinless authorization, the next release of the library – for the first time – will also come in 3 different flavors, regardless of flavor though, the API will be the same to ease development processes.

For a quick look at how OAuth will work for mobile, check out Mark Dohertys AIR 2.5 StageWebView Demo where he shows off pinless OAuth on an Android Mobile Device.

I would like to extend my thanks to Mark at this point, since thanks to a short-notice debug session over Adobe Connect, i think we both learned pretty quickly that there wasn’t much to change in the library itself to get Pinless OAuth working :)

I also would like to thank Joe Rheaume (aka @Chronotron) for providing me with his Pinless OAuth Solution. I ended up implementing my own solution because i had already forgotten that i had his approach in my email :) As it seems i ended up doing more or less the same thing as he did without realizing though :). So once again, thanks for that.

There will most likely be another week or two before this new version wil be released as i have a backlog of things that still need to get done before i can release this version. Be sure to keep an eye on SVN though if you want to try out the latest code bits.

Overview Part #2

In this two-part blog post i will cover the technical, as well as overall aspects of implementing accessibility into the EventManager Project. And not just any form of accessibility – the Game has earned the AA+ Certification from Access For All (their highest certification grade conform to WCAG 2.0).

Go here for the first blog post on accessibility. This second part will cover all the technically nitty-gritty, blood and tears that went into implementing accessibility for this project. :)

Some Resources First

Throughout my research and while developing the accessiblity implementation for EventManager i’ve collected useful resources on the web which i’m glad i can share with you via my delicious. There are notes for all the links available that will tell you what type of information you will find behind the click.

Accessibility Introduction

If you haven’t worked with accessiblity in Flash or Flex yet, here’s a short introduction on how it all works.

Flash has it’s own package responsible for all the accessibility features. This package is situated under flash.accessibility.*

Within this package (as of this writing) you will find three classes:

• Accessibility
• AccessibilityProperties
• AccessibilityImplementation

The Accessibility class is a static class that allows you to do three important things. From that class you can check if the user is actually using a screenreader and if it is available or not (Accessibility.active). It also allows you to make sure that all accessibility properties are updated if you change any of their values (Accessibility.updateProperties()). The third and in my opinion most important bit of this class is the capability to manually submit an Event to the MSAA API (Accessibility.sendEvent()).

The AccessibilityProperties class is the place where you define the properties, such as name, description and shortcut that are being presented to accessibility aids. You can also set some properties that control the behaviour of your object towards screenreaders. AcessibilityProperties can be attached to any type of DisplayObject.

The AccessibilityImplementation class, is a bit of a special one. It is the base class in Flash that allows for the implementation of accessibility. This class you will never really use directly, since Adobe advices us not to instantiate it but instead extends AccImpl (which again extends from AccessibilityImplementation) in order to create our own implementation for any custom component we might create. The AccImpl class exists in two versions, one for flash and one for flex.

More Than a Million Words

Instead of boring you any further with details and long paragraphs of information, i figured it’s easier to understand how this all works by actually showing you. Enjoy the videos, if the quality is a bit low and you would like them to be sharper, make sure to head over to the vimeo site itself to download the original videos directly from there.

A Basic Example

_{WATCH IN 800 x 600 | DOWNLOAD EXAMPLE SOURCE CODE}

A Basic AccessibilityImplementation Example

_{WATCH IN 800 x 600 | DOWNLOAD EXAMPLE SOURCE CODE}

The Final EventManager Accessibility Approach

_{WATCH IN 800 x 600 | DOWNLOAD EXAMPLE SOURCE CODE}

Preamble

The greater part of last year i was heads-down-busy developing the EventManager Game which i had the pleasure to build at Liip for Postfinance. EventManager is an educational but fun game, that approaches topics such as budgeting, financing and investing in a modern way (read: not boring you to death).

Today i want to talk to you about the new iteration of the game that we just released a couple of weeks ago. What is new you ask? How about: Accessibility! And not just any form of accessibility – the Game has earned the AA+ Certification from Access For All (their highest certification grade conform to WCAG 2.0).

Overview Part #1

In this two-part blog post i will cover the technical, as well as overall aspects of this endeavour. This first part will cover a brief history of accessibility within the Flash Platform and its current state and hopefully useful insight if you are considering to add accessibility to one of your projects.

Accessibility History in Flash

Thanks to Adobe (and of course Macromedia back then), the Flash Platform has been sporting accessibility features since Macromedia released Flash MX back in 2002. For those that remember, this used to be Flash Player in version 6 and just introduced the Vector Drawing API (ahh, nostalgia.. but i digress).

Over the years obviously the feature set has vastly improved and Adobe (rightly so) can be proud of the level of accessibility that the Platform has today, since it allows you to:

• Create your own tab order
• Set alternative text (naming & description text)
• Set shortcuts
• Set element focus (also visually if needed)
• Communicate statuses to screenreaders.

As you see, there is really not much to wish for left here. In fact, if you use the Flex Framework, all these functionalities and features are just a step away from you. But that’s not all, Adobe has made it quite simple to build your own components within the flex framework, that can with little work, implement the accessibility layer. If that wasn’t enough you even have the capability to manually trigger an event to tell attached screenreaders that something has changed within your application.

For us developers, this means that we have the tools and capabilities to fully fullfill the guidelines proposed by WCAG 2.0.

Dark Side of the Accessible Moon

One of the “limitations” when it comes to the Flash Platform and accessibility, is that it’s only available for the Windows Platform.

There have been many voices that critisized Adobe for “only” implementing the Microsoft Active Accessibility (MSAA) API, yet to this day it seems that it is the only documented and standardized API out there. Also it is to be said, that the most popular and wide used screenreader applications have their home only on the Windows Platform.

Misconceptions & Half Truths

Question: So, since the Flash Platform supports accessibility so well, how come there are only a few accessible flash sites out there?

This question is usually met with one of the following answers:

ANSWER: Costs for implementation too high

There is no denying that implementing accessibility into a flash application is a high cost investment, if you do not already have a developer with prior such knowledge.

This has multiple reasons. Depending on your application it will require an entire different approach than just the straight forward making «Your-Standard-RIA App» or «Form-based GUI App» accessible. Which obviously, unless you have done it before will require tinkering, information gathering, experimenting and lots of testing. Hence, it will take time and thereby cost money.

ANSWER: Too difficult & lack of documentation

I have good and bad news. The good news is if you are considering making your RIA accessible, rejoice! Most of the information / documentation on accessibility for the Flash Platform is actually directly aimed at the Flex Framework and at RIA development.

And here is the bad news: if you want to make something completely custom – like a game – accessbile, make sure you have enough time at your hands, you will need it :). But since you are reading this, hopefully i’ll be able to provide you with enough information to ease your pain :).

The main problem lies not in the fact that implementing is difficult or complicated, it’s the fact that real in-depth documentation is either missing, hard to come by and that examples usually only cover little ground. So the difficulty of implementing accessbility really only comes from the fact that you will have to invest lots of time into testing and debugging.

ANSWER: No time / No money within the project

This really is a convergence of the previous two points. Lack of knowledge and the possible cost of implementation, compared to the percentage of users who actually will benefit from that step, leads often – and here we have to be honest to ourselves – to the quick dismissal of accessibility within projects.

ANSWER: What? Flash is accessible?

Yes genius, have you missed the memo? In fact a few years back when i took Macromedia’s Certified Flash Developer exams there was already a huge part dedicated to accessibility within the exam. Go read up, right now!

Adobe followed in Macromedia’s footsteps and continued to improve accessibility, updating the accessibility features once more in their latest Flex 4.0 Framework and implementing their entire accessibility layer into the freshly released AIR 2.0.

The Challenge

Coming back to our topic at hand, for EventManager i was confronted with a game that had many requirements.

The game’s flow for example, does not allow a regular tab order, it just wouldn’t work. There were also many interactions that would take place without any prior user action and those had to inform the player obviously about what is happening.

Depending on where you were in the game or what you wanted to do, the keyboard had to apply a different layout/scheme that is tailored to the task at hand. For example, when you are on the eventgrounds, you need to be able to place/manipulate constructions, which obviously has an entire different control scheme than for example having to bid on an artist in the auction part of the game.

To make the matter worse, the game has a strong mix of pure flash elements and flex components. Oh, and everything had to be multilingual of course :)

Finding a Solution

Keyboard accessibility was pretty clear from the start. We needed a class that allows us to set a specified keyboard layout/scheme to be active when we needed it.

For user-interactions, it was generally agreed that a context-menu would make most sense and thereby should be used for building constructions and general interaction with the eventgrounds in the game.

When it came to implementing screenreader accessibility the concept had to change a couple times, obviously here the lack of knowledge was a problem and forced me to try out various things until finally finding a working and valiable solution.

At this point i would like to extend my most grateful thanks to Adobe’s Accessibility Evangelist (congrats on the new position!) Matt May , he was of incredible help and was able to give me just the right hints, that helped me resolve some key issues that were plaguing me during my quest for accessibility.

The Final Solution

The final solution can be broken down into three essential parts:

• A global Keyboard Controller that allows applying different control schemes at will.
• A single class from which we can communicate with a screenreader to manipulate its focus, send text to be read via speech synthesizer or displayed on a braille device.
• Last but not least a custom context menu component, that allows us to display a menu of possible actions the user can undertake depending on the situation.

I’ll be covering all the technical details and attempted approaches in the second blog post: Flash & the Quest for Accessibility – Part #2.

The Information Hunt

I’ve invested countless hours in information gathering and hunting down resources concering accessibility and possible ways of implementation so that most screenreaders are supported.

Sadly, as it turns out, supporting all available Windows screenreaders seems to be impossible (see these tests). Thereby i concentrated on JAWS and ZoomText since these two applications seem to be the most widely used, when it comes to assistive technologies.

The resources gathered throughout the project that were useful are publicly available via my delicious account. They have notes as to what information was useful and/or if parts of the information was incorrect or not valid anymore.

Conclusion

All in all, getting the chance to implement accessibility in such a big flex application was an incredibly rewarding experience in multiple aspects.

Getting the chance to actually implement accessibility was a great, allbeit, at times nerve-wracking experience that gave me new and invaluable knowledge.

The most rewarding aspect of the entire project though, to me personally, was to receive the excited feedback from our targeted end-users audience. A big thanks also here to Access4All, the entire team at LIIP and everyone else involved in this big effort and of course to Postfinance for giving us this great opportunity.

Feel free to leave comments or get in touch with me if you have any further questions about flash, flex or accessibility.

If you use AIR Applications under Windows and all of sudden those apps can’t connect to the internet anymore, make sure that your Internet Explorer is not “Working Offline”. You can check in the Menu of Internet Explorer under Tools -> Work Offline. If it has a checkmark, remove it and your apps should be working fine again.

I’m really suprised that the Windows Version of AIR apparently retrieves it’s Network Capabitilies via Internet Explorer and that this behaviour is in no way documented anywhere. Hopefully Adobe will changes this or atleast make sure that people now about this.

You can grab the Project Sourcecode here.

If you want to watch the video in the size it was intended for, go to the Tutorial Page on the Project Homepage.

The first installment is covering “Installing & Setting up the TweetrProxy” and you can watch it in it’s intended size by following this link.

Installing & Setting up the TweetrProxy from Sandro on Vimeo.

On the Tweetr-Front i’ve already released v1.0 beta 2 which adds a couple fixes. Here a short update:

• AS: changed serviceHost call from getter to internal variable _serviceHost [minor]
• AS: added serviceHost to OAuth Class since same crossdomain problem applies [major]
• PROXY: added OAuth Authorization support [major]
• ASDOC: Update Documentations, also added which Methods require Authentication [minor]

As usual you can download the new version from the Project Homepage.

UPDATED: Tweetr has gotten an Update since this blog post. See this blog post for more infos.

I’m proud to announce a major update to Tweetr – the AS3 Twitter API Library. We are now very close to reaching the infamous v1.0!

Eventhough i have tested out most of the features, i am not entirely confident in calling this new release v1.0 and am thereby releasing it as v1.0 beta and hope all of you will provide me with feedback as to how well it works out and if you encounter any bugs.

The new version is available as of right now and can be downloaded from to shiney new Project Home at: http://tweetr.swfjunkie.com .

What’s new

As of now, the library integrates all twitter API features and is supporting Basic Authentication aswell as the much requested OAuth!

• AS: added OAuth Support
• AS: added getHomeTimeLine
• AS: added getRetweetsByMe
• AS: added getRetweetsToMe
• AS: added getRetweetsOfMe
• AS: added retweetStatus
• AS: added statusRetweets
• AS: added Geo Tagging feature to updateStatus
• AS: added searchUser
• AS: added description property to ListData
• AS: updated StatusData to include Retweeted Statuses and Geo Information
• AS: refactored GET Request argument passing
• AS: fixed a bug when parsing SavedSearchData (thx Ken)
• AS: removed deprecated methods, sendTweet, destroyTweet, getSingleTweet, getReplies

• PROXY: Fixed an Image Upload Bug (thx Bhargava)
• PROXY: OAuth Support

Known Issues

As of right now there is one known issue with OAuth and DELETE Methods for Lists. This is a official Issue within the Twitter API thereby we all have to wait for Twitter to come out with a fix for it :)

What’s next

Next i will be doing some Tutorials on OAuth usage and in general on how to use the Library. These will then be posted over at the new Project Homepage. Also i really hope you – dear users – will provide me with feedback on how things work. For that i have setup a Issue Tracker which you will also be able to find from the new Project Homepage.

Whom i’d like to thank

There is one person in particular i would like to thank and that person is Dan Petitt aka Coderanger . I was able to base my OAuth implementation on his great OAuth Class, which really helped me getting started. Thanks mate!

Also i would like to thank you all for the continuous feedback you are giving me and please keep it coming :)

As always, if you build something cool with the library, drop me a line!