Platinum Partner
ria,flash,flex & air,adobe flash collaboration service

Getting started with Adobe Flash Collaboration Service beta

At Adobe MAX, Adobe announced the Adobe Flash Collaboration Service (formerly, code name “Cocomo”) project that you can use to add real-time connectivity and collaboration to any Flex application. Adobe Flash Collaboration Service beta comes with built-in components to add functionality such as whiteboarding and video chat, as well as a framework that you can use to build your own real-time components.

This tutorial will help you get started with Adobe Flash Collaboration Service beta. It will take you through setting up an account, performing the authentication, and then creating a session with some of the built-in pods. At the end, you can make the application accessible to guests so anyone can come into the room and collaborate.

Requirements

In order to make the most of this article, you need the following software and files:

Adobe Flash Collaboration Service beta account and SDK (Adobe ID required)


Sample files:


Flex Builder 3


 

 

Flash Player


Prerequisite knowledge

Basic knowledge of Flex and Flex Builder is required.

Creating your Adobe Flash Collaboration Service beta account

As a first step, you'll need to sign up for a developer account at afcs.acrobat.com.

If you already have an Adobe ID, just sign in with your credentials. If not, take a minute to sign up. After signing in, you will be asked to enter an account name to create the SDK account. The account name will make up the URL that you can use to connect to rooms and build in collaboration.

When you have finished creating your account URL, you'll see the Adobe Flash Collaboration Service beta portal. Here you can provision rooms and see how much bandwidth your rooms have consumed. Click the link to download the Adobe Flash Collaboration Service SDK, if you don't already have it (see Figure 1).

The Adobe Flash Collaboration Service beta Developer Portal after setting up an account.

Figure 1. The Adobe Flash Collaboration Service beta Developer Portal after setting up an account.

To create a room, click the "Add" button in the Room Instances panel. I called mine "demoroom" but you can name yours whatever you want.

Adding Adobe Flash Collaboration Service beta SWC files to your project

The Adobe Flash Collaboration Service beta SDK includes SWC files in the lib directory that provide all of the functionality you'll need to use Adobe Flash Collaboration Service beta. Start by creating a new Flex project, and then add the SWC file from the lib/player9 folder to the project by choosing Project > Properties > Flex Build Path > Library Path > Add SWC. Browse to the lib/player9 folder and select afcs.swc.

There are some special microphone features that are available to you if you're using Flash Player 10. You won't use those for this tutorial, but if you have Flash Player 10, you can use the player10/afcs.swc with no problems. Just make sure to set the minimum Flash Player version of your Flex project to 10.0.0 in the Flex Compiler tab of your project properties.

Adobe Flash Collaboration Service beta authentication

Adobe Flash Collaboration Service beta authentication uses the Adobe Flash Collaboration Service beta SDK's AdobeHSAuthenticator component, which you will need add to your the application.

You can use external authentication, which is the most powerful and flexible way of deploying production applications, or you can open up the room and allow guests to enter without authentication. During development, you can use your developer Adobe ID and password to initialize the components you want to put in your room. For this tutorial, because you're in development, you can start with your Adobe ID, but I encourage you to look at the ExternalAuthentication example in the SDK for the safest way to deploy Adobe Flash Collaboration Service beta apps.

Note: From a security standpoint, hard coding your Adobe ID into a deployed Flex application is never a good idea. Instead it is better to either open your room up to guest users or to use some server-side code to bring the shared secret dynamically so you don't have to hard code it into your application. There are examples and instructions for this in the examples folder of the Adobe Flash Collaboration Service beta SDK as well as some more information in the Adobe Flash Collaboration Service beta Getting Started PDF in the docs/pdf folder.

Your code should look like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" xmlns:rtc="AfcsNameSpace">
<rtc:AdobeHSAuthenticator id="auth" userName="<your Adobe ID>" password="<your password>" />
</mx:Application>

That's all you need to do! The AdobeHSAuthenticator component takes care of making the connection to the Adobe Flash Collaboration Service beta servers.

Creating sessions

