Firebase is a platform for developing mobile and web application that provides analytics, authentication, real-time databases, notifications, cloud messaging, crash reporting and other services for your application. In this post, I will discuss how to use the Firebase Analytics in Cordova applications for measuring app usage and user engagement.

Analytics for Firebase

This is a free service that can be used for both Android and iOS applications. It provides unlimited reporting of up to 500 distinct events and a number of user properties.

Events allow you to see what happens in an application, such as user actions, system events, or errors. There is a number of automatically collected events and you can define your own events. However, you have to keep in mind that:

  • there is a limit of 500 distinct events that can be reported.
  • each event can have up to 25 parameters associated with it.
  • event names can be up to 40 characters long, may only contain alphanumeric characters and underscores (“_”), and must start with an alphabetic character.
  • “firebase_”, “google_” and “ga_” prefixes are reserved and cannot be used.
  • names are case-sensitive and logging two events whose names differ only in case will result in two distinct events.

See FirebaseAnalytics.Event for more information.

User properties are information about the user that is recorded together with the events. Default collected user properties include user info (age, gender, country, language, interests), device info (brand, category, model) and app info (version, app store, first open time, new/established).

Appart from the implicitly collected user properties you can define your own. For that, however, you must use the Firebase console. You must be careful with the properties that you add because for now these cannot be renamed or deleted (you can only change their description).

Getting started

To be able to use Firebase for your Android or iOS app you need to enroll it. For that, you must create a project and then add applications to it.

  1. Open the Firebase console.
  2. Create a new project (or select an existing one).
  3. Add a new Android, iOS or web app.
  4. Follow to instructions to register the app, download the config files or perform other necessary setups.

If you need more help for setting up your app read the Firebase documentation or additional web resources.

Cordova plugin

There is an official Cordova plugin called cordova-plugin-firebase that provides push notifications, analytics, event tracking, crash reporting and other services from the Firebase platform for you Cordova application.

When you start using Firebase, make sure you have the config files properly setup (present and valid). Otherwise, your app will crash on boot or Firebase features won’t work.

Recording events and user properties

To record a user property you should call setUserProperty. This has the form:

The name is the case-sensitive name you defined in the Firebase console. In the example above the name was login_type and possible values were demo and live. The purpose of this is to indicate that for an application that supports a demo mode where the users don’t have to create an account to try the app, the user is either properly authenticated on or actually using the demo feature.

When this call is made the Debug view shows the change of the user property value in the live stream.

If you look at the recorded user properties for all following events you will see the logon_type with the demo value attached to it.

As mentioned ealier, there are a series of events that are automatically recorded. These include screen_view (collected whenever the page has changed) and user_engagement (collected periodically when the app is in foreground). However, you can send any other event, each with any number of parameters. To record events you must use the logEvent function that has the following form:

Let’s suppose that in your app users can bookmark items (whatever those items might be) but also remove them from the bookmarks (or favorites). You want to record the event of adding and removing an item. You can define an event called favorites_action with two parameters: action that can be either add or remove, and type, that indicates what kind of item was added or removed.

These are added automatically to the stream of events, recorded with both the the auto collected and user defined parameters and user properties.


All the events have several implicit parameters, including firebase_screen, firebase_screen_class, and firebase_screen_id. Screen class is the class name of the Activity, and the ID is a numerical ID that is probably hard to use to figure where the event came from. The screen name on the other hand (firebase_screen) is what you probably want to look at. This can be set with a call to setScreenName. All events will have the param firebase_screen set to the last value passed to setScreenName. Therefore, you probably want to make this call whenever the user opens a new page in your application. The call has the form:

Here is an example:

Debugging Firebase Analytics

The events recorded by Firebase are not instantly sent to the servers. Instead they are cached, archived and periodically dispatched. However, you can enable live streaming of events for debugging purposes, both on Android and iOS. This was used for all the screen shots used previously.

For Android devices:

  • To enable execute:
  • To disable execute:

For iOS devices:

  • To enable specify -FIRDebugEnabled as an argument in XCode
  • To disable specify -FIRDebugDisabled as an argument in XCode

