Next week I’ll be presenting in Seattle at my first Force.com Developer Meetup! It starts at 6pm on Wednesday, June 22. My session will be on Flex Mobile Development. Other sessions include Force.com Platform Basics, Native iOS Development using JavaScript, and a Force.com Hands-On Lab. It’s going to be a fun evening, so if you are in the Seattle area, then I hope to see you there!

Get more details and register!

Adobe AIR provides a consistent platform for desktop and mobile apps. While consistency is very important there are times when developers need to extend beyond the common APIs. This article will walk you through how to integrate AIR for Android applications with other native APIs and functionality in the Android SDK. It covers three common use cases for native extensibility: System Notifications, Widgets, and Application Licensing.

If you’d like to follow along you will need the following prerequisites:

• Adobe Flash Builder 4.5(which includes the Flex 4.5 SDK and AIR 2.6 SDK)
• Android SDK
• Android Eclipse Plugin

Before getting started, a little background will help. Android applications are distributed as APK files. An APK file contains the Dalvik executable (dex), which will run on an Android device inside the Dalvik VM. The Android SDK compiles a Java-like language to dex.

AIR for Android applications are also distributed as APK files. Inside of these APK files is a small bit of dex that bootstraps the AIR for Android runtime, which then loads and runs the SWF file that is also inside of the APK. The actual dex class that bootstraps the AIR application is dynamically generated by the adt tool in the AIR SDK. The class is named AppEntry and its package name depends on the AIR application ID, but it always begins with “air”. The AppEntry class checks for the existence of the AIR runtime and then launches the AIR application. The Android descriptor file in an AIR APK specifies that the main application class is the AppEntry class.

To extend AIR for Android applications to include native APIs and Android SDK functionality, you start by creating a SWF file using Flex and then copy that SWF file, the dex classes for AIR for Android, and the required resources into a standard Android project. By using the original AppEntry class you can still bootstrap the AIR application in the Android project but you can extend that class to gain a startup hook.

1. To get started, download a package with the required dependencies for extending AIR for Android:
   http://www.jamesward.com/downloads/extending_air_for_android-flex_4_5-air_2_6-v_1.zip
2. Next, create a regular Android project in Eclipse (do not create an Activity yet):
   
3. Copy all of the files from the zip file you downloaded into the root directory of the newly created Android project. You will need to overwrite the existing files and update the launch configuration (if Eclipse asks you to).
4. Delete the “res/layout” directory.
5. Add the airbootstrap.jar file to the project’s build path. You can do that by right-clicking on the file, then select Build Path and then Add to Build Path.
6. Verify that the project runs. You should see “hello, world” on your Android device. If so, then the AIR application is properly being bootstrapped and the Flex application in assets/app.swf is correctly being run.

   At this point if you do not need any custom startup hooks then you can simply replace the assets/app.swf file with your own SWF file (but it must be named app.swf). If you do need a custom startup hook then simply create a new Java class named “MainApp” that extends the air.app.AppEntry class.
   

7. Override the onCreate() method and add your own startup logic before super.onCreate() is called (which loads the AIR app). Here is an example:

   package com.jamesward;
    
   import air.app.AppEntry;
   import android.os.Bundle;
    
   public class MainApp extends AppEntry {
    
   	@Override
   	public void onCreate(Bundle arg0) {
   		System.out.println("test test");
   		super.onCreate(arg0);
   	}
   }

8. Open the AndroidManifest.xml descriptor file and tell it to use the new MainApp class instead of the original AppEntry class. First change the package to be the same as your MainApp’s package:

   <manifest package="com.jamesward" android:versionCode="1000000" android:versionName="1.0.0"
     xmlns:android="http://schemas.android.com/apk/res/android">

   Also update the activity to use the MainApp class (make sure you have the period before the class name):

   <activity android:name=".MainApp"

   You can also add any other permissions or settings you might need in the AndroidManifest.xml file.

