New Project: Flex Collaboration Library

I’ve been digging deeply into the dark crevices of Adobe Flash Collaboration Services (AFCS) my session on creating collaborative components at MAX this week. One of my examples is a collaborative map so I relied heavily on the Yahoo Maps example that ships with the AFCS SDK. One of the things I like about the Yahoo Maps example is that it includes a class that extends ArrayCollection and includes some hooks for collaboration. It’s essentially a collaborative ArrayCollection and I rewrote parts of it for my own example and have found it to be very useful across a lot of my projects.

I realized that it could lower the barrier to entry on AFCS if some of the Flex classes that people rely on a lot had “automatic” support for collaboration via AFCS. So I took the class I created based on the Yahoo Maps example and tried to make it as “drag-and-droppable” as can be for someone who wants to start using AFCS. It merges two concepts, the ArrayCollection concept, and the CollectionNode concept from AFCS. CollectionNodes let you store any piece of data on the server and lets multiple people add/change/remove information from the collection. Events are fired so that any time someone changes a piece of data it can be updated across all of the connected clients.

What I’ve done with my SharedArrayCollection class is put all of that logic into a single class that extends ArrayCollection. Developers can use the SharedArrayCollection just like they would use an ArrayCollection but the difference is that the SharedArrayCollection is automatically enabled for multi-user collaboration with AFCS. The only major difference is that instead of listening for a collectionChange Event you listen for a CollectionNodeEvent.

I’m still hacking out the basics and after MAX I’ll try to provide an example use case so people can see exactly how it works. I’ve put everything up on GitHub under the Flex Collaboration Library project. I’m hoping to make the SharedArrayCollection more bullet proof and then create more AFCS-enabled Flex classes and components. Let me know if you find a bug or if you find this at all useful.

The Full Flash Platform Services Story

platform_servicesToday we announced the release of the distribution side of Flash Platform Services. Most of the action is on Techmeme but I liked the ReadWriteWeb post, the TechCrunch post, and the VentureBeat post specifically. Distribution Services is the one that’s new and the goal is to let you track your application across a number of different screens while also simplifying the distribution mechanism. There are also hooks that will let you easily bring in advertising so that you can both track and monetize your content. The first thing people will think of is widgets, and that makes sense because a lot of the “sharing” aspect, which we’re partnering with Gigya for, will remind people of the widgets they’re able to place on Facebook, MySpace, blogs, and other places. But as Serge’s MAX Widget shows, these can be more complicated applications as well. So while widgets may be the first thought, any one of these three threads; sharing, tracking, and advertising, can be brought into an application of any size. So regardless of what kind of application you’re building, these services should be helpful.

Show me the money
One thing this allows you to do is easily monetize your content. The money side of this is that advertisers or developers can buy installs and pay a fee (starting at one dollar) per successful installs. You can also target this a bit, so if you want to make sure a high number of people are embedding your widget, you can promote it via the network and you’ll be charged a fee anytime someone embeds or installs your content. On the profit side, you can also offer to host advertisements via our network. We’ll give you a specific CPM (cost per thousand impressions), we estimate around $5, and pay that out to you.

Mobile
These services also work with mobile devices. This is one of the slickest features I’ve seen demoed because when a user wants to install a shareable mobile application, they’ll get an SMS with a link to the application. When they click it, our distribution service detects which device they’re on and will push out the correct version of the application. Currently we support Symbian S60 phones, Windows Mobile, and the iPhone. That doesn’t mean you can use Flash on the iPhone, but you can create an iPhone version that can be pushed out with our distribution network.

The Rest of the Services Story
There are three parts to the Flash Platform Services initiative; Distribution, Collaboration, and Social. Distribution is what we announced today, Social will make it easy to integrate social networks like Facebook and MySpace, and Collaboration has been in beta for a while, you know it as Flash Collaboration Services. All of these will have a pay-per-use model and will provide added functionality or easy integration for developers. The Flash Platform is the most cutting edge technology on the web. The full range of things it lets developers and designers do just doesn’t exist on any other platform. As a result, we’re able to do some very interesting things when it comes to collaboration, tracking, distribution, or integration. The goal of these services is to make it much easier for any Flash Platform developer to accomplish those things. Lowering the barrier to entry for things that makes Flash so powerful is going to be beneficial for a lot of developers.