For more information see Debugging Events.

, , , , , , Hits for this post: 2958 .

I am building a hybrid mobile app with Visual Studio Tools for Apache Cordova that is able to make phone calls, send text message or emails, view a location on a map, etc. These are all handled with external applications (for instance use Gmail to send an email or Maps to pinpoint a location). They are placed in an anchor tag in HTML, such as <a href="tel:12345678">, <a href="sms:12345678">, <a href="mailto:name@domain.com"> or <a href="geo:...">. These work fine except that when you execute one of these actions and the system opens another app you see for a short time a webview with an error: “Web page not available”. Then the external app opens, you take the action and then go back to the app. At that point you again see this webview with the error as shown below.

ERR_UNKNOWN_URL_SCHEME when sending a text message

ERR_UNKNOWN_URL_SCHEME when sending a text message


This seem to be a known issue as I found many references of it on the web. Here are several for reference:

I am using the InAppBrowser plugin to open links in external apps. In order for this to work the schemes must be white-listed in Cordova’s config.xml file and the launch-external attribute should be set to true (which was already set in my case).

The indicated solution is to override WebView.shouldOverrideUrlLoading method.

I added the following in plugins\cordova-plugin-inappbrowser\src\android\InAppBrowser.java in the plugin’s WebView extension, but that did not work as the code did not even execute.

Looking for a solution I have noticed that this was only working OK for tel: and for others it was exhibiting this behavior. Then I found the following code in the InAppBrowser plugin class, in the execute() method.

I have changed that to include the other schemes and that fixed the problem.

With this in place, the web page error no longer shows up for any URL scheme.

I’m not sure if this is the best solution, but it is the only one that I managed to implement.

, , , , , , , Hits for this post: 29908 .

If you work on a Apache Cordova project in Visual Studio 2013 using Visual Studio Tools for Apache Cordova CTP 3 or 3.1 you should know there are important breaking changes in migrating the project from Visual Studio 2013 to Visual Studio 2015. The project can be migrated, but you have to do everything manually, as Visual Studio is not able to apply the changes automatically.

First of all, Visual Studio Tools for Apache Cordova CTP3.x are not longer supported in Visual Studio 2013 in the first place. If you try to install Update 5 it will prompt you to remove it before continuing.
vs2013u5
This is explained in the release notes for Update 5.

Also note: All prior releases of the Tools for Apache Cordova are incompatible with Update 5. If you have previously installed a Tools for Apache Cordova CTP extension, you must uninstall that extension before installing Visual Studio 2013 Update 5. If you require Apache Cordova support, we encourage you to try Visual Studio 2015.

The options for those developing with the VS tools for Apache Cordova in VS2013 are either to switch to Visual Studio 2015 or not install the last update and continue to work with CTP 3.x in VS2013.

In this article I will show you how to migrate a Cordova application from VS2013 to VS2015 and I will exemplify with a test application.

I have this app called TestApp. It’s built with Ionic and AngularJS. It is a JavaScript app, not a TypeScript app, but this works just the same regardless what language you use. It has the following project structure, with the Javascript source code in a folder called app, the libraries in libs and the templates in views. There are other folders apart from the ones VS has created, mainly css and images.

vs2013proj1 vs2013proj2

The application is just a test, it doesn’t do anything but it works for both Android and iOS.

ripple1 ripple2

When you open this project in Visual Studio 2015 it is not loaded. Visual Studio complains that “This project is incompatible with the current edition of Visual Studio.”
vs2015proj1
You have to covert it manually in order to make it available for Visual Studio 2015. Fortunately, the steps to do this are documented, but not in MSDN as one might expect, but on GitHub. There is a document called Known Issues – Visual Studio 2015 that explains what has to be done.

  • Create a new empty Apache Cordova app. The only purpose of this app is to copy from files to your actually project.
    vs2015proj2
  • Copy the .jsproj and taco.json files into the project folder of the application you migrate. Make sure you overwrite the existing .jsproj with this new project file.
  • Delete the existing bin and bld folders
  • Create a folder called www
  • Move everything except for config.xml and folders merges, res and plugins to the www folder.