9. Save the changes and, when Eclipse prompts you, update the launch configuration.
10. Run the application and you should again see “hello, world”. This time, however, in LogCat (command line tool or Eclipse view) you should see the “test test” output. Now that you have a startup hook, you can do some fun stuff!

System Notifications and Services

AIR for Android applications don’t yet have an API to do Android system notifications. But you can add system notifications to your AIR for Android application through a startup hook. In order for the AIR application to communicate with the native Android APIs you must provide a bridge for the communication. The simplest way to create that bridge is using a network socket. The Android application can listen for data on the socket and then read that data and determine if it needs to display a system notification. Then the AIR application can connect to the socket and send the necessary data. This is a pretty straightforward example but some security (for instance a key exchange) should be implemented to insure that malicious apps don’t discover and abuse the socket. Also some logic to determine which socket should be used would likely be necessary.

1. Inside the application section add a new Android Service:

<service android:enabled="true" android:name="TestService" />

2. Since this example uses a Socket you will also need to add the INTERNET permission:

<uses-permission android:name="android.permission.INTERNET"/>

3. You might also want to enable the phone to vibrate when there is a new notification. If so add that permission as well:

   <uses-permission android:name="android.permission.VIBRATE"/>

4. Save your changes to AndroidManifest.xml.
5. Next, create the background Java Service class, called TestService. This service will listen on a socket and when necessary, display an Android Notification:

   package com.jamesward;
    
   import java.io.BufferedInputStream;
   import java.io.DataInputStream;
   import java.io.IOException;
   import java.net.ServerSocket;
   import java.net.Socket;
    
   import android.app.Notification;
   import android.app.NotificationManager;
   import android.app.PendingIntent;
   import android.app.Service;
   import android.content.Context;
   import android.content.Intent;
   import android.os.IBinder;
   import android.os.Looper;
   import android.util.Log;
    
   public class TestService extends Service
   {
     private boolean stopped=false;
     private Thread serverThread;
     private ServerSocket ss;
    
     @Override
     public IBinder onBind(Intent intent)
     {
       return null;
     }
    
     @Override
     public void onCreate()
     {
       super.onCreate();
    
       Log.d(getClass().getSimpleName(), "onCreate");
    
         serverThread = new Thread(new Runnable() {
    
           public void run()
           {
                   try
                   {
                           Looper.prepare();
                           ss = new ServerSocket(12345);
                           ss.setReuseAddress(true);
                           ss.setPerformancePreferences(100, 100, 1);
                           while (!stopped)
                           {
                                   Socket accept = ss.accept();
                                   accept.setPerformancePreferences(10, 100, 1);
                                   accept.setKeepAlive(true);
    
                                   DataInputStream _in = null;
                                   try
                                   {
                                           _in = new DataInputStream(new BufferedInputStream(accept.getInputStream(),1024));
                                   }
                                   catch (IOException e2)
                                   {
                                     e2.printStackTrace();
                                   }
    
                                   int method =_in.readInt();
    
                                   switch (method)
                                   {
                                     // notification
                                     case 1:
                                           doNotification(_in);
                                           break;
                                   }
                           }
                   }
                   catch (Throwable e)
                   {
                           e.printStackTrace();
                           Log.e(getClass().getSimpleName(), "Error in Listener",e);
                   }
    
                   try
                   {
                     ss.close();
                   }
                   catch (IOException e)
                   {
                     Log.e(getClass().getSimpleName(), "keep it simple");
                   }
           }
    
           },"Server thread");
         serverThread.start();
    
     }
    
     private void doNotification(DataInputStream in) throws IOException {
       String id = in.readUTF();
       displayNotification(id);
     }
    
     @Override
     public void onDestroy() {
             stopped=true;
             try {
                     ss.close();
             } catch (IOException e) {}
             serverThread.interrupt();
             try {
                     serverThread.join();
             } catch (InterruptedException e) {}
     }
    
     public void displayNotification(String notificationString)
     {
       int icon = R.drawable.mp_warning_32x32_n;
       CharSequence tickerText = notificationString;
       long when = System.currentTimeMillis();
       Context context = getApplicationContext();
       CharSequence contentTitle = notificationString;
       CharSequence contentText = "Hello World!";
    
       Intent notificationIntent = new Intent(this, MainApp.class);
       PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
    
       Notification notification = new Notification(icon, tickerText, when);
       notification.vibrate = new long[] {0,100,200,300};
    
       notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent);
    
       String ns = Context.NOTIFICATION_SERVICE;
       NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
    
       mNotificationManager.notify(1, notification);
     }
    
   }

   This service listens on port 12345. When it receives some data it checks if the first “int” sent is “1”. If so, it then creates a new notification using the next piece of data (a string) that is received over the socket.