In The Bay Area? Come Check Out AFCS

I’m going to be presenting at the Bay Area Application Developer Adobe User Group today (Tuesday) on Adobe Flash Collaboration Services. It starts at 6:30 at Learn iT!. Here’s the blurb:

Ryan will walk us through how to getting started with AFCS, show us how to use the default pods that are delivered with AFCS, and how to extend existing components to make them collaborative. Finally he will show us real world examples of AFCS in action.

The Web Way vs the Wave Way vs the Flash Collaboration Services Way

afcs_logoAnil Dash has a post worth reading up on his blog that talks about the “Web Way” versus the “Wave Way” and why Google Wave won’t succeed because it doesn’t really fit the same pattern of successful web technologies. He makes 4 general points to define the “Web Way”:

  • Upgrades to the web are incremental. Instead of requiring a complete overhaul of your technical infrastructure, or radical changes to existing behaviors, the web tech that wins is usually the sort of thing that can be adopted piecemeal, integrated as needed or as a normal part of updating one’s websites or applications.
  • Understanding new tech needs to be a weekend-sized problem. For a lot of web developers, long before they start integrating a new protocol or platform into their work, they hack together a rough demo over a long weekend to make sure they truly grasp how it works. And a weekend-scale implementation on a personal site usually translates roughly into a 90-day implementation cycle in a business context, which is a reasonably approachable project size. (In tech, three days in personal effort often translates to three months of corporate effort.)
  • There has to be value before everybody has upgraded. This is basically a corollary to Metcalfe’s Law. While we know networks increase in value as they add more nodes, the nature of web tech is that, in order to be worthwhile, it has to provide value even if the people on the other end haven’t upgraded their software or web browsers or clients or servers. Otherwise you’re shouting into an empty room.
  • You have to be able to understand and explain it. Duh.

The entire post goes on to explain details of where Wave fits and where Wave fails. But as I read it I couldn’t help see it as a ringing endorsement of Flash and especially Adobe Flash Collaboration Services (AFCS). Before I dive in, I understand that Anil’s “The Web Way” has an inherent requirement that everything be “open”. Flash and Flash Collaboration Services probably won’t fit in most people’s definition of “open” as it relates to the web. In this case, I think that’s part of the benefit. One thing Anil does is looks at Wave from the developer perspective and he provides a list of technologies required to use Google Wave and add real-time collaboration to your web application:

  • Federation (XMPP)
  • The robot protocol (JSONRPC)
  • The gadget API (OpenSocial)
  • The wave embed API (Javascript)
  • The client-server protocol (As defined by GWT)

That’s a lot of stuff for a developer to know and understand if they want to start building something that interoperates with and leverages the technology behind Google Wave. Now think about a Flash developer who wants to add real-time collaboration to their web application. They’ve got no real new protocols to learn (RTMP behind the scenes but not necessarily exposed in such a way that developers need to understand it), no new languages to learn, no new client-server protocol, it’s just ActionScript and(/or) Flex, and some new APIs. Then your application is real-time enabled. So lets look at the four “Web Ways” and see how they apply to AFCS.

  • Upgrades to the web are incremental. With the pods and APIs for AFCS, it’s pretty damn easy to just integrate it with your current application. There is no rewriting from scratch and you can literally just add an AFCS component and enable collaboration for your application. As you dig deeper, the service gets more complex and you can do more with it, but to start, it’s dead simple.
  • Understanding new tech needs to be a weekend-sized problem. If you’re a Flash developer already, all you’re learning are a few new APIs. You still have to understand the fundamental issues behind real-time collaboration if you want to create complex components, but you’ve got the core development skills to create those applications so you can focus on learning the theoretical stuff and not the code stuff.
  • There has to be value before everybody has upgraded. This is my favorite, because it’s one of the benefits of Flash. AFCS has 2 versions, a Flash Player 9 version and a Flash Player 10 that adds some more audio support. If you’re targeting Flash Player 9 then 98.8% of the web can see your application and with Flash Player 10 it’s 86.7%. No one has to upgrade anything to see your new real-time enabled application.
  • You have to be able to understand and explain it. With AFCS you can easily add real-time collaboration features like video chat, whiteboarding, and shared data into your Flash-based application. I think that works.

