AIR Tip 5 - Passing Arguments to an Application on Install

January 10th, 2008

AIR Tip 5: This tutorial will walk you through the process of passing arguments to an AIR application when it is installed using the AIR installer badge. It includes both an article as well as a demonstration video. This tutorial is current for Adobe AIR Beta 3.

Someone left a comment today asking if it was possible to send arguments to an application when it is installed via the AIR Installer Badge. The answer: yes and no. First, it cannot be done through the default badge that comes with the SDK. However, the badge can easily be modified to perform this. Second, for an AIR application to receive the BrowserInvokeEvent [Reference], the allowBrowserInvocation property in the application descriptor file must be set to true.

Modifying the AIR Install Badge

Assuming this is true, you should go ahead and create a modified AIR Install Badge. The source code for the badge comes with the Adobe AIR Beta 3 SDK. It can be found in the src/badge folder. You will need to edit the AIRBadge.as file in three places.

1. You will need to add a property to this class called _arguments. The properties are at the bottom of this class, so add your property declaration after the others. This property will be an array.
   PLAIN TEXT
   ACTIONSCRIPT:

   1. ...
   2. private var _messageColor: String;
   3. private var _buttonColor: String;
   4. private var _imageURL: String;
   5. private var _appURL: String;
   6. private var _appName: String;
   7. private var _airVersion: String;
   8. private var _arguments: Array;
   9. ...

   Code Example 1 - Creating the _arguments Property

    

2. Next, you will need to assign the arguments passed into the SWF file to the _arguments property. This is done in the constructor. You will need to take this String [Reference] that will be passed in and split it into an Array [Reference]. You can accomplish this with the split method of the String class. In this case, you can use the comma as a delimiter for the Array.
   PLAIN TEXT
   ACTIONSCRIPT:

   1. ...
   2. _imageURL = validateURL(parameters["imageurl"]);
   3. _airVersion = String(parameters["airversion"]);
   4. _appURL = validateURL(parameters["appurl"]);
   5. _arguments = String(parameters["arguments"]).split(",");
   6. ...

   Code Example 2 - Populating the _arguments Property with an Array of Arguments

    

3. Finally, you will need to pass the _arguments property as the third argument in the _air.installApplication method. This method is called twice in the switch statement that is in the onButtonClicked method. You will need to update both locations.
   PLAIN TEXT
   ACTIONSCRIPT:

   1. ...
   2. _air.installApplication( _appURL, _airVersion, _arguments );
   3. ...

   Code Example 3 - Passing the _arguments Array to the AIR Installer

With these changes, you can now pass an arguments parameter into the badge installer, and it will pass those arguments to your AIR application on installation. As an example of this, I have created an AIR application that will display all of the arguments passed to it as a list. It also displays the other properties of the BrowserInvokeEvent.

For the installation, I modified my InstallBadge.js file to also include a property for the arguments (and also to pass those arguments in with the flashvars). For this example I have created a ColdFusion file which passed the IP Address and Server Name into the application as arguments.

The sample AIR application lists all properties of the BrowserInvokeEvent as well as a list of all of the arguments passed into it. You can see an example below (with the IP address and Server Name blurred).

Inserting the Modified Badge into a Site

I recently wrote an article for the Adobe AIR Develop Center entitled Deploying Adobe AIR applications seamlessly with the badge install feature. This article covers the entire process of inserting the badge onto a page. I have only modified these files slightly for this example (to add the arguments feature).

First, I have modified the InstallBadge.js file, and I have included the new version with the exercise file for this tutorial. Second, I added a new global variable (airApplicationArguments) to the head of the HTML page. This is a comma delimited list of arguments to pass to

Code Example 3 - Additional Global JavaScript Variable

Setting Up Your AIR Application

There are two settings that need to be considered when setting up your AIR application to receive BrowserInvokeEvents. First, you will need to modify your application descriptor file to allow your application to receive these events. Be sure that the allowBrowserInvocation option in your application descriptor file is set to true.

Code Example 4 - Allowing Browser Invocation for an AIR Application

Second, you will tell your application to listen for these events. This should be added as follows:

Code Example 4 - Adding Event Listener for BrowserInvokeEvents

Sample Application

The sample AIR application for this tutorial (as seen in the video) is available. It displays all of the information sent to it in a BrowserInvokeEvent. This application also has "View Source" enabled, so you can right-click it and view the actual code.

Video (Click to View)

Exercise Files
Install AIR Application - Click Here
Exercise Files (636 kb)

Reference
Livedocs - BrowserInvokeEvent
Developer Center - Deploying Adobe AIR applications seamlessly with the badge install feature
Developer Guide - Launching an Installed AIR Application from the Browser

AIR | Comments | Trackback | Del.icio.us | Digg | Technorati