6. Modify the MainApp Java class to start the service when the onCreate() method is called:

   	@Override
   	public void onCreate(Bundle savedInstanceState)
   	{
   		try
   		{
   			Intent srv = new Intent(this, TestService.class);
   			startService(srv);
   		}
   		catch (Exception e)
   		{
   			// service could not be started
   		}
    
   		super.onCreate(savedInstanceState);
   	}

   That is all you need to do in the Android application.

7. Next, create a Flex application that will connect to the socket and send the right data. Here is some sample code for my Notifier.mxml class, which I used to test the Android service:

   <?xml version="1.0" encoding="utf-8"?>
   <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
                          xmlns:s="library://ns.adobe.com/flex/spark">
    
     <fx:Style>
       @namespace s "library://ns.adobe.com/flex/spark";
    
       global {
         fontSize: 32;      
       }
     </fx:Style>
    
     <s:layout>
       <s:VerticalLayout horizontalAlign="center" paddingTop="20"/>
     </s:layout>
    
     <s:TextInput id="t" text="test test"/>
    
     <s:Button label="create notification">
       <s:click>
         <![CDATA[
           var s:Socket = new Socket();
           s.connect("localhost", 12345);
           s.addEventListener(Event.CONNECT, function(event:Event):void {
             trace('connected!');
             (event.currentTarget as Socket).writeInt(1);
             (event.currentTarget as Socket).writeUTF(t.text);
             (event.currentTarget as Socket).flush();
             (event.currentTarget as Socket).close();
           });
           s.addEventListener(IOErrorEvent.IO_ERROR, function(event:IOErrorEvent):void {
             trace('error! ' + event.errorID);
           });
           s.addEventListener(ProgressEvent.SOCKET_DATA, function(event:ProgressEvent):void {
             trace('progress ');
           });
         ]]>
       </s:click>
     </s:Button>
    
   </s:Application>

   As you can see there is just a TextInput control that allows the user to enter some text. Then when the user clicks the Button the AIR for Android application connects to a local socket on port 12345, writes an int with the value of 1, writes the string that the user typed into the TextInput control, and finally flushes and closes the connection. This causes the notification to be displayed.

8. Now simply compile the Flex app and overwrite the assets/app.swf file with the new Flex application. Check out a video demonstration of this code.

Widgets

Widgets in Android are the mini apps that can be displayed on the home screen of the device. There is a fairly limited amount of things that can be displayed in Widgets. So unfortunately Widgets can’t be built with AIR for Android. However a custom application Widget can be packaged with an AIR for Android application. To add a Widget to an AIR for Android application you can use the default AppEntry class instead of wrapping it with another class (MainApp in my example). (It doesn’t, however, do any harm to keep the MainApp class there.) To add a Widget simply add its definition to the AndroidManifest.xml file, create the Widget with Java, and create a corresponding layout resource.

1. First define the Widget in the application section of the AndroidManifest.xml file:

   <receiver android:name=".AndroidWidget" android:label="app">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data android:name="android.appwidget.provider" android:resource="@xml/airandroidwidget" />
   </receiver>

