LimeLM
wyBuild
Support forum
wyDay blog
wyDay Home

Using TurboActivate with Adobe AIR

Adobe AIRThis article will give step-by-step instructions on how to add software licensing (specifically, hardware-locked or node-locked licensing) to your Adobe AIR app. There's also a full example app that you can download and play with without needing to add licensing to your app.

By the end of this article you'll have working licensing integrated with your application, and thus the ability to sell individual copies of your software.

Sign up or login and download the native TurboActivate library

Before you can do anything, you need to login to your LimeLM account (or sign up). Then download TurboActivate for Windows, macOS (Mac OS X), or Linux. It contains the native library and source code examples needed to integrate hardware-locked licensing in your app:

Step-by-step walkthrough

We're going to walk you through each step you need to take in adding licensing, online activation, and timed-trials to your Adobe AIR app. There are lots of ways you can add licensing to your app, but there are 2 popular styles:

  1. Separate versions of your app. This style of licensing is where you build 2 versions of your product: a trial version and a full version.
  2. Hybrid version of your app. This style of licensing is where your product is the trial version or the full version depending on whether the user is activated.

The first method (the separate versions method) is possible with TurboActivate, but we're not going to talk about it here because it's not very user friendly. Instead we'll talk about making your app a hybrid Full/Trial app. That is, your users will be able to use your app in "trial mode" until either the trial expires or they purchase a product key and use it to activate your app.

Step 1. Signup for LimeLM, download TurboActivate

If you haven't already signed up for LimeLM then sign up now. All plans have a 30-day free trial. Or, if you're just putting your toes in the water, there's even a free plan that has no time limit and doesn't require a credit card.

After you've created your account download TurboActivate for Windows, Mac OS X, or Linux (or all 3 if you'll be releasing your app for all platforms). Once downloaded, extract them anywhere. Inside you'll find an "API" folder which contains a full Adobe AIR example.

Step 2. Add TurboActivate to your project

Adding TurboActivate to your product involves a few steps.

TurboActivate.as and TurboActivateEvent.as files

Copy the "TurboActivate.as" and "TurboActivateEvent.as" files from the "API/Adobe AIR/src" folder you extracted earlier. You can copy these files to your app's "src" folder.

Copy the "Mac", "Windows", or "Linux" folders

Now you need to copy the folder that inside the extracted "API/Adobe AIR/bin-debug" folder. That is, for the Windows version of TurboActivate you copy the "Windows" folder from inside the example project's "bin-debug" folder to your own "bin-debug" folder. For Mac OS X, copy the "Mac" folder, and for Linux copy the "Linux" folder.

Inside the folder you copied is a "systa" (or "systa.exe") file and a text file.

TurboActivate.dll, libTurboActivate.dylib, or libTurboActivate.so

Now you need to copy the TurboActivate library into the "Windows", "Mac", or "Linux" folder you just copied.

Step 3. Create a new product in LimeLM

If you haven't already created a new product in LimeLM, do it now. You can change any value later, so don't worry about making a mistake.

Adding your first product to LimeLM

Step 4. Download TurboActivate.datTurboActivate.dat and Version GUID

Go to your version page in LimeLM. Download the "TurboActivate.dat" file. Now copy this file to the "Windows", "Mac", or "Linux" folders you just copied moments ago. For instance, if you're programming on Windows, your "Windows" folder inside your "bin-debug" folder will contain:

  1. systa.exe
  2. TurboActivate.dat
  3. TurboActivate.dll

Step 5. Modify the Application Descriptor File

Since TurboActivate runs natively on the operating system, you need to make a small change to your AIR app's "Application Descriptor File" (e.g. ProductName-app.xml). Add the following line anywhere inside the <application> block:

<supportedProfiles>extendedDesktop</supportedProfiles>

Step 6. init() function, TurboActivate class, Version GUID

The first order of business is to add an "init()" function to your "WindowedApplication". First add an "applicationComplete" event handler:

<mx:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
                        xmlns:mx="library://ns.adobe.com/flex/mx"
                        applicationComplete="init()"
...

Then add the "init()" function to the script part of your *.mxml file:

<fx:Script>
    <![CDATA
        public function init():void
        {

        }
    ]]>
</fx:Script>

Now we can add a TurboActivate class to your code. This is the class that gives your app full control over all licensing, activation, and timed trial functions:

private var ta:TurboActivate = new TurboActivate("Paste GUID Here");

public function init():void
{

}

Replace the "Paste GUID Here" string with the Version GUID string your copied from your version page.