Now again, I understand that openness is a pretty core part of what the web is. But there has always been a trade off between openness and innovation when it comes to the web. And even in cases where “open” can be innovative, like with Google Wave, everyone else has to catch up. With AFCS, even though it may not fit with the wider definition of the “Web Way” you can take advantage of the cutting edge technology that everyone is excited about and ensure that it’s 1) easy to build and 2) easy for your customers and users to view.

Thanks to Sachin for tweeting the link to Anil’s post. I didn’t take the time to read it until I saw he did.

Week of AFCS Revisited: SharedObject

After my trainwreck post on using CollectionNode in AFCS Nigel suggested that I try to recreate my example using the higher level APIs instead of trying to build everything from scratch with NodeCollection. As I mentioned in the previous post, the AFCS team did a great job of creating very basic APIs like CollectionNode and then building on top of those to make APIs that are easier to use. SharedObject is a perfect example of that.

Here’s what I wanted to accomplish: Create a basic multiplayer game where players try to match colors with each other using a ColorPicker. Using the SharedObject class it’s really pretty easy. The first thing I did was set up a room where guests are automatically promoted and no username/password is required. Then I used a combination of AFCS components and Flex components to create a user interface for entering a display name, picking the color, and showing how many players there are:

<rtc:AdobeHSAuthenticator id="auth" />
<rtc:ConnectSessionContainer id="cSession" 
          authenticator="{auth}" 
          roomURL="{_roomURL}"
          synchronizationChange="cSession_synchronizationChangeHandler(event)"
     <mx:Panel id="panelColor" title="Pick a Color!"
          horizontalCenter="0" verticalCenter="0" alpha=".3" 
          width="200" height="200" enabled="false"
          <mx:ColorPicker id="color" change="color_changeHandler(event)" width="100%" height="100%" />
<mx:Label text="Playing with {cSession.userManager.userCollection.length - 1} other people" />
</mx:Panel>
 
<mx:TitleWindow id="tw" horizontalCenter="0" verticalCenter="0"
          <mx:TextInput id="username" width="150" text="Enter A Username" focusIn="{username.text = ''}" />
<mx:Button id="btnLogin" label="Login" click="btnLogin_clickHandler(event)" />
</mx:TitleWindow>
</rtc:ConnectSessionContainer>

Nothing major there, notice we’re using the userManager class to get the number of other users in the room (and that it’s bindable). The big thing is the synchronizationChange event handler. In that function we’re going to configure our node and create the SharedObject.

public var sharedColor:com.adobe.rtc.sharedModel.SharedObject;
 
protected function cSession_synchronizationChangeHandler(event:SessionEvent):void
{
if( event.type == SessionEvent.SYNCHRONIZATION_CHANGE )
{
var config:NodeConfiguration = new NodeConfiguration();
config.userDependentItems = true;
 
sharedColor = new com.adobe.rtc.sharedModel.SharedObject();
sharedColor.sharedID = "color";
sharedColor.setNodeConfiguration(config);
sharedColor.subscribe();
sharedColor.addEventListener(SharedObjectEvent.PROPERTY_ADD, onPropertyChange);
sharedColor.addEventListener(SharedObjectEvent.PROPERTY_CHANGE, onPropertyChange);
sharedColor.addEventListener(SharedObjectEvent.PROPERTY_REMOVE, onPropertyRemove);
}
}

We have to use the full namespace when we reference the SharedObject in AFCS because it conflicts with the normal Flash SharedObject. We first do a check go make sure we’re in a SYNCHRONIZATION_CHANGE event and then start setting things up. The only change I make to the default NodeConfiguration is to make it so that when a user leaves the room, they take their items with them so we don’t have “ghost” matches. That’s done by setting the userDependentItems property to false.