2. You need an XML resource that provides metadata about the widget. Simply create a new file named airandroidwidget.xml in a new res/xml directory with the following contents:

   <?xml version="1.0" encoding="utf-8"?>
   <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
       android:minWidth="294dp"
       android:minHeight="72dp"
       android:updatePeriodMillis="86400000"
       android:initialLayout="@layout/main">
   </appwidget-provider>

   This tells the widget to use the main layout resource as the initial layout for the widget.

3. Create a res/layout/main.xml file that contains a simple text display:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:id="@+id/widget"
       android:orientation="vertical"
       android:layout_width="fill_parent"
       android:layout_height="fill_parent"
       android:background="#ffffffff"
       >
   <TextView  
       android:layout_width="fill_parent" 
       android:layout_height="wrap_content" 
       android:text="hello"
       />
   </LinearLayout>

   Next, you’ll need to create the AppWidgetProvider class specified in the AndroidManifest.xml file.

4. Create a new Java class named AndroidWidget with the following contents:

   package com.jamesward;
    
   import android.app.PendingIntent;
   import android.appwidget.AppWidgetManager;
   import android.appwidget.AppWidgetProvider;
   import android.content.Context;
   import android.content.Intent;
   import android.widget.RemoteViews;
   import com.jamesward.MainApp;
    
   public class AndroidWidget extends AppWidgetProvider
   {
    
       public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds)
       {
           final int N = appWidgetIds.length;
    
           // Perform this loop procedure for each App Widget that belongs to this provider
           for (int i=0; i<N; i++)
           {
               int appWidgetId = appWidgetIds[i];
               Intent intent = new Intent(context, MainApp.class);
               intent.setAction(Intent.ACTION_MAIN);
               PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);
               RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.main);
               views.setOnClickPendingIntent(R.id.widget, pendingIntent);
               appWidgetManager.updateAppWidget(appWidgetId, views);
           }
       }
   }

   This class will display the Widget when necessary and register a click handler that will open the MainApp application when the user taps on the Widget.

5. Run the application to verify that it works.
6. Now you can add the widget to the home screen by holding down on the home screen and following the Widget wizard.
7. Verify that tapping the widget launches the AIR application.

Application Licensing

Android provides APIs to help you enforce licensing policies for non-free apps in the Android Market. You might want to go read up on Android Licensing before you give this one a try.

To add Application Licensing to you AIR for Android application you first need to follow the steps outlined in the Android documentation. The broad steps are as follows:

1. Set up an Android Market publisher account
2. Install the Market Licensing Package in the Android SDK
3. Create a new LVL Android Library Project in Eclipse
4. Add a Library reference in the Android project to the LVL Android Library
5. Add the CHECK_LICENSE permission to your Android project’s manifest file:

   <uses-permission android:name="com.android.vending.CHECK_LICENSE" />

After completing these set up steps, you are ready to update the MainApp Java class to handle validating the license:

package com.jamesward;
 
import com.android.vending.licensing.AESObfuscator;
import com.android.vending.licensing.LicenseChecker;
import com.android.vending.licensing.LicenseCheckerCallback;
import com.android.vending.licensing.ServerManagedPolicy;
 
import air.Foo.AppEntry;
import android.os.Bundle;
import android.os.Handler;
import android.provider.Settings.Secure;
 
public class MainApp extends AppEntry {
 
    private static final String BASE64_PUBLIC_KEY = "REPLACE WITH KEY FROM ANDROID MARKET PROFILE";
 
    // Generate your own 20 random bytes, and put them here.
    private static final byte[] SALT = new byte[] {
        -45, 12, 72, -31, -8, -122, 98, -24, 86, 47, -65, -47, 33, -99, -55, -64, -114, 39, -71, 47
    };
 