Adobe Flash Collaboration Service beta interactions are based on sessions, and sessions are all based on rooms. You'll use the room you created in the Creating your Adobe Flash Collaboration Service beta account section as your room. To create a Adobe Flash Collaboration Service beta session, use the ConnectSessionContainer component. This will be the outsidemost component of the application—everything nested inside of it will refer to the session you create with it. (Although you will you only one session in this tutorial, youcan have multiple sessions in one application.) There are two main parameters for the session component: authenticator and roomURL. The authenticator parameters points to the authentication you set up with the AdobeHSAuthenticator component. The roomURL parameters points to your Adobe Flash Collaboration Service beta account and the room you created with the format http://connectnow.acrobat.com/<your account>/<your room name>/. Set the id of this component to cSession and add it after the AdobeHSAuthenticator component.

<rtc:ConnectSessionContainer id="cSession" authenticator="{auth}"
roomURL="http://connectnow.acrobat.com/<your account>/<your room name>/" autoLogin="true">

</rtc:ConnectSessionContainer>

Notice that the code uses the binding brackets for the authentication property. As a result, when the AdobeHSAuthenticator property changes those changes will be applied to the session. When the autoLogin property is set to true, as in the code above, you will automatically log into the session as soon as the component is created. If set to false, you will need to explicitly call the login() method in your code. By default the autoLogin property is true. Later in the tutorial you'll set it to false, so add it to the component but set it to the default, true, until you need to change it.

Using pods

Now that you have the room and session set up, you can start adding collaborative components. Creating your own components is beyond the scope of this tutorial, so for now, you'll simply use a few of the out-of-the-box pods that come with Adobe Flash Collaboration Service beta.

One of the first things you'll want to do is see who is in the room. There are a number of ways to get this data, but the simplest is just to use a roster pod. you can add that using one line of code inside the ConnectSessionContainer tag:

<rtc:Roster id="roster" width="250" height="200" />

To complete your first collaboration application with a room that has chat functionality and whiteboard functionality, add just two more pods:

<rtc:SharedWhiteBoard id="wb" width="400" height="400" x="205" />
<rtc:SimpleChat id="chat" width="200" height="200" y="205" />

The final code should look like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" xmlns:rtc="AfcsNameSpace" >
<rtc:AdobeHSAuthenticator id="auth" userName="<your adobe username>" password="<your password>" />
<rtc:ConnectSessionContainer id="cSession" authenticator="{auth}"
roomURL="http://connectnow.acrobat.com/<your account url>/<your room name>/"
autoLogin="true">
<rtc:Roster id="roster" width="200" height="200" />
<rtc:SharedWhiteBoard id="wb" width="400" height="400" x="205" />
<rtc:SimpleChat id="chat" width="200" height="200" y="205" />
</rtc:ConnectSessionContainer>
</mx:Application>

When you run that code you'll be automatically brought into the room, and you'll be able to chat and use the whiteboard. If you copy and paste the room's URL into a new browser window you can see any changes you make represented in both windows. But you'll also notice a problem. Your second window will display your name in the roster as "<Your User Name> 2".

Working with guests

Up to now you've been logging in to Adobe Flash Collaboration Service beta with your hard coded Adobe ID. But, as you saw, that doesn't quite work—you need to let your users log themselves in. If you want to, you can use the Adobe Flash Collaboration Service beta Authentication APIs and tie into an external authorization system. For this example, however, all you will do is prompt them for a username and have them come in as a guest with that username.

When you create a room, the collaborative components (that is, the pods you created including the whiteboard, chat, and so on) within it need to be initialized. Only the owner of the account is allowed to add these facilities to the room. By logging in to the room with your developer Adobe ID, you have already initialized the components, so you do not need to do that again. Now you will remove the username and password credentials and make it so that anyone can enter the room with just a username.

You'll need to modify the room settings and prompt the users for a username. To change the room settings, you can use a special Adobe AIR application called AFCSDevConsole. This application was created by the Adobe Flash Collaboration Service beta team and can be found in the extras folder of the SDK. AFCSDevConsole is different from the Adobe Flash Collaboration Service beta portal that you used earlier to create your Adobe Flash Collaboration Service beta account and roomURL.

Install and run AFCSDevConsole. Click the "Add" button in the lower left had corner to add your account. Fill in your roomURL, username, password, and a display name that you can use to identify this account. Also select Log into this account so that when you click Save you'll be automatically logged in. You can use AFCSDevConsole to manage the settings of your rooms. Select your account, the default template and the room you created above, and then click Enter Room. This will take you to the management area where you can change settings (see Figure 2).

Figure 2. After logging in to the Adobe Flash Collaboration Service beta Dev Console