Next we create our SharedObject. I give it a sharedID of “color” and then make sure the application is subscribed to the SharedObject so that it sees any changes. Finally I set up event handlers for whenever a property is changed, added and removed. The add and change properties use the same function, onPropertyChange.

Let’s first take a look at how we create the SharedObject; something that happens whenever we change our color selection.

protected function color_changeHandler(event:ColorPickerEvent):void
{
sharedColor.setProperty(cSession.userManager.myUserID,color.selectedColor);
}

We use the setProperty() method on the SharedObject to give it information. A SharedObject is just a name/value pair, or in this case, a propertyName/value pair. I set the propertyName to the userID so we can know where the color came from and then set the value to our selected color. Whenever we set that property it will create a property change event and call our event handler.

protected function onPropertyChange(event:SharedObjectEvent):void
{
if( event.propertyName != cSession.userManager.myUserID)
{
if(event.value == color.selectedColor)
{
var user:UserDescriptor = cSession.userManager.getUserDescriptor(event.propertyName);
sharedColor.removeProperty(cSession.userManager.myUserID);
Alert.show("You matched with " + user.displayName + "!");
}
}
}

This is where the game starts to happen. The way AFCS works is that when you change a something locally inside of your application it is sent to the server and then you get a change event when it comes back. This is so you can be sure the change was successful. In our game we want to make sure that we’re not dealing with the event we just sent so I use the propertyName property and compare it to myUserID to see if it’s an event that the user sent him or herself. If it isn’t, we look for a match using the value property and our selectedColor. If we have a match I use the UserManager class to get the display name of the matched user and pop up an alert box to show that we found a match.

The other thing I do is to call the removeProperty() method the user’s SharedObject. I ran into an issue where when a user selected a color that matched another one, the other user would get the popup but there was no easy way to notify the user who selected the color that it was a match. I solved this by removing the property which would then trigger a PROPERTY_REMOVE event and fire our event handler.

protected function onPropertyRemove(event:SharedObjectEvent):void
{
var user:UserDescriptor = cSession.userManager.getUserDescriptor(event.propertyName);
if( event.propertyName != cSession.userManager.myUserID && user != null)
{
Alert.show("You matched with " + user.displayName + "!");
}
}

It looks similar to our change event handler. I first get the user information for the popup and then I check a couple of things. First, I make sure that the event isn’t coming from the current user, but the user I have the match for. I also want to make sure that the SharedObject wasn’t removed by someone just logging out (remember our NodeConfiguration settings). If my user is null then that means the user is gone and the event fired because the user left the room and not because I specifically removed it.

That’s pretty much all there is to it. You can grab the project here or I’ve embedded the game below (and here’s a direct link), so feel free to play and see if you can match colors!

data=”http://www.digitalbackcountry.com/afcs/colorgame/ColorGame.swf”
width=”450″
height=”400″>

A Week of Flash Collaboration: Shared Models and Collection Nodes

Update: This blog post took me the better part of a day and a half and just as I was posting it I realized I had a huge hole in the logic for my application because of the problem at the bottom. My plan is to come back and clean this up, as Peter suggested, divide it up into a couple of parts. The most important parts are the first couple of paragraphs that talk about the sharedModel classes and the last paragraph that mentions how the AFCS team architected things to build on top of very low level base classes like CollectionNode. Largely this blog post is a mess and digging into CollectionNode was interesting but I recommend it only after having some time playing with the other classes in sharedModel. After that this might be a useful post to read. Diving into the video tutorials is also highly recommended.

The basic building blocks of Adobe Flash Collaboration Services (AFCS) are really the sharedModel package which includes the CollectionNode classes. Using the classes in the sharedModel package you can share any piece of data across AFCS connections and use these classes to build custom collaboration components like charts or maps where data can be updated and must change for everyone who is connected. I’ll first talk about some of the classes in the sharedModel package and then dive into how to use the CollectionNode, which provides the base functionality for sharing data.