    private LicenseCheckerCallback mLicenseCheckerCallback;
    private LicenseChecker mChecker;
    private Handler mHandler;
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mHandler = new Handler();
        String deviceId = Secure.getString(getContentResolver(), Secure.ANDROID_ID);
        mLicenseCheckerCallback = new MyLicenseCheckerCallback();
        mChecker = new LicenseChecker(
            this, new ServerManagedPolicy(this,
                new AESObfuscator(SALT, getPackageName(), deviceId)),
            BASE64_PUBLIC_KEY);
        mChecker.checkAccess(mLicenseCheckerCallback);
    }
 
    private void displayFault() {
        mHandler.post(new Runnable() {
            public void run() {
                // Cover the screen with a messaging indicating there was a licensing problem
                setContentView(R.layout.main);
            }
        });
    }
 
    private class MyLicenseCheckerCallback implements LicenseCheckerCallback {
        public void allow() {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
            // Should allow user access.
        }
 
        public void dontAllow() {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
            displayFault();
        }
 
        public void applicationError(ApplicationErrorCode errorCode) {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
        }
    }
 
    @Override
    protected void onDestroy() {
        super.onDestroy();
        mChecker.onDestroy();
    }
}

Also add the following to a new res/layout/main.xml file in order to display an error when the license is denied:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
 
  <TextView  
    android:layout_width="fill_parent" 
    android:layout_height="wrap_content" 
    android:text="@string/license_problem"
    />
 
</LinearLayout>

The text to display uses a string resource named “license_problem”, which must be added to the res/values/strings.xml file:

<string name="license_problem">THERE WAS A PROBLEM LICENSING YOUR APPLICATION!</string>

When the application runs it will check for a valid license. If the license comes back as valid then the AIR application will start and run as usual. However, if there is an invalid license then the application will set the ContentView to the R.layout.main resource, which displays the error message defined in the “license_problem” resource. To simulate different responses you can change the “Test Response” in your Android Market profile.

The Gory Details
I’ve wrapped up a generated AppEntry class and its resources to make the process of extending AIR for Android fairly easy. If you are interested in seeing how that is done, I’ve posted all of the source code on github.

Here is an overview of the procedure:

1. Use the AIR SDK to create an AIR for Android APK file.
2. Use the dex2jar utility to convert the AppEntry dex classes into a JAR file.
3. Pull the resource classes out of the JAR file so that they don’t conflict with the new resources.
4. Use apktool to extract the original resources out of the AIR for Android APK file.
5. Create a single ZIP file containing the airbootstap.jar file, resources, AndroidManifest.xml file, and assets.

Now you can simply copy and paste those dependencies into your Android project.

Conclusion
Hopefully this article has helped you to better understand how you can extend AIR for Android applications with Android APIs. There are still a number of areas where this method can be improved. For instance, I am currently working with the Merapi Project developers to get Merapi working with my method of extending AIR for Android. That will provide a better bridging technique for communicating between the AIR application and Android APIs. So stay tuned for more information about that. And let me know if you have any questions!

Very fun stuff! Let me know what you think.

• AS34J – ActionScript for Java Developers
• Rapid Mobile & Tablet App Development with Spring and Flex

On March 22, 2011 at the Atlanta Flex User Group I will be presenting about Flex 4.5 – The Non-Mobile New Features.

I hope to see you at DevNexus and at the Atlanta Flex User Group!

Here is the abstract for the talk:
Today, users want apps in the browser, on their desktop, phone, tablet, and TV. Reusing code across all of these devices is now crucial for developers. By combining Flex for the UI with Spring and Hibernate for the back-end, developers can build apps that work on a variety of devices including PCs, Android phones / tablets, the BlackBerry PlayBook tablet, iPhones, and iPads. This session will walk developers through the steps for creating these cross-device apps with Flex and Java.

Go register now! See you there! :)

Grab the code for the demos in the video from github:

• P2Pong
• P2Hancock (Signature capture over P2P)

Just as the video shows, it’s incredibly easy to use the P2P APIs. Here is a quick walk through. First create a new NetConnection that is connected to “rtmfp:” like so:

localNc = new NetConnection();
localNc.addEventListener(NetStatusEvent.NET_STATUS, netStatus);
localNc.connect("rtmfp:");

In the netStatus event listener wait for the “NetConnection.Connect.Success” event and then set up the NetGroup:

