The road to 2.4

If you were to dig through our platform release notes you’d notice that it’s been nearly 18 months since the last major version number update to the platform.

During this time we’ve released 16 minor platform updates to help you navigate through:

  • Two major iOS software and hardware releases.
  • Support for writing custom native modules using the Swift programming language.
  • Four major Android API releases.
  • Beta support for Intel’s Crosswalk web runtime.
  • More App Store rule changes than anyone (including Apple) keeps track of.

I’ll be honest, surfing this tsunami of change isn’t always fun but once in a while I’ll come across something that reminds me of the value of what we do:


I don’t want to get into a rant about the kind of thinking responsible for this state of affairs but I would like to place it in perspective:

If, twenty years ago, you compiled a C/C++ application for the Windows WIN32 API using C/C++ there is every chance that your original binary executable will still work on Microsoft’s latest Windows 10 release.

Binary compatibility is unfortunately out of our reach and it’s still too early to tell if Trigger.IO will match Microsoft’s track record but we’re certainly giving it the old college try.

Simply put:

If you shipped a HTML/CSS/JS Trigger.IO app in 2012 chances are very, very good that it will still run on the latest versions of iOS and Android without requiring anything more from your side than a forge build ios && forge build android.

Your legacy? It matters to us.

Platform Version 2.4

The road to 2.4 has been long and I know a lot of you have been patiently waiting for the Crosswalk support from our beta branch to finally make its way to stable release.

Well, I’m pleased to announce that today we finished the last major piece of work that has been holding this back!

Basically, we had two major blockers:

  1. The Ant build system had problems dealing with application resources from multiple external libraries which led to all kinds of horrible bugs when using Crosswalk with some native modules.
  2. There was no simple way to test custom native modules in both the Android and Crosswalk environments.

The resolution wasn’t simple but, ironically, it came in the form of the kind of announcement we’d normally dread:

As of next year Google will no longer be supporting Eclipse or the Ant build system.

It’s taken the better part of two months, but we’ve finished migrating our Android build system over to Gradle and it has brought a wealth of cool stuff, including:

  • Android Studio support for custom native module development.
  • Support for using .aar packages directly from your custom native modules.
  • Support for including module dependencies directly from Maven and other repositories.
  • Support for debugging modules against both Android and Crosswalk.
  • Support for building x86 and 64-bit packages for Android.
  • No more module resource conflicts!

We’ll continue to support Eclipse for as long as possible, but you may be surprised how easy (and pleasant!) it is to move your module development over to Android Studio.

Release Timeline

Migrating the Android build system is a massive change and, no matter how much testing we do on our side, there is still potential for things to break.

We’re now officially in feature-freeze for v2.4 and will be pushing v2.3.2beta-1 to production early next week.

Depending on how much feedback we get from y’all at we’re hoping to pull the trigger on stable release before the end of the year. Forge support for iOS9 and OSX “El Capitan” is ready! Forge is ready for iOS9 and OSX El Capitan

If you caught last night’s Apple event you’ll know Apple have finally pushed the GM releases for Xcode 7, iOS 9 and OSX El Capitan.

The GM release is what Apple will be shipping to the general public in a week’s time so, if you haven’t been following along during the Beta-test phase, now is the time to make sure your app is ready for iOS 9.

We’ve been working towards this moment since the initial announcement in June and are pleased as punch to announce that supports iOS9 and OSX El Capitan as of platform version v2.2.16.

To get your app running on iOS 9 all you’ll need to do is take the following steps:

1. Upgrade your Xcode to version 7

You can grab the GM seed from the Xcode Developer Center or, if you don’t mind waiting a week, download the update from the App Store.

2. Update your iOS device to iOS 9 (Optional)

If you don’t want to wait till next week, you can head over to the iOS Developer Center and grab the install image.

We also support the new iOS 9 simulator in Xcode 7 so this step is not necessary if you want to hold off on upgrading your hardware immediately.

3. Update your app to platform version v2.2.16

To update your app to the latest platform version open up the Toolkit, navigate to your app config and click on the Change version button:

Toolkit App Config

In the popup dialog, simply click the Switch to v2.2.16 button:

Toolkit App Version

That’s it!


Sometimes there are minor teething issues with GM releases as Apple often adds a bunch of new stuff that wasn’t present in the betas. So please, if you run into any problems or have questions, don’t hesitate to let us know at and we’ll be all over it!

Important note for Ionic/Angular users:

We’ve heard reports that UIWebView for iOS 9 introduced a breaking change that can cause issues for apps that rely on the semantics of window.location.

If your app uses the Angular $location service you can find a patch and more information here:

Shipping Code with Forge
Part 2: Choose Your App Architecture


Welcome to the second part of our new monthly blog series, “Shipping Code”!

In the previous instalment we took a look at the various strategies available for developing your mobile app. We covered Mobile Web Apps, Native Apps and Hybrid Apps.

