This page is an archive of my old blog. Please visit DavidTucker.net for my current blog.
This site is no longer being maintained and commenting is disabled.

AIR Tip 5 – Passing Arguments to an Application on Install

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.
    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.
    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.
    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

JAVASCRIPT:
  1. // AIR Application Arguments
  2. var airApplicationArguments = "First Argument,Second Argument";

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.

XML:
  1. <!-- Whether the application can be launched when the user clicks a link in a web browser.
  2. Optional. Default false. -->
  3. <allowBrowserInvocation>true</allowBrowserInvocation>

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:

ACTIONSCRIPT:
  1. import flash.events.BrowserInvokeEvent;
  2. private function init():void {
  3.     NativeApplication.nativeApplication.addEventListener(BrowserInvokeEvent.BROWSER_INVOKE,onBrowserInvoke);
  4. }
  5. private function onBrowserInvoke(e:BrowserInvokeEvent):void {
  6.     // Code to React to BrowserInvokeEvent
  7. }

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




20 Responses to “AIR Tip 5 – Passing Arguments to an Application on Install”

  1. [...] AIR Tip 5: Passing Arguments to an Application on Install (AIR 1.0) [...]

  2. [...] Browser API that has been covered in AIR Tip 5 and AIR Tip 6 allows you not only to launch an AIR application from the browser, but also from [...]

  3. [...] 来源:AIR Tip 5: Passing Arguments to an Application on Install [...]

  4. randy says:

    I hit a bottleneck when using the flashvars arguments parameter to pass ip address from javascript.

    As per the docs , to send arguments to the swf file , one can use the arguments parameter of the flashvars variable. If there any special characters as part of the variable value % and hexadecimal value should be used.

    I have to pass for example the the following two values are parameters

    172.1.12.25:8080/test1
    172.1.13.26:8080/test2

    I have created the argument values as
    var airApplicationArguments = “172 %2E 12 %2E 25%3A 8080%2F abc,
    172 %2E 13 %2E 26%3A 8080%2F efd&
    “;

    I get a invalid argument error.

    Iam not sure what could be issue .Can u point me to the right direction. How did create the value for arguments variable ?

    Where there any encoding involved ?

  5. David Tucker says:

    @randy – Since the Browser API is used to send the arguments – the Browser API determines what values are acceptable arguments. With AIR 1.0 the browser API changed a bit – and it only allows alpha-numeric values (no symbols). I haven’t had a chance to update this tutorial yet.

  6. randy says:

    Yes you are right. Iam apprehensive about the Browser API , since it breaks the application from working , when it does changes like the alpha-numerics only. The best example is your tutorial , which is failing because of the changes .

  7. Rémi says:

    Hello david,

    Does this feature work if i click “save” instead of “install” ???

    Anyways, thanks for all your tips. :)

  8. David Tucker says:

    @Remi – I don’t believe that it would, but I haven’t tested it.

  9. Rémi says:

    So, this feature will be useless… :(

    I’ve to try. ^-^

  10. Lisa says:

    Do you know if there is a similar approach that can be utilized with sidecar installations on CD/DVD?

  11. Ricardinho says:

    “Does this feature work if i click “save” instead of “install” ???”

    If it doesn’t is there a way to simply remove the option to “save” the document and only allow for it to be directly installed?

  12. Hi says:

    IS it possible for having an input box at install time which will take one time input parameters and store them in the application.
    The type of application will be normal AIR application without the Browser invoke event.

  13. ryan says:

    yup i second what mr. “Hi” said…

    Specificly is there a way to use this feature to store sensetive service data into the EncryptedLocalStore during installation?

    Has anybody tried that yet?

  14. Elie says:

    Hi David, it’s a great tutorial :)

    I have a question concerning dynamically passing parameter.

    I have a list where the user can select from it. i need to pass the user selection to air application via the seamless badge.

    Is it posible to do it?

    Thanks a lot
    -Elie

  15. Jonathan Blackburn says:

    Hi David,

    I’d like to follow up on Ricardinho’s question. Passing custom params on a browser install is all well and good, but the “Save” button on the install screen doesn’t pass anything in – it’s a direct download.

    I have an app that is dependent on custom parameters that in-turn form queries to load custom data that is then stored on a user’s system. I need to be able to remove the “Save” button from the install screen. How can I accomplish this?

    Thanks.

  16. Dan Bucholtz says:

    Hi – I’m confused as to how this works.

    I’ve followed your tutorial yet the BrowserInvokeEvent does not seem to be invoked.

    This is the application compiled into the .air app. On the preInitialize event, I do the following code:

    private function initResources():void{
    NativeApplication.nativeApplication.addEventListener(BrowserInvokeEvent.BROWSER_INVOKE, onInvokeEvent);
    Swiz.loadBeans( [Beans] );
    }

    As you can see, I subscribe to the event and prepare my swiz framework beans. That’s all.

    Having said that, the listener is never called. I have the following code in place to debug and see what data I’d be receiving from the flashvars.

    private function onInvokeEvent(invocation:BrowserInvokeEvent):void {
    Alert.show(“BrowserInvokeEvent handler”);
    var arguments:Array = invocation.arguments;
    for each ( var object in arguments ){
    Alert.show(“argument is ” + object + ” or ” + object.data );
    }
    }

    Am I missing a step such as recompiling the Badge.swf with the new contents of AIRBadge.as ?

    Thanks in advance, I’m very stumped by this. Any guidance will be appreciated.

    Dan

  17. luca says:

    After having modified the AIRBadge.as file, how do I build the .SWF file?

    Unfortunally all the articles that I found, do not explain this last passage.

  18. This really is my fourth visit your website. I discovered so many fascinating issues in your blog especially its dialogue. I assume I’m not the only one enjoying it! Keep up the good operate.

  19. greno says:

    Just tried downloading this AIR application and it says: Invalid argument IP XX.XX.XX.XX

    How do you download this app?

  20. greno says:

    After a lot of tinkering it looks like you cannot make any argument be an IP, URL or a FilePath.

    So what good are arguments then?

    Next, after changing the arguments to something trivial like test,test2 I was able to get the installer code to begin but then ran into another problem.

    I have AIR 2.5 already installed and this app installer refused to continue with this error:
    ==========================
    Application Install Window
    ==========================
    Sorry, an error has occurred.

    This application requires an update to Adobe AIR that is not
    available for your system.

    Please view the system requirements for Adobe AIR and
    update your system accordingly.

    Close Button
    ==========================

    Time to give up on this exercise…