private function netStatus(event:NetStatusEvent):void
{                        
    switch(event.info.code)
    {
        case "NetConnection.Connect.Success":
            setupGroup();
            break;
    }
}
 
private function setupGroup():void
{
    var groupspec:GroupSpecifier = new GroupSpecifier(GROUP_ID);
    groupspec.ipMulticastMemberUpdatesEnabled = true;
    groupspec.multicastEnabled = true;
    groupspec.routingEnabled = true;
    groupspec.postingEnabled = true;
 
    // This is a multicast IP address. More info: http://en.wikipedia.org/wiki/Multicast_address
    groupspec.addIPMulticastAddress("239.254.254.2:30304");
 
    netGroup = new NetGroup(localNc, groupspec.groupspecWithAuthorizations());
    netGroup.addEventListener(NetStatusEvent.NET_STATUS, netStatus);
}

Now handle a “NetGroup.SendTo.Notify” event when a message is received over the P2P connection:

// in the netStatus switch block
case "NetGroup.SendTo.Notify":
    var data:Object = event.info.message;
    break;

And finally to send a P2P message to everyone who is listening simply do:

netGroup.sendToAllNeighbors(objectToSend);

That’s it! Super simple and super fun! :)

Thanks to Tom Krcha for all of his great blogs on how to do this. Also thanks to Mark Dong and James Li (Flash Platform Evangelists in China) for helping me build P2Pong.

Download the Tour de Mobile Flex Flash Builder Project (FXP) or get the code from github. And let me know what you think!

UPDATE: To compile the latest code on github you will need the latest private prerelease of Flash Builder. You can get more information about the private prerelease on the Flex Team Blog.

But no one wants to go back to the Client / Server architecture. We want to embrace Cloud Computing architectures but not lose the client capabilities. What we really need is the Client / Cloud architecture. We need a web deployment model that provides ease of deployment but also the ability to install applications on our desktops and mobile devices.

This is why I’m so excited about the new Adobe Flash Builder for Force.com. In a nutshell this is a tool that Adobe and Salesforce.com built together to enable developers to build great software using Flex for the UI and Force.com for the Cloud back-end. It’s a wonderful combination of technologies that will help many Client / Server apps make the switch to Client / Cloud.

Applications created with Flash Builder for Force.com can be run in the browser, on the desktop, and on mobile devices. These applications can be assembled from the hundreds of Flex components that are out there (check out many of them in Tour de Flex).

Check out this video to see how to use Flash Builder for Force.com to build a simple app:

As you can see, it’s very easy to get started. But I wanted to go a step further and try to build something real–something that shows a genuine use case for extending beyond the out-of-the-box Salesforce.com UI. I wanted to keep it really simple so that I could post the code here. What I came up with is this (in user story form):

• As a Salesforce.com user I want to take a photo, using my phone, of one of my contacts so that the photo can be saved to their contact record for future reference.
• As a Salesforce.com user I want to see photos I’ve taken of my contacts so that I can be reminded of what they look like.

Simple enough. So here is what I came up with:

To build these two apps I first downloaded and installed Flash Builder for Force.com. I used the Adobe AIR for Android prerelease to build the mobile app. Here is how I created these apps.

First I added a new field to Contact to store the photo. Salesforce.com doesn’t have a binary field so I used a large text field (32k limit). I’ll store the photo Base64 encoded.

Then in Salesforce.com I saved my enterprise.wsdl file. Check out a great video from Dave Carroll to see how to do this.

Now in Flash Builder for Force.com I created a new Force.com Flex Project for the mobile app. If you do this on your own and want to run on a mobile device then you will need to overlay the AIR for Android SDK on top of a Flex 4.1 SDK. Select Desktop Application as the app type. Replace WindowedApplication with just Application. And replace the F3DesktopApplication with F3WebApplication since F3DesktopApplication uses APIs that are not available on AIR for Android. (BTW: Flash Builder, Flex, and Force.com Flex Projects do not officially support mobile deployment yet. It works but there is no support and no guarantees.) If you are building a standard Web Application or Desktop Application then you can just leave the generated code as is.