Before you continue, run your app. Your app should run just as it had before (because you haven't added the licensing code yet). If you get an error, read the error message carefully and fix it. Common errors include forgetting to add the "Windows", "Mac", or "Linux" folder to your "bin-debug" folder, or forgetting to add the <supportedProfiles> element to your application descriptor file.

Step 7. Adding licensing functionality

Now that you've included all the needed TurboActivate files with your app, you can start using the licensing. The code example will follow the example app included in the "API/Adobe AIR" folder you extracted earlier:

Example AIR app

The example AIR app demonstrates using activation, deactivation, timed-trials, and trial extensions. Now I'll explain in detail how to use these TurboActivate functions.

The first thing you'll need to add to your app is event handlers for 3 functions. Add the event handler in the "init()" function you created earlier:

public function init():void
{
    // these are TurboActivate event handlers that will be used at
    // both the start of your program and throughout the use of your program
    ta.addEventListener(TurboActivateEvent.IS_GENUINE_EX, onIsGenuineEx);
    ta.addEventListener(TurboActivateEvent.USE_TRIAL, onUseTrial);
    ta.addEventListener(TurboActivateEvent.TRIAL_DAYS_REMAINING, onTrialDaysRemaining);
}

private function onIsGenuineEx(evt:TurboActivateEvent):void
{

}

private function onUseTrial(evt:TurboActivateEvent):void
{

}

private function onTrialDaysRemaining(evt:TurboActivateEvent):void
{

}

Before I continue let me explain how functions are processed by TurboActivate. Due to the way Adobe AIR is designed function calls to TurboActivate are asynchronous to the response. That is, instead of getting the returned response immediately, instead an event is called a few milliseconds after you make a call.

Let's take the "IsGenuineEx()" function as an example. When you call "ta.IsGenuineEx(...)" the event listener for "TurboActivateEvent.IS_GENUINE_EX" is called. So, if you declare the event listener "onIsGenuineEx" like the code above, the function would be written like this:

public function init():void
{
...
    ta.addEventListener(TurboActivateEvent.IS_GENUINE_EX, onIsGenuineEx);
...
    // Check if we're activated, and every 90 days verify it with
    // the activation servers. In this example we won't show an
    // error if the activation was done offline
    // (see the 3rd parameter of the IsGenuine() function)

    ta.IsGenuineEx(90, 14, true);
}

private function onIsGenuineEx(evt:TurboActivateEvent):void
{
    if (evt.ErrorObj == null)
    {
        isActivated = evt.uintResponse == TurboActivate.IGRet_Genuine ||
            evt.uintResponse == TurboActivate.IGRet_GenuineFeaturesChanged ||

            // an internet error means the user is activated but
            // TurboActivate failed to contact the LimeLM servers
            evt.uintResponse == TurboActivate.IGRet_InternetError;

        if (evt.uintResponse == TurboActivate.IGRet_InternetError)
        {
            //TODO: give the user the option to retry the genuine checking
            //      immediately. For example a dialog box. In the dialog
            //      call IsGenuine() to retry immediately.
        }

        if (isActivated)
        {
            // is activated, reenable any features
            EndLicensingCheck();
        }
        else
        {
            // not activated, disable any app features
            ta.UseTrial();
        }
    }
    else
    {
        // the function call failed, disable any features
        isActivated = false;
        EndLicensingCheck();

        // in a real world app don't throw exceptions.
        // This is for debugging only
        throw evt.ErrorObj;
    }
}

I encourage you to look at the example project in the "API/Adobe AIR" folder. Change the "VersionGUID" to your VersionGUID and run the app. Play with the buttons so you understand how you can use licensing and timed trials in your app. You can take the "TrialExtension" and "PKey" windows and include them with your app if you wish:

Example AIR app

Step 8. Packaging your Adobe AIR app

After you've added the licensing to your app, and you're ready to release your app to your user, you need to build your native installer. I'm going to show you how to do this using Adobe Flash Builder on Windows and Mac OS X. If you want to build a native installer on Linux (.deb or .rpm), or you're more comfortable using the AIR Developer Tool (ADT) then see the article "Packaging a desktop native installer".

Copy the Windows or Mac folders

In "Step 2" you added the "Windows" or "Mac" folders to your "bin-debug" folder. Now you can copy this folder ("Windows" or "Mac") to your "src" folder.

Export Release Build

Now you're ready to build the native installer for Mac OS X and/or Windows. First, click the "Project -> Export Release Build..." menu in Adobe Flash Builder:

Export Release Build... menu

Select "Export to native installer"

Click the "Export native installer" radio button. This will allow you to export a .dmg file on Mac, and an .exe on Windows:

Export native installer

Digitally sign the AIR app

After clicking the next button you'll be asked to sign your AIR application. Either using an existing certificate or click the "Create..." button to create a new one:

Sign your AIR app

Verify AIR Application Contents

After clicking the next button you'll come to a page where you verify what files will be included in the native installer. In Windows make sure the "Windows" folder along with the "TurboActivate.dll", "TurboActivate.dat", and the "systa.exe" files are checked:

AIR application contents (Windows)

Similarly, in Mac OS X make sure the "Mac" folder along with the "libTurboActivate.dylib", "TurboActivate.dat", and the "systa" files are checked:

AIR application contents (Mac OS X)

Then click "Finish" to make the installer.

Note: If you didn't see the "Windows" folder or "Mac" folder (depending on your platform), make sure you copied that folder into the "src" folder from the "bin-debug" folder.

Common error on Linux & Mac OS X — "The NativeProcess could not be started."

If you get the exception "The NativeProcess could not be started." when you run your Adobe AIR app on either Linux or Mac OS X the most common cause is that the "systa" file does not have executable permission. You can verify this by opening a terminal and navigating to the folder that contains the "sysa" file, "TurboActivate.dat" file, and the "libTurboActivate.dylib" or "libTurboActivate.so" file depending on whether you're on Mac or Linux:

cd /path/to/your/app

Then type "ls -l" in terminal and press enter. You'll see a list of permissions for every file in the directory:

...
-rwxr-xr-x  1 wyatt  staff    26396 Mar 21 02:18 systa
...

The "systa" file should have 3 "x" (executable) permissions. If it does not then you should type "chmod a+x systa" in terminal and press enter. Then type "ls -l" in terminal and press enter to confirm the "systa" file now has executable permission. Now when you run your app and build your native installer everything will work.

About  ·  Careers  ·  Contact us  ·  Privacy  ·  Site Map
© 2023 wyDay