If you open the project again in Visual Studio 2015 it will work and you can build and run it. For my test application the new project looks like this.
vs2015proj3

You can see that the all the folders and files under the www folder appear automatically in the solution explorer. They are not added with a Content or Folder element in the .jsproj file. You can make a comparison of the old and new .jsproj and see how simplified the new file is.
jsprojcompare1

Another thing to notice here is that the NodeJS module used for building the project is no longer called vs-mda (i.e. Visual Studio Multi-Device Application) but vs-tac (i.e. Visual Studio Tools for Apache Cordova).
jsprojcompare2

However, when I tried to build I got the following error:

MSBUILD : cordova-build error BLD401: Error : BLD00401 : Could not find module ‘delayed-stream’] code: ‘MODULE_NOT_FOUND’. Please Go to Tools –> Options –> Tools for Apache Cordova –> Cordova Tools –> Clear Cordova Cache and try building again.

This might have been related to the version of Apache Cordova I had globally installed, i.e. 5.1.1. If you get the same install it via npm.

However, you may still get problems when you try to build for Android.

MSBUILD : cordova-build error BLD10205: Please install Android target “”
You may not have the required environment or OS to build this project
MDAVSCLI : error : cmd: Command failed with exit code 2

The Android target name is empty, but if you do a Rebuild you get more information and actual required target name:

[Error: Please install Android target: “android-21”.

Hint: Open the SDK manager by running: C:\Program\ Files\ (x86)\Android\android-sdk\tools\android.BAT
You will require:
1. “SDK Platform” for android-21
2. “Android SDK Platform-tools (latest)
3. “Android SDK Build-tools” (latest)]
C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v14.0\ApacheCordovaTools\vs-mda-targets\Microsoft.MDA.FileMirroring.targets(352,5): error MSB3073: The command “platforms\android\cordova\clean.bat” exited with code 2.

These can be installed using the Android SDK Manager. Make sure you select all the mentioned components.
android1
With these changes you can build successfully for Android.

One more thing here is the version of Apache Cordova used by vs-tac to build. vs-tac uses Cordova 4.3.1, but I already had Cordova 5.1.1 installed on my machine and used by vs-mda. If you have a newer Cordova version than 4.3.1 what you have to do instruct vs-tac to use this one in the taco.json file.

Replace the version 4.3.1 of the cordova command line interface with desired version (in my case 5.1.1). When you rebuilt it will install it and build with it.

Your environment has been set up for using Node.js 0.12.7 (x64) and npm.
—— Ensuring correct global installation of package from source package directory: C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\ApacheCordovaTools\packages\vs-tac
—— Name from source package.json: vs-tac
—— Version from source package.json: 1.0.0
—— Package already installed globally at correct version.
—— Installing Cordova tools cordova@5.1.1 for project from npm. This could take a few minutes…

You can find the various Cordova versions installed under %APPDATA%\npm\node_modules\vs-tac\node_modules\cordova.
vstac3

For more information see:

, , , , Hits for this post: 25260 .

I am investigating using PhoneGap as a platform for building mobile apps for several operating systems including Android. While doing so I have ran into various issues, and this article is intended to help others avoid the same headaches (with a focus on Android).

PhoneGap vs Cordova

The PhoneGap installation documentation says you could install PhoneGap using this command (will come back to that later).

But if you check the documentation or take various online tutorials you’ll notice they say you should install and use cordova. So what is PhoneGap and what is Cordova and which one should you use?

The best explanation comes from the PhoneGap itself:

PhoneGap is a distribution of Apache Cordova. You can think of Apache Cordova as the engine that powers PhoneGap, similar to how WebKit is the engine that powers Chrome or Safari.

Over time, the PhoneGap distribution may contain additional tools that tie into other Adobe services, which would not be appropriate for an Apache project. For example, PhoneGap Build and Adobe Shadow together make a whole lot of strategic sense. PhoneGap will always remain free, open source software and will always be a free distribution of Apache Cordova.

Currently, the only difference is in the name of the download package and will remain so for some time.