Using the Data/Services wizard I connected to Salesforce.com using my enterprise.wsdl file. After the services and value objects have been generated I modified the Contact object and added a Bindable account property. The generated application already included the F3DesktopApplication Declaration used to connect to Salesforce. Due to an incompatibility with that API and AIR for Android I switched it to use F3WebApplication. In F3WebApplication’s loginComplete event handler I query Salesforce.com for Accounts and then Contacts, associate contacts with their account, and then store the contacts:

app.wrapper.query("select Id, Name from Account", new AsyncResponder(function(data:ArrayCollection, token:Object):void {
    accounts = data;
    app.wrapper.query("select Id, AccountId, FirstName, LastName, Phone, MobilePhone, Email, Title, Department, MailingCity, photoData__c from Contact", new AsyncResponder(function(data:ArrayCollection, token:Object):void {
        for each (var contact:Contact in data)
        {
            for each (var account:Account in accounts)
            {
                if (account.Id == contact.AccountId)
                {
                    contact.account = account;						
                }
            }
        }
        contacts = data;
    }, handleError));
}, handleError));

Notice in the query that I’m fetching photoData__c, which is the custom field I created on Contact to store the photo.

In the renderer for a contact I need to either display the photo if there is one or let the user add one. Here is the simple UI code to handle that:

<s:Group width="92" height="92" top="8" right="8">
    <s:Rect width="92" height="92">
        <s:fill>
            <s:SolidColor color="#cccccc"/>
        </s:fill>
    </s:Rect>
    <s:Label id="addPhoto" text="Add a photo" width="92" height="92" verticalAlign="middle" textAlign="center"/>
    <s:BitmapImage id="photo" width="92" height="92"/>
</s:Group>

When the contact is set I check to see if there is a photo and if so display it:

if (contact.photoData__c == null)
{
    photo.visible = false;
    return;
}
 
var decoder:Base64Decoder = new Base64Decoder();
decoder.decode(contact.photoData__c);
 
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, function(event:Event):void {
    photo.source = event.target.content;
    photo.visible = true;
});
loader.loadBytes(decoder.toByteArray());

The data from the photoData__c field is Base64 decoded and then displayed using the Flex BitmapImage component.

Now when the user clicks on the photo or empty photo box I use the AIR for Android CameraUI to grab a photo, resize it, covert it to a PNG, Base64 encode it, set it on the contact, and then save the contact to Salesforce.com:

if (CameraUI.isSupported)
{
    cameraUI = new CameraUI();
    cameraUI.addEventListener(MediaEvent.COMPLETE, function(event:MediaEvent):void {
        var loader:Loader = new Loader();
        loader.load(new URLRequest(event.data.file.url));
        loader.contentLoaderInfo.addEventListener(Event.COMPLETE, function(event:Event):void {
            var bitmap:Bitmap = event.target.content as Bitmap;
 
            var result:BitmapData = new BitmapData(46, 46, false);
            var matrix:Matrix = new Matrix();
            matrix.scale(46 / bitmap.width, 46 / bitmap.height);
            result.draw(bitmap, matrix);
 
            var pngEncoder:PNGEncoder = new PNGEncoder();
            var pngBytes:ByteArray = pngEncoder.encode(result);
 
            var base64Encoder:Base64Encoder = new Base64Encoder();
            base64Encoder.encodeBytes(pngBytes);
            var encodedImage:String = base64Encoder.flush();
 
            contact.photoData__c = encodedImage;
 
            displayPhoto();
 
            F3WebApplication.getInstance().wrapper.save(contact, new AsyncResponder(function(data:Object, token:Object=null):void {
            }, FlexGlobals.topLevelApplication.handleError));
        });
    });
    cameraUI.addEventListener(ErrorEvent.ERROR, function(event:ErrorEvent):void {
        FlexGlobals.topLevelApplication.handleError(event);
    });
    cameraUI.launch(MediaType.IMAGE);
}