For the remainder of the series we’ll be leaving Web & Native Apps behind to focus purely on Hybrid App development because that’s what we do here at!

How should I structure the architecture of my Hybrid app?

Now that you’ve decided on a Hybrid App for your development strategy the next question you’ll face is how to structure your code.

There are a variety of architectural patterns in common use and the approach you decide on will depend largely on the type of application you are developing.

In general terms we can break the patterns down into the following broad categories:

  • Single Page: The “Single Page” architecture is the most common pattern found with hybrid apps. This architecture takes the form of a single index.html page which serves as the containing document for the app. Content and resources are then dynamically loaded into this page via Javascript.
  • Static Site: The “Static Site” architecture is similar to a traditional web site. The app consists of multiple HTML pages which are linked together via hyperlinks.
  • Hosted Iframe: In the “Hosted Iframe” architecture the app takes the form of a single index.html page with an embedded <iframe/> tag which contains a remote web site.

Let’s take a closer look at each of these patterns:

Option 1: Single Page

single-page architecture

The trend over the last ten years has been towards so-called “Single Page” apps which move responsibility for rendering the application UI from the server towards client-side HTML and Javascript.

This approach brings a number of advantages, most importantly:

  • Speed: With traditional server-side architecture there is a significant delay after each user interaction as a request first has to be sent to the server and any UI updates have to be returned to the user.
  • Simplicity: Rather than managing complex application and UI state on the server for each user, that state can now be maintained locally on the user’s device.

See the Wikipedia page for a thorough discussion on Single Page applications.

While the entire app is hosted on a single page local to the device the backend web server still plays a role. Most commonly, a RESTful JSON interface will be exposed on the web server which provides the following services to your app:

  • Implementing application logic for the data endpoints used by the application.
  • Retrieval and persistence of application state.
  • User authentication and authorisation.

The components of a Single Page App

The exact structure of your Single Page app will depend largely on whether you are using vanilla HTML/Javascript/CSS or one of the many Third-party Single Page app frameworks to implement your app.