Shared Models
The classes in the Shared Model package include a number of ways to share data and actions with AFCS. For the most part, the classes in sharedModel all use the CollectionNode to exchange data but they abstract a bit of the nuts and bolts of CollectionNode to make it easier to use. For instance the SharedProperty class lets you take any arbitrary property and share it across AFCS instances. It includes the ability to specify a CollectionNode or to just use one that will be generated as soon as the component using SharedProperty is created. Nigel Pegg has a great tutorial which covers using SharedProperty. Another set of classes in the sharedModel package are the Baton classes. The Baton is essentially a SharedProperty that gives you more control over when a user can edit something. The Baton class helps define when something is currently in use and shouldn’t be editable by anyone else in the room. It includes methods to grab() and putDown() a baton as well as a batonHolderChange event that can be used to make changes to the user interface. Nigel’s video goes through this as well using the example of a TextInput box. Using the Baton classes it is easy to disable editing of the TextInput while someone else is typing inside of it.

CollectionNode</strong
All of the classes above use collection nodes and there are three major parts to the basic CollectionNode: creation, configuration, usage. As the documentation states, an AFCS room is essentially a bunch of CollectionNodes exchanging data and each of those nodes has specific configurations that define who and how people can interact with them. One thing to note is that CollectionNodes can only be created by a room owner, or someone with UserRoles.OWNER so when creating a CollectionNode, the owner must be the first person in the room so they can “initialize” it. After that the developer can use the NodeConfiguration classes to customize what level of user has read or write access to the node.

Creating a new CollectionNode is pretty straight forward. In this example I’m going to create a mini-game where the participants have to match up a ColorPicker to “win”. To set up the game, I’ve got one CollectionNode with a “Color” node that will contain the values of the ColorPicker. Here’s how I create the CollectionNode:

protected function application1_creationCompleteHandler(event:FlexEvent):void
{
nodeGame = new CollectionNode();
nodeGame.sharedID = "gameNodes";
nodeGame.addEventListener(CollectionNodeEvent.SYNCHRONIZATION_CHANGE, onSync);
nodeGame.addEventListener(CollectionNodeEvent.ITEM_RECEIVE, onItemRecieve);
nodeGame.subscribe();
}

A few things to notice. First, the sharedID property is described in the docs as the “logical address of the collection within the room” and is how AFCS will refer to it so it needs to be unique. It is also the name that you will see when you browse the nodes in the room console that comes with the SDK. Second, in order to use the node we have to make sure it’s synchronized or we’ll get an error. After creating the node I added a CollectionNodeEvent listener that fires when we have a synchronization change event. I also added an event handler for when we receive messages upon subscribing to the node which I’ll talk about later. Once the SYNCHRONIZATION_CHANGE event fires we can start making changes to our CollectionNode:

protected function onSync(event:CollectionNodeEvent):void
{
var config:NodeConfiguration = new NodeConfiguration();
config.modifyAnyItem = false;
config.userDependentItems = true;
 
nodeGame.createNode("Color",config);
createMessage(false);
}

Now that we’re able to make changes to the CollectionNode I can create the Node that will store messages, in this case the “Color” Node. First I need to use the NodeConfiguration class to set up some rules for the game. By setting the modifyAnyItem property to False I make sure we’re not allowing users to modify messages that aren’t created by them. The userDependentItems property set to true means that when the user leaves the room, we clear out all of the messages belonging to them. In our game we don’t want to find a match with someone who isn’t playing any more. The NodeConfiguration classes allow us to tweak things like what happens to messages as well as define permissions for specific nodes within my CollectionNode. Once we’ve created the NodeConfiguration I can use the createNode() method to create a Node named “Color” and pass in the configuration values I just created. The last method there is a function I created. After we create the node and configure it I want to send the value of my ColorPicker to AFCS so I can start playing the game. I do that with a createMessage()</code< function.

protected function createMessage(overwrite:Boolean):void
{
var colorMessage:MessageItem = new MessageItem("Color");
colorMessage.itemID = cSession.userManager.myUserID + "_color";
colorMessage.body = color1.selectedColor;
 
nodeGame.publishItem(colorMessage,overwrite);
}