That’s it for the mobile app! I compiled it, exported it to an Android app, and then copied it to my phone. Pretty simple and as you can see it works! One limitation with my approach is the 32k limit of the photoData__c field. However, I think I could easily get around that by striping the Base64 encoded data across multiple fields. It’s not ideal but it would work.

To display the photo when I view a contact on Salesforce.com I created a very simple Flex app using another Force.com Flex Project. I could have also added photo upload to this application but chose to keep it simple. All it does is display the selected contact’s photo. Here is the complete code (after generating the required services in Flash Builder):

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:mx="library://ns.adobe.com/flex/mx"
    xmlns:flexforforce="http://flexforforce.salesforce.com">
 
    <fx:Script>		
    import mx.rpc.AsyncResponder;
    import mx.utils.Base64Decoder;
    </fx:Script>
 
    <fx:Declarations>
        <flexforforce:F3WebApplication id="app" requiredTypes="Contact">
            <flexforforce:loginComplete>
                app.wrapper.query("select photoData__c from Contact where Id = '" + this.parameters.contactId + "'", new AsyncResponder(function(data:Object, token:Object):void {
                    if (data.length == 1)
                    {
                        if (data[0].photoData__c == null)
                        {
                            photo.visible = false;
                            noPhoto.visible = true;
                            return;
                        }
 
                        var decoder:Base64Decoder = new Base64Decoder();
                        decoder.decode(data[0].photoData__c);
 
                        var loader:Loader = new Loader();
                        loader.contentLoaderInfo.addEventListener(Event.COMPLETE, function(event:Event):void {
                            photo.source = event.target.content;
                            photo.visible = true;
                        });
                        loader.loadBytes(decoder.toByteArray());
                    }
                }, function(fault:Object):void {
                    // ignored
                }));
            </flexforforce:loginComplete>
        </flexforforce:F3WebApplication>
    </fx:Declarations>
 
    <s:applicationComplete>
        app.serverUrl = this.parameters.serverUrl;
        app.loginBySessionId(this.parameters.sessionId);
    </s:applicationComplete>
 
    <s:Rect width="92" height="92">
        <s:fill>
            <s:SolidColor color="#cccccc"/>
        </s:fill>
    </s:Rect>
 
    <s:Label id="noPhoto" text="No Photo" width="92" height="92" textAlign="center" verticalAlign="middle" visible="false"/>
 
    <s:BitmapImage id="photo" width="92" height="92"/>
 
</s:Application>

Finally I created a custom S-Control to run the Flex app:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="ContactPhoto" width="92" height="92" 
codebase="https://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab"> 
    <param name="movie" value="{!Scontrol.JavaArchive}" /> 
    <param name="flashvars" value="sessionId={!API.Session_ID}&serverUrl={!API.Partner_Server_URL_90}&contactId={!Contact.Id}" /> 
    <embed src="{!Scontrol.JavaArchive}" width="92" height="92" name="ContactPhoto" 
flashvars="sessionId={!API.Session_ID}&serverUrl={!API.Partner_Server_URL_90}&contactId={!Contact.Id}" 
type="application/x-shockwave-flash" 
pluginspage="http://www.adobe.com/go/getflashplayer"> 
    </embed> 
</object>

I uploaded the compiled Flex app to the S-Control and added it to the Contact page. And that’s it! In just a few hours I extended Force.com and built a cool mobile app. I could also have easily created a desktop widget for browsing contacts and adding photos. If you are looking for a fun project to use as a way to learn this stuff that would be a good one! :)

Here are some resources to help you get started with Flash Builder for Force.com:

• Force.com Flex Quick Start Tutorial
• Force.com Flex Project APIs for Web Applications
• Force.com Flex Project APIs for Desktop Applications
• Numerous other demo applications and tutorials
• Source code for my mobile contacts demo
• Source code for my web contact photo viewer demo

Have fun building the next generation of software! Let me know how it goes.