In summary, PhoneGap is a distribution of Cordova and for the time being there is no other difference than the name of the package.

(Bonus read: PhoneGap or Cordova? Don’t confuse and tell me the differences!)

The question is then, which one should you use? If you plan to use Adobe’s utilities and services such as PhoneGap Build, then you should use PhoneGap. Otherwise you could pick Cordova. That is what I picked.

(Bonus read: Apache Cordova vs Adobe PhoneGap: the differences and which one to use)

Pre-requisites

In order to install either PhoneGap or Cordova you need to first install Node.js. Node.js is is a cross-platform runtime environment and a library for running applications written in JavaScript outside the browser.

  1. download and install Node.js
  2. add Node.js installation folder (e.g. C:\Program Files\nodejs) to the PATH environment variable

Installing Cordova

To install Cordova run this command in a console:

The version I have installed is 3.5.0. The rest of the article relates to this version of Cordova.

Dependencies for Android

In order to be able to create and build for Android you need additional components.

  • Java
  • Apache Ant, a Java library and command-line tool for building software
  • Android SDK that provides libraries and tools for building, testing and debugging apps for Android

However, just installing these components is not enough. You need to set-up several environment variables, as they are required by Cordova/Phonegap.

  • create a variable called JAVA_HOME and set it to the Java installation folder (e.g. C:\Program Files\Java\jdk)
  • create a variable called ANT_HOME and set it to the Apache Ant installation folder
  • create a variable called ANDROID_HOME and set it to the Android SDK installation folder

After you have created these environment variables you also need to update the PATH variable to enable all these command line tools to be run from a console. Add the following paths to PATH:

Just having the Android SDK installed is not enough. You need to use the Android SDK Manager to install the appropriate tools for your Cordova version. For 3.5.0 the target API is 19 (or Android 4.4.2). When you install the tools make sure you also install a system image so you could create an Android emulator later. (Note that installation may take a while.)
android19
The next step is creating a virtual device for Android. You can run the following command to open up the Android Virtual Device Manager.

android-avd

Having done all this you can go ahead and create a cordova/phonegap application.

Create a HelloWorld application

To create, build and run a first cordova application execute the following commands in a console:

  1. create an application called HelloWorld
  2. edit the application index.html page replacing the text of the text of the “event received” class paragraph:

    with

  3. add the Android platform to the application

  4. build the application for Android:

  5. run the application in an Android emulator

Here is a screenshot of the Android application running in the emulator.
cordova-hw

Troubleshooting

If you missed any of the steps described in this article you will run into various errors when you try to create, edit, build or emulate your application. Below are several possible problems you may encounter and their solution.

Missing Apache Ant

When you try to add a platform to your application you may get this error message:

Error : Executing command ‘ant’, make sure you have ant installed and added to your path.

This is either because you did not install Apache Ant or because you have not setup the environment variables as described above.

Error querying Android targets

When you try to add a platform to your application you may get this error message:

Checking Android requirements…
(Error: An error occurred while listing Android targets)

This is either because you did not install the Android SDK or because you have not setup the environment variables as described above.

Missing Android target

When you try to add a platform to your application you may get this error message:

Error: Please install Android target 19 (the Android newest SDK). Make sure you have the latest Android tools installed as well. Run “android” from your command-line to install/update any missing SDKs or tools.

This is because you do not have the appropriate Android tools required by the installed cordova/phonegap version. For Cordova 3.5.0 the required platform tools are version 19 or Android 4.4.2. You can use the SDK Manager to install the appropriate tools.

No emulator available

When you try to emulate your application you may get this error message:

ERROR : No emulator images (avds) found, if you would like to create an avd follow the instructions provided here: http://developer.android.com/tools/devices/index.html
Or run ‘android create avd –name –target ‘ in on the command line.

This is because no emulator is defined. You need to use the Android Virtual Device Manager to create one or more emulators.

Using Eclipse

You probably do not want to do everything from the command line and plan to use an IDE. Eclipse comes bundled with everything you need for developing for Android. See the following references for using Android with Cordova.

, , , , , Hits for this post: 25607 .