My createMessage() takes one variable, a Boolean that we'll use to tell AFCS whether or not we are allowed to overwrite an existing message. The first part of the code is where we create our MessageItem to be sent. I'm just creating a new MessageItem and passing in which Node it will belong to, in this case the "Color" node I created above. Then I give it an itemID which is how it will be referred to by AFCS. I use the current userID and prepend that to the word color. Finally I set the body of the message. The body of a MessageItem can be a String, a Boolean, a Number,or a key-value pair. In this case we're just going to pass in our selectedColor value. Once we create the MessageItem we need to add it to the Node. To do that we use the publishItem() method on the CollectionNode. This is where I pass in the overwrite flag. In this case, I don't want the MessageItem to be overwritten because this should be the first time we're adding it since we called it from the OnSync method. But later I want to make sure we overwrite it because we're making updates to it.

As soon as we publish our message, it's going to go into AFCS and then AFCS is going to send it back to us so we make sure it was sent correctly. When that happens it will fire an ITEM_RECEIVE event which we added an event handler for in our initial function. That code looks like this:

protected function onItemRecieve(event:CollectionNodeEvent):void
{
var tempMessage:MessageItem = event.item;
var userName:String = cSession.userManager.getUserDescriptor(tempMessage.associatedUserID).displayName
 
arrColors.push({color:tempMessage.body,user:userName});
if(tempMessage.associatedUserID != cSession.userManager.myUserID)
{
if( tempMessage.body == color1.selectedColor )
{
Alert.show('Winner! Your partner is: ' + userName);
}
}
}

This is where we start to get to the game. The first to lines just put the MessageItem and user displayName into their own variables. Next we put the selectedColor from our message and the displayName into an array that's stored on the client. This is kind of important. A lot of the sharedModel classes, like SharedProperty for instance, will handle storing data for you but the CollectionNode class doesn't, it's a very basic, low level component. So in this case we can't tell AFCS to send us a list of messages to check and see if there is a match, we have to keep a record within our own application. I do that by storing the information in an Array. Once I do that I want to check if we have a match but I need to make sure we're not matching our own color so I do a quick check using the associatedUserID and myUserID from the ConnectSession. Once we know that isn't the case I can check the body of the message with my current color to see if there is a match and pop up the appropriate dialogue.

When we make changes to our color to try and find a match we also need to send the update to AFCS and check our Array so I added an event handler to my ColorPicker for any change event:

protected function color1_changeHandler(event:ColorPickerEvent):void
{
createMessage(true);
for(var i:Number=0; i<arrColors.length; i++)
{
if(event.color == arrColors[i].color)
{
Alert.show('Winner! Your partner is: ' + arrColors[i].user);
}
}
}

In this case the first thing we do is call createMessage() with the overwrite flag set to true so we are overwriting our current message with the new color value instead of creating a new one. Then we run through our array of colors to see if this new color matches anything on the system. Do you notice a problem?

The problem is this: We configured our Node to remove all messages as soon as someone leaves the room but because we're using CollectionNode instead of one of the higher level classes we also have that array that is storing the values. We're using that array to check for a match after we change our color but we don't ever clear out old messages from our array so we might get a match from someone who is no longer logged in. We're also not checking the array and updating values so we have a lot of old data.

Welcome to Multi-User Applications
Multi-user applications are fun but there is also a lot to deal with. Luckily, the AFCS team has done a very good job of building base functionality into classes like CollectionNode and then building on top of them with classes like SharedProperty that take care of a lot of the complicated parts of managing a collaborative application. I tried to get nitty gritty and show how CollectionNode works but I really encourage you to start with the higher level classes, get an idea of what's happening, then break down to the low level base classes when you need to start creating very customized collaborative applications with specific rules, custom components, and many different types of data.

You can grab the full project here (Flash Builder 4 FPX file) and see how the parts fit together. I'll be updating it in the next few days to take into account the problem above and include a version that people can play.