For this example, you want enable guests to log in without having an account. To do this, select Auto-Promote Users. You'll also see that you can make guests knock and be approved before they come in, and you can set the room state to active, ended, hostNotArrived, or onHold. To have this room be as open as possible, leave Guests Have to Knock unchecked and make sure the room is set to active (these should be the defaults). As you change these settings, the settings for the room are being automatically changed so there is no need to confirm or click a button to make the changes (see Figure 3). Now back to code.

Figure 3. The Room Manager in the Adobe Flash Collaboration Service beta Dev Console

Back in your Flex Project, you need to modify the ConnectSessionContainer and change the autoLogin property from true to false:

<rtc:ConnectSessionContainer  id="cSession"
authenticator="{auth}" roomURL="http://connectnow.acrobat.com/ryancocomotest/demoroom/" autoLogin="false">

Also, add a TextInput box so that your users can enter a username. Next, add a ViewStack above the ConnectSessionContainer so you can switch between the TextInput box and the pods you created earlier. In the ViewStack, create a VBox and then put the TextInput and a Button control in that VBox. The code is pretty standard:

<mx:ViewStack id="vs" width="100%" height="100%">
<mx:VBox width="100%" height="100%" verticalAlign="middle" horizontalAlign="center">
<mx:TextInput id="username" text="Username" click="username.text = ''" />
<mx:Button id="btn" label="Login" click="onClick(event);" />
</mx:VBox>
<rtc:ConnectSessionContainer id="cSession" authenticator="{auth}"
roomURL="http://connectnow.acrobat.com/ryancocomotest/demoroom/" autoLogin="false">
<rtc:Roster id="roster" width="200" height="200" />
<rtc:SharedWhiteBoard id="wb" width="400" height="400" x="205" />
<rtc:SimpleChat id="chat" width="200" height="200" y="205" />
</rtc:ConnectSessionContainer>
</mx:ViewStack>

Notice that ConnectSessionContainer is a child of the ViewStack. That's because ConnectSessionContainer extends the Canvas control so you can use it as you would other display objects. Also, make sure to add an onClick handler to the button. You'll create the function for that shortly.

Finally, you need to make changes to the AdobeHSAuthenticator component. Specifically, you're going to remove the username and password and add two event handlers, one for a successful authentication and one for an authentication failure:

<rtc:AdobeHSAuthenticator id="auth" 
authenticationSuccess="onAuthSuccess(event);"
authenticationFailure="onAuthFailure(event);" />

There are two new functions to create in addition to the function needed for the click event of the button. When autoLogin was set to true, you didn't need to worry about explicitly logging users in; Adobe Flash Collaboration Service beta did that for you. But now that you are prompting them for a username, you need to log them in after they click the button. To make sure everything works, you need the authenticationSuccess event handler. If the log in fails and there is a problem authenticating, you need the authenticationFailure event handler. The script tag should look like this:

<mx:Script>
<![CDATA[
import mx.controls.Alert;
public function onClick(event:Event) : void
{
auth.userName = username.text;
cSession.login();
}

public function onAuthFailure(event:Event) : void
{
Alert.show('There was a problem!');
}

public function onAuthSuccess(event:Event) : void
{
vs.selectedIndex = 1;
}
]]>
</mx:Script>

The onClick method sets the username of the AdobeHSAuthenticator component to the one from the TextInput control. Users will see that username in the Roster pod. The onClick method then calls the login() method of the ConnectSessionContainer. That call will result in authorizationSuccess or authorizationFailure. In the case of a success, the code simply sets the ViewStack to the level with the pods.

Where to go from here

That's all there is to it! You created a room, set up the basic parameters, initialized it, and made it accessible to users. You can run this SWF in as many browsers as you want to test it out—just copy and paste the URL in your browser window to other windows. You'll see all the changes happen in real time. You could then export a release version of this from Flex Builder, put that SWF on a server, and create your own collaboration application.

There is much more that you can do with Adobe Flash Collaboration Service beta including creating your own collaboration components when the out-of-the-box pods don't meet your needs. Look for more on that topic in a future tutorial.

For more Adobe Flash Collaboration Service beta resources, visit the Adobe Labs.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

Published at DZone with permission of {{ articles[0].authors[0].realName }}, DZone MVB. (source)

Opinions expressed by DZone contributors are their own.

{{ tag }}, {{tag}},

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}
{{ parent.authors[0].realName || parent.author}}

{{ parent.authors[0].tagline || parent.tagline }}

{{ parent.views }} ViewsClicks
Tweet

{{parent.nComments}}