That said, most Single Page apps will contain some combination of the following elements:

  • A src/index.html file containing:
    • The basic app layout
    • Imports for your Javascript code.
    • Imports for your CSS code.
    • Imports for any Third-party Javascript & CSS libraries.
  • One or more src/templates/*.html files containing:
    • Templates for your views
    • Templates for your UI components
  • One or more src/js/*.js files containing:
    • Your application logic.
    • Third-party libraries and frameworks.
  • One or more src/css/*.css files containing:
    • Rules for the look & feel of your application.
    • Third-party CSS frameworks.
  • Binary resources such as images, audio or video.

Third party Single Page App Frameworks

There are a large number of Third-party Single Page libraries and frameworks available that simplify the task of structuring and developing your Single Page app.

While the borders aren’t always clear-cut, we can divide Single Page app Frameworks into two broad categories:

  • Application Frameworks: Provide functions to handle app navigation (routing), template rendering, user event processing and data-binding between the application’s data and user interface elements.
  • User Interface Frameworks: Provide User Interface elements such as buttons, lists, popovers, transitions etc. that mirror the functionality (and sometimes also the look & feel) of native apps.

Some examples for each type of framework are:

Application Frameworks

User Interface Frameworks

Figuring out which framework will work best for your purposes can be a complex endeavour and is a topic we’ll cover in-depth with our next instalment.

Pros for Single Page Architecture

  • Provides a fluid user experience with complex interactions comparable to Native Apps.
  • It’s much easier to develop complex Single Page apps than traditional server-based applications.
  • There is a huge selection of high-quality Third-party Single Page app frameworks available.
  • You can access all forge.* API’s from your app.
  • Users can still use your app even if they are not connected to the Internet.

Cons for Single Page Architecture

  • If you have not developed Single Page apps before you’ll have to go through a mild learning curve to get comfortable with the concepts.
  • If you want to use functionality from your existing website you may need to implement a RESTful JSON interface for transferring data between your app and backend services.

Option 2: Static Site

static architecture

This approach can work well with simple apps that require interaction with native device features and consist primarily of statically served web pages, images and other resources.

The components of a Single Page App

Structured in the same way as a website serving static content, your hybrid app contains a separate HTML file for each page in the site.

While it’s tempting to think you could take any existing website and easily convert it to a web app in this way it’s worth remembering that this will only work with the very simplest of sites as you will no longer be able to rely on the server for processing user interaction or other forms dynamic processing.

Pros for Static Site Architecture

  • It can be the easiest way to transfer content from an existing site to mobile.
  • You can access all forge.* API’s from your app.
  • Users can still use your app even if they are not connected to the Internet.

Cons for Static Site Architecture

  • Maintaining a complex application as a set of HTML pages can quickly become overwhelming.
  • If your existing site features complex server interactions you will have to rewrite those as client-side Javascript and expose a RESTful JSON interface on your server.

Option 3: Hosted Iframe

hosted iframe architecture

If you have an existing web app which does not require complex interactions with native device features or functionality you can simply “host” it inside a hybrid app by using an <iframe /> HTML tag inside your app’s main page.

An important factor to bear in mind is that you cannot directly access forge.* API’s from the remote site’s pages.

If you would like to make use of native device features you will need to bridge the calls from the remote page to your app’s src/index.html page by using the window.postMessage() and window.addEventListener() API’s to marshall communication between the hosted site and the parent hybrid app.

A Simple Example

The code for the remote page, hosted on the remote server:

The code for your app’s src/index.html page:

Pros for Hosted Iframe Architecture

  • You can re-use portions of your existing site’s functionality.
  • You can decide which portions of your app will be implemented locally and which portions will re-use existing site functionality.

Cons for Hosted Iframe Architecture

  • You will need to apply responsive design to your remote content or it may look odd on mobile devices.
  • Accessing device functionality through the forge.* API’s is more complex as function calls will need to be marshalled through the iframe’s parent window.
  • Users may not be able to use your app unless they are connected to the Internet.


All of the above options are supported by Forge but we will be spending the bulk of our time in this series focusing on the Single Page App Architecture (Option 1) as it has emerged as the most practical and popular pattern for hybrid app development.

In the next instalment of this series we’ll be taking a closer look at some Single Page app frameworks and the problems they solve.

Until then, if you have any questions about the material we’ve covered so far, we’d love to hear from you at!

Using OAuth 2.0 and the Google API Client Library for Javascript with Forge


Google’s beta release of their API Client Library for Javascript promises to make life easier for developers who want to integrate their apps with Google services (Calendar, Contacts, Analytics, etc.)

While Google provide some documentation for using their library with web applications accessed via a standard browser there are some gotchas involved when trying to make us of it in a Hybrid app environment.


  • Athentication & Authorization flow differs slightly as Hybrid apps do not support the creation of popup windows.
  • Google make use of a small shim library which bootstraps the rest of the library source code from their remote servers. This library has a bug which causes it to fail silently when included from a page which has been served by a protocol other than http:, https: or file:. Unfortunately, app assets are served via the content: protocol on Android!

In this technote I’m going to show you how to use the GoogleJS Client Library and walk through solutions to both of these issues.

Application Configuration

To follow this tech note and use the Google Javascript client library, you’ll first need to configure your application as follows:

Step 1: Platform Version

Make sure your app is running on platform version v2.2.15 (or higher)

Step 2: Modules

Add the following three modules to your app:

  • tabs – We’re going to use a forge tab to open the OAuth authorization dialog and obtain the user’s auth token for your app.
  • httpd – This is a new, experimental, module which serves your app content via the http: protocol rather than file: (iOS) or content: (Android).
  • parameters – We’re going to use the parameters module to store your Google API keys.

Step 3: Trusted URL’s

In your app config, go to core => general => trusted_urls and add the following entry:

This will whitelist any requests made to the httpd module and ensure they are opened by your app’s webview rather than the device browser.

Obtain Google API keys

Before you can use the Google Javascript client library you’ll need to register your app and create a set of API keys.

You can find full instructions here but the process boils down to the following steps:

  1. Visit the Google API’s Console
  2. Create a project for your application.
  3. Navigate to: API's & auth => APIs
  4. Select the API’s you want to use and enable them.
  5. Navigate to: API's & auth => Credentials
  6. Create a new OAuth “Client ID” with the following settings:
    • Application type: Web application
    • Authorized Javascript origins: http://localhost
    • Authorized redirect URIs: http://localhost/oauth2callback
  7. Create a new Public API access “Key” with the following settings:
    • Key type: Browser key
    • HTTP referrers: Leave empty

Once you’ve created the keys, you can add them to your app by adding the following entries to the parameters module:

Loading the Google client library

To load the Javascript client library, include the following script tag in your app’s src/index.html file:

You’ll notice that the script takes a single argument: onload=OnLoadCallback

This specifies the name of a Javascript function in your code that will be called once the library has finished loading and is ready for use.

To implement the callback, add the following global function definition to your code:

Depending on how your app is structured you can use this callback in a number of ways, including:

  • Setting your Public API access key.
  • Letting the rest of your app know that the library has loaded and ready for use.
  • Logging in the user for API’s which require OAuth login credentials.
  • Checking that cached OAuth login credentials are still valid.
  • Loading the Google API libraries your app will use.

Performing Public API requests

For Public API requests the only authorization you’ll require is to set your API key in the library onload callback.

To keep downloads to a minimium Google have implemented an incremental loading mechanism for the client libraries.

To use a particular library you will first have to load it by making a call to gapi.client.load(API_NAME, API_VERSION, CALLBACK).

Once the library is loaded you will be able to access it directly using the format: gapi.client.API_NAME.FUNCTION

For example, the following code can be used to return public information for a Google+ user:

Note that you only ever have to load a libary once via gapi.client.load.

For more information you can refer to the Google documentation.

OAuth 2.0 Authentication & Authorization

To access any private data belonging to the user your application will need to work with Google’s OAuth 2.0 mechanism.

While Google provide a simple convenience method in the form of gapi.auth.authorize() it is not suitable for use in a Hybrid application as it will attempt to open a browser popup window to handle user login.

Fortunately it’s easy enough to write our own OAuth function using the tabs module:

Note that this method is not only limited to Google but can also be used for any other OAuth service!

Our OAuthorize funtion takes an options object as an argument with the following fields:

  • url – the remote OAuth end point. In this case we’ll be using Google’s.
  • client_id – the OAuth Google Client ID you signed up for earlier.
  • redirect_uri – the URL to redirect the OAuth popup to after the user has authenticated. Here we will use the value we used earlier when we created our Google Client ID.
  • scope – the scope of the authorization we’re requesting. For now we’ll just limit this to the user’s basic information on Google Plus.

To authenticate our App with Google and obtain an authorization token we can use to configure the Google client library we’d use the function like this:

Now we can make Google API calls that will return user information:

…and that’s a wrap!

For more information on Google’s OAuth mechanism please refer to the Google documentation.


I hope you’ve enjoyed this quick walkthrough on using Google’s Javascript Client Library with Forge. As always, we’re looking forward to your questions or comments at!

Shipping Code with Forge
Part 1: Choose Your Mobile App Strategy


Series overview

Part of what attracts developers to hybrid apps is the freedom of choice we get from building on open standards supported by the community of our fellow developers but this very freedom can also be intimidating at times!

To help make sense of the wild and wooly landscape out there we’d like to introduce our new monthly blog series: “Shipping Code”

Our “Shipping Code” series will be running over the next year and will cover the entire hybrid app development cycle from beginning to end.

The process of shipping a new mobile app from scratch is complex and you’ll run into many different questions on your journey.

What we will try and do is to fit those questions (and some answers!) into a cohesive picture which, we hope, will assist both new hybrid developers and even old hands to locate themselves in the happy chaos of modern mobile app development.

Introduction: The Three Mobile App Strategies

As a developer you have three broad strategies available to you if you want to develop an app which runs on a mobile device:

  1. Mobile Web App
  2. Native App
  3. Hybrid App

We’ll be kicking off our series on hybrid app development by examining some of the pros and cons of each approach.

Strategy 1: Mobile Web App

The easiest solution for getting your application onto a mobile device is to simply develop it as a web application.

Web App

Mobile web apps are hosted on a remote server and built using identical technologies to desktop web apps: HTML5, JavaScript and CSS

The primary difference is that it will be accessed via mobile device’s built-in web browser which may require you to apply responsive web design principles to ensure that the user experience is not degraded by the limited screen size on mobile.

There are a number of limitations to this approach but the biggest is that you will only have limited access to device API’s, features and integration with other apps on the user’s device.


  • Few, if any, technological differences from any other web site or web application.
  • Maintain a single version of your app for both mobile and desktop versions.
  • You can easily ship new versions of your app by updating the remote server.


  • The cost of applying responsive design principles to an existing website may be a significant fraction of developing a mobile app.
  • Your app will not be available on mobile app stores which may make it hard for users to find it.
  • Mobile device browsers have historically lagged behind their desktop counterparts, this can create compatibility issues on mobile devices with parts of your app not behaving as required.
  • Limited access to device features.

Strategy 2: Native App

Native Apps exist on the other extreme of the scale. They are developed using the device’s native SDK’s.

Native App

On Android this usually means writing your code in Java using Google’s Android SDK libraries. On iOS you’d be working in Objective-C or Swift using Apple’s iOS SDK libraries.

This is unquestionably the most powerful approach as you are able to access all features of the device and make use of the native UI components of the device.

The biggest downside is that you’re going to need engineers with the skills required to maintain two separate platform versions of your app, one for each device you want to support.


  • Access to all device API’s, features and inter-app integration.
  • Full control over the user experience allowing for complex experiences such as gaming or content creation.
  • Your app will match the native look & feel of the device without requiring a 3rd-party UI library.
  • Your app will be available on App stores.


  • Development costs are high and can take orders of magnitude longer to ship due to the low-level nature of the device SDK’s.
  • You need to write and maintain a separate version of your app for each device you want to support.
  • Developers need to learn multiple different programming languages and API’s with steep learning curves for each version of the same app.
  • Slower development time.
  • Bugs are more likely to crash your app (or even the device!)
  • Harder to debug errors & crashes
  • Shipping updates can be slow due to the app store approval processes.

Strategy 3: Hybrid App

Hybrid apps occupy the space in the middle of the previous two extremes. They enable you to use standard web technologies to develop your app whilst, simultaneously, having access to the native API’s and features of the device.

Hybrid App

While they have somewhat of a reputation for not being competitive against their native counterparts the present reality is that we continue to see more and more world-class apps that shipped with a Hybrid App strategy.

There are many more good reasons to choose a Hybrid App for your project but there’s one factor which stands out above all else:

Shipping and maintaining a Native App on both Android & iOS is going to cost you, at the very least, twice as much as a Hybrid App.

…and this is assuming that you and/or your team are already well versed in Java, Objective-C, Swift and the Android & iOS SDK’s!


  • You can use most of the same technologies and tools used for web development to create a mobile app.
  • Maintain a single codebase for both iOS and Android versions of your app.
  • You can re-use many components of any existing web apps you may have.
  • Your app will be available on App stores.
  • Easily ship updates to your app without requiring App Store approval with Reload.
  • Access to device API’s, features and application integrations via native modules.
  • Modern web-technologies such as CSS Transitions and WebGL allow you to achieve near-native UI performance even for complex user interactions.
  • Excellent development tools courtesy of Chrome & Safari remote debugging.


  • Achieving a native look&feel depends on 3rd party frameworks which may vary in quality.
  • There are many different ways of doing things and it can be hard to know which approach to follow up front.
  • App performance can suffer if you are not conscientious.
  • Accessing some native device features may still require you to write portions of your app in native code.


In this, the first instalment of our “Shipping Code” series, we looked at the pros & cons of the three strategies for mobile app development: Mobile Web App, Native App and Hybrid App.

In the next instalment of this series we’ll be taking a look at the different architectural choices you need to make when developing your Hybrid App.

Until then, if you have any questions about the material we’ve covered so far or suggestions for future instalments, we’d love to hear from you at

Use and Mozilla’s PDF.js to build a PDF viewer for your Android app


While iOS has had a native PDF viewer baked into the WebView component for as long as I can remember the Android WebView is still unable to open PDF files for viewing.

Usually this problem is solved in one of two ways, neither of which are ideal:

1. Show the PDF file via the online view capabilities of the Google Doc Viewer.

  • Requires that the user sign into their Google Account before they can view the file.
  • It’s not immediately clear to the user how they should navigate back to your app.

2. Download the file locally and open it via an external Android app.

  • Complex to implement.
  • May fail if the user’s Android device does not have a PDF viewer installed.
  • It’s not immediately clear to the user how they should navigate back to your app.

In this tech note we’re going to explore a third option which uses Mozilla’s PDF.js library to seamlessly display PDF files in your app and does not suffer from any of the drawbacks above.

Introducing PDF.js

PDF.js is a HTML5 Portable Document Format (PDF) viewer built by Mozilla Labs. that can faithfully and efficiently render PDF files without native code assistance.

It provides excellent document rendering quality and is easy to integrate into an app to provide a workable solution to the problem of rendering PDF documents for your Android users.

You can find out more about the project on the GitHub page:

Using PDF.js in your App

Step 0: Create an application

Create a new app and add the following modules to it:

  • file – unless you are viewing PDF files which are local to your app or can set CORS headers on the remote server you will need to use forge.file.cacheURL to obtain a local copy of the file.
  • tabs – you may wish to continue using the tabs module to display PDF’s on iOS

Step 1: Obtain the PDF.js library

While there are instructions for building the PDF.js library from source on the GitHub page we’ll be making our lives easier by using the bower package manager to obtain a copy of the library:

What this will do is add a subdirectory called bower_components to your app containing the following files:

If you don’t already have bower installed on your system you can head over to for installation instructions and documentation.

Step 2: Load the PDF.js library in your app

Open your app’s src/index.html file and add the library includes to the other content in your page’s <head> section:

Step 3: Create a custom PDFViewer

A huge advantage of using a HTML5-based PDF Viewer is you get a lot of control over how to represent the reader to your users.

Not only can the viewer itself be customized by modifying bower_components/pdfjs-dist/web/pdf_viewer.css but you also get complete control over how it will be hosted within your app.

For the purposes of this tutorial we’re going to replicate the look & feel of opening a PDF using forge.tabs on iOS to give us something like this:

Android PDF Viewer

Let’s open our app’s src/js/main.js file and implement a simple PDF viewer based on PDF.js:

Step 4: Test it!

Open up your app’s src/index.html file and add some code to test your viewer:

In Conclusion

In this short tutorial we walked you through the process of using Mozilla’s PDF.js library to build a simple PDF viewer you can use inside your app.

You can obtain copies of the full src/index.html and src/js/main.js files used for this demo here:

GitHub Gist

We hope you enjoyed it and are looking forward to hearing from you at if you have any feedback or questions!

How to use Android AAR libraries with your Native Modules


Third-party native libraries for Android are increasingly starting to appear only in AAR form.

This is wonderful if you’re using Gradle and/or Android Studio but the native module build system uses ant for build automation!

Fortunately, it’s relatively simple to convert an AAR library into a format you can use with your native modules.

If you were to unpack an AAR library you’d find that it is really just a standard Android library project which has been zipped up into a single file:

To import an unzipped AAR library into a module you would have to take the following steps:

  1. Convert any entries in AndroidManifest.xml to module/android/build_steps.json
  2. Copy classes.jar to module/android/libs
  3. Merge res/ with module/android/res
  4. Copy any jar files in libs/ to module/android/libs
  5. Copy any JNI libraries in jni/<abi>/ to module/android/libs/<abi>
  6. Create any entries in proguard.txt to module/android/build_steps.json

This can be a little overwhelming so we’ve written a small python script called which largely automates the process.

You can grab yourself a copy from here:

In the next section we’ll walk through an example of using it to import an AAR library for use by your native module.

Step 0. Backup your module directory!

Either commit the current state to source control or make a copy of your module/android directory so you are able to restore it to its original state if anything goes wrong during this process!

Step 1. Switch to at least Platform v2.2.11

To support JNI libraries we had to make some small changes to the Forge platform so you may need to update your module/manifest.json file’s platform_version to at least v2.2.11:

Step 2. Import aar libraries

Copy the script to your local machine and run it as follows on each of the aar files you wish to import:


For the purposes of this tech note we’re going to walk through a simple module that uses the Google Play Services Maps .aar library to add support for the native Google Maps UI to your app.

First, start the Android SDK manager and make sure you have the latest version of the Google Play services package installed:


Next, copy the following aar libraries from your Android SDK directory into a temporary location:

Now you can impor the AAR library into your module as follows:

To use Google Play Services SDK you’ll also require a few additional entries in your app’s AndroidManifest.xml, so let’s add those to module/android/build_steps.json.

Google Play Version

Google Maps API key

You’ll need to replace the key below with your own key:

See for instructions on how to get your own key.

Step 3. Update the Android inspector in the toolkit and write some code

Once you’ve imported the AAR libraries you’d like to use you can simply click the Update Android button in the Toolkit to refresh the Android Inspector project with the imported AAR library content.


To test it, let’s add support for the Google Play Services Maps library we imported.

Open up the Android Inspector in Eclipse and create a new class called MapFragment in the ForgeModule project:

Next, you’ll need to add an entry to your app’s AndroidManifest.xml file for the MapFragment class. Do this by adding the following step to module/android/build_steps.json:

(Remember to update your inspector after making any changes to the files in your module’s module directory!)

Finally, edit and add the following API method to your module which will instantiate the MapFragment class you created above:

Now, if everything goes to plan you should be able to run the ForgeInspector project on your mobile device, select the showMap method, hit “Run!” and see:


Closing thoughts

Android AAR libraries may seem complex at first but, in reality, they make integration of 3rd-party libraries much easier with your app.

Instead of wrestling with the individual pieces of a library, developers are now able to use a single integrated bundle which makes it possible to import library classes, resources, AndroidManifest.xml entries, proguard rules and JNI libraries into your app with a single step.

We hope you enjoyed this TechNote and look forward to hearing from you at if you have any comments or questions!

Connect Everything to Everything Else With and PubNub

It’s a fascinating time to be a developer. As early as 2008 the number of things connected to the internet surpassed the number of people alive on earth, and some well informed people think the number could be as high as 50 billion by 2020.


Users have been exposed to the type of user experience that realtime web technology provides, and expect those types of experiences in the apps they use.

Although realtime web technologies have been around for some time it’s only quite recently they’ve started to pervade everyday activities, such as hailing a taxi, keeping track of sports scores, bidding in an online auction or even opening the door to the garage.

Keep talking

Massive social platforms now represent one of the main ways that we communicate with each other. It’s realtime technologies that power the interactivity that make the experience so rewarding. Given the comprehensive toolsets provided by PubNub, implementing full-featured, massively scalable messaging has never been easier.

IoT and Really Big Numbers™

Talk about the Internet of Things (IoT) brings up numbers that can get anyone sweaty!

The global market is estimated to be worth $7.1 trillion by by 2020, or $14.4 trillion, according to Cisco. Less than 1% of things that could be connected to the Internet currently are, which means 10 billion things out of the 1.5 trillion that exist globally are currently connected. That’s a big gap, and a big opportunity.

Time-to-market has never been more key, nor a mature and well-developed technology stack.


PubNub started life as a provider of APIs allowing publishers and developers to integrate messaging and social services on apps and websites.


Since then their product offering has evolved into The PubNub Data Stream Network, a PAAS which allows rapid development of real-time apps and communication for web, mobile and IoT apps.

Their wide range of robust, friendly APIs merge seamlessly with’s fast, effective hybrid mobile runtime, bringing realtime technology to mobile.


In software architecture, publish–subscribe is a messaging pattern where senders of messages, called publishers, do not program the messages to be sent directly to specific receivers, called subscribers. Instead, published messages are characterized into classes, without knowledge of what, if any, subscribers there may be. Similarly, subscribers express interest in one or more classes, and only receive messages that are of interest, without knowledge of what, if any, publishers there are.

Pub/sub is a sibling of the message queue paradigm, and is typically one part of a larger message-oriented middleware system.

This pattern provides greater network scalability and a more dynamic network topology, with a resulting decreased flexibility to modify the Publisher and its structure of the data published.

Using PubNub with

To demonstrate Pubnub’s ease of use I’m going to show you how to run PubNub’s 10chat 10-line Javascript chat sample inside a app.

Step 1


Create a new app in the Trigger Toolkit.

Step 2


Under Config / Tools, specify whether you want the app to run on a specific device or emulator, and specify the path to the appropriate SDK

Step 3


Now let’s give it a test run! Under Forge, click either Android or iOS to run it on the appropriate platform, or click Web to run it in a browser window.

You should now see something like this:


Step 4

So far so good, now let’s make it do something!

Find the index.html file in the src/ folder of your app, open it in the text editor of your choice and remove the template code between the <body></body> tags to leave you with something like this:

Step 5

Click here to go to PubNub’s 10chat demo page:


…now copy the 10chat javascript code from the code box into your app’s index.html file:

Step 6

Save the file, go back to the Trigger Toolkit and run the app again.

Now if you open the 10chat page in a web browser you’ll be able to chat back and forth between the two!


Learn More

We hope you enjoyed this short introduction.

For more in-depth tutorials on PubNub, please visit the PubNub Data Stream Tutorial page.

If you’re interested in learning more about using PubNub with please give us a ping at, we’d love to hear from you!

Setting Up Google Play Services for a Trigger.IO Native Module

Google Play Services Logo

Adding support for the Google Play Services library when building an Android custom native module is a little more complex than most and we’ve had a number of requests for detailed information on how to do it.

While Google provide detailed documentation, it’s not always clear how that maps to the Trigger.IO native module SDK.

The process boils down to these five basic steps:

  1. Add the Google Play Services Jar file to your module.
  2. Add the Google Play Services resource directory to your module.
  3. Add a meta-data tag for the app’s AndroidManifest.xml file
  4. Add Proguard rules to allow Google Play Services to use reflection.
  5. Update your module’s inspector project with the changes from the previous steps.

Let’s walk through these steps in detail…

Step 0: Increase Eclipse memory limits (optional)

If you run into issues here where Eclipse crashes out on after adding the Google Play Services library to your module you’ll need to edit your eclipse.ini configuration file and increase the memory limits:

Step 1: Add Google Play Library

To include external libraries you need to copy them into the module/android/libs folder in your module:

Step 2: Add Google Play Resources

To include the external resources used by the Google Play Services library you will need to copy them into the module/android/res folder.

Step 3: Setup AndroidManifest.xml

Google Play services require you to specify the version of Google Play Services your app is working with in your app’s AndroidManifest.xml file.

To do this open your app’s module/android/build_steps.json file and make sure it looks as follows:

Step 4: Add Proguard rules

As part of the final compilation step, the Android compiler will use ProGuard to obfusticate the bytecode passed to it. This can cause problems with some libraries which rely on reflection to look up class and method information at runtime.

To prevent Proguard from obfusticating the Google Play Services library add the following to your module/android/build_steps.json file:

Step 5: Update Inspector

The final step just requires you to update your module’s inspector project by navigating to your module in the Trigger Toolkit and hitting the “Update Inspector” button.

Please give us a shout at if you have any questions.

Solving Android Fragmentation with Trigger.IO Forge and Intel’s Crosswalk

The State of the Hurt

Anyone developing for Android will be all too familiar with the compatibility issues that come up when trying to run apps on older Android devices. Historically, even the act of porting an app from a desktop browser environment to Android has been fraught with issues as the Android WebView lacked many basic HTML5 features and suffered from implementation problems.

While Google did much to rectify this after they started shipping a Chrome based WebView with Android 4.4 the reality is that, at the time of writing, Android 4.4 or higher devices still only account for 44.2% of the marketplace.

The remainder is made up of 7.3% devices still running Android 2.x while a massive 48.5% of devices are still running some version of Android v4.x with various non-Chrome versions of the Android WebView.


Image from:

Finally, if you thought it couldn’t get any worse… even if we assume that at some point in the future we have a majority of devices running 4.4 or higher there is STILL no guarantee that your app will run smoothly across Android versions as it is entirely up to the vendor whether a given device will be receiving regular updates of the System WebView!

Against this background it therefore gives me great pleasure to announce that we have integrated Intel’s Crosswalk technology with Trigger.IO.

Starting from today your Forge apps only have to target a single web runtime for Android which covers 92.7% of all Android devices while retaining full access to all of our Forge API’s.

What is the “Crosswalk” Forge target?

Android versions before v4.4 shipped with a proprietary System WebView which lacked many basic HTML5 features, performed poorly and suffered from compatibility issues.

Android versions higher than v4.4 use a Chrome-based System WebView which, in turn, is based on the open-source Chromium code base which closely tracks HTML5 implementation standards.

Up till now, developing hybrid apps under Android meant that your app would be hosted by whichever System WebView shipped with the device forcing developers to take a “lowest-common-denominator” approach and spend an inordinate amount of effort to ensure rendering compatibility.

What the Forge crosswalk target does is to embed a build of the latest versions of the open-source Chromium WebView directly within your Forge application, allowing your app to execute in a uniform environment irrespective of the System WebView shipped with a particular device.

This means your app will behave exactly the same no matter which Android device it is running on!

How well does Crosswalk perform?

Apart from the tangible benefits that come from being able to target a uniform WebView, the Forge crosswalk target also provides significant performance improvements over all versions of the Android WebView, even those based on Chrome.

HTML5 Conformance

We checked a variety of Android devices against the HTML5TEST Benchmark for HTML5 conformance and found some interesting results:



The older devices showed the most significant improvements over the default System WebView, in all cases exceeding even the iOS System WebView in compatibility scores.


Our biggest surprise from HTML5 conformance testing was the marked improvement we saw even for devices that shipped with a Chrome-based System WebView. Even the latest Chrome-based System WebView scored a couple points lower than Crosswalk. We attribute this to the fact that Crosswalk are able to more rapidly integrate and ship improvements from the upstream Chromium project.


Something else we noticed was that there was some variation in crosswalk scores between devices. Closer investigation showed that, in all cases, the variation came down to the following HTML5 features which required hardware support:

  • WebAudio is only available on ARM devices that support NEON optimizations which were introduced with the ARM Cortex-A8 processor.
  • Newer Video Codecs require specific hardware support for decoding which is not present in some older Android devices. Our recommendation is that if you are in doubt, use H. 264 as support is a requirement for all Android devices on the market.
  • Support for the universally loathed DRM and Media Source extensions are tied to Video Codec support and may therefore not be available on some devices.

Javascript Performance

For Javascript performance we evaluated the same set of devices against the Octane 2.0 Benchmark:

Octane 2.0 Results

The impact of Chromium’s use of Google’s V8 Javascript engine is clearly visible in these results with older devices showing as much as a 60% improvement in execution speed.

Again, the advantages of crosswalk are evident even on newer devices where we see an 8% improvement on identical Nexus 7 hardware between the older Chrome-based WebView on Android 4.4.3 vs Android 5.0.2.

How do I use it?

Crosswalk is currently in Open Beta and can be accessed by changing your App’s platform_version to v2.3.1beta-3 and using the crosswalk target rather than android:

  1. Open your application’s src/config.json file in an editor and set the platform_version key’s value as follows:
  2. Run your app from the Toolkit using the Crosswalk button or from the command-line with:

This is a Beta release so please don’t be dismayed if you run into issues. We’ll be standing by at to answer any questions you may have!

When will it enter the stable platform branch?

The Crosswalk target is the biggest change we’ve implemented since the release of Android 4.x and the Crosswalk project itself is still under heavy development so we’re going to be holding off a bit on pushing it to the stable v2.2.x release stream until everyone’s had a chance to try and break it!

To track release information you can go to: Forge Beta Release Notes

How much will it cost?

Integrating Crosswalk into Trigger.IO Forge has been a major engineering challenge which we’ve invested a lot of time, money and resources into.

Because of this, we did toy with the idea of making access to crosswalk exclusive to our Go Pro or higher customers as a way of recouping our development cost.

That said, our philosophy has always been to provide all of our customers with access to the best tools for Hybrid App development.

Our experience with Crosswalk is that it falls into that category of game-changing technology which everyone should have access to.

Therefore, we made the decision to make Crosswalk available, at no extra charge, to all of our customers irrespective of the plan they are on.

What about my custom modules?

We’ve been able to maintain binary compatibility with the vast majority of Forge modules and it is likely your modules will continue working “as is”.

If you have a custom module which is behaving strangely under Crosswalk please contact us at and we’ll be happy to assist you with any changes that may be required.

In conclusion

By using the Forge Crosswalk target to build your apps you are now able to take advantage of a unified HTML5 runtime with significant Javascript performance improvements.

Crosswalk also offers a more rapid release cycle than the Android System WebView and continues to bring new HTML5 features and performance improvements to your app even on devices which are no longer supported by vendor updates.

With Crosswalk you are now also able to take advantage of many new HTML5 standards and features which, in the past, had to be avoided due to compatibility concerns, including:

  • 3D CSS Transforms
  • WebGL
  • Date/Time input types
  • Multiple file selection
  • Raw Sockets
  • WebRTC

We feel that the integration of Crosswalk marks the beginning of a new era for our Forge standards-based Hybrid App Runtime and look forward to making the new capabilities developed by the W3C over the last few years available to all of our users.

Happy hacking everyone!