How to Use the Sencha Touch Native Packager & Common Errors

Although PhoneGap Build is my preferred method for creating native applications from Sencha Touch, it’s worth taking a look at how the Sencha Touch native packager works – you can compare the two methods and decide on what is best for you. Essentially, the Sencha Touch native packager packages your Sencha Touch application as a native application (as the name would suggest). This allows you to do two things primarily:

    1. Run your application as a native app, that can be submitted to application stores
    2. Access additional features that the web browser does not have access to such as the devices camera

This is not a difficult process, but it's easy to trip up on certain points and spend hours researching how to get by it. I'm going to walk-through exactly how to run the packager, install the application on a phone and list some common errors you might come across (certainly the ones that tripped me up for a little while). Things you will need:

    • A Sencha Touch Application
    • Provision profiles / certificates (read about how to create those here)

First of all let's create a minified version of your application, open up the command prompt, change your directory to the Sencha Touch application you want to deploy and run the following command:

``` sencha app build package```

This will create a minified version of your application in /build/appname/package. Next we will create the configuration file, this tells the native packager what you are trying to do and some details about your application. Run the following command:

``` sencha app package generate iphoneConfig.json```

This will create a template configuration file called iphoneConfig.json. You can name this file whatever you want, and the same template is used for both iOS and Android (although you will need one for each as the details will be different). Since I'll be deploying to an iPhone for this demonstration, I've named it iphoneConfig.json. Open it up and take a look at the configuration options inside. Most of the options should be fairly obvious and you can go ahead and fill them out, I few that are worth mentioning however:

bundleSeedId – This is only needed for iOS. Go to the Apple developer website and find your App ID, there should be a 10 character prefix on the App ID. This is the bundleSeedId.

inputPath – This is the location of the application you want to deploy. In my case, and most likely yours, this is set to "./build/appname/package"

outputPath – This is where the packaged application will be sent. Make sure this points somewhere outside of your application directory. It will not build properly if the output path is somewhere inside your application, I set mine to "../build" so it is sent to a folder one level up from my application directory called "build".

certificatePath – This specifies the path to your P12 file, in my case I've set this to "certificates/appname_p12.p12"

I've included my entire config file at the end of this post for reference. Now the config file is sorted, it's as simple as running the following command:
sencha app package build iphoneConfig.json

Your built application should now be in the folder you specified as the output path. In order to get this onto your phone, connect your iPhone and open up iTunes. You'll need to find the file menu, which you can do by clicking on the icon in the top left of iTunes and choosing "Show Menu Bar" or alternatively just press Ctrl + B. Go to File > Add Folder to Library… and choose the folder in the output folder called YourApp.app. You should now be able to sync the application to your phone from the apps screen.

Common Errors:
  • Make sure your output path is not within your projects directory
  • Make sure all the paths in your config file are correct
  • Make sure you have the path to the Java JDK in your user PATH variable (editable through Environment Variables)
  • Make sure you have a system variable called JAVA_HOME that points to the Java JDK (editable through Environment Variables)
  • Make sure to link to your Android SDK correctly (also make sure you have the Android SDK if building for Android!)
That's it! If you run into any troubles, leave a comment below. As promised, here is my config file:

{
/**
* @cfg {String} applicationName
* @required
* This is the name of your application, which is displayed on the device when the app is installed. On IOS, this should match
* the name of your application in the Apple Provisioning Portal.
*/
"applicationName":"AppName",

/**
* @cfg {String} applicationId
* This is the name namespace for your application. On IOS, this should match the name of your application in the Apple Provisioning Portal.
*/
"applicationId":"com.joshmorony.appname",

/**
* @cfg {String} bundleSeedId
* A ten character string which stands before aplication ID in Apple Provisioning Portal
*/
"bundleSeedId":"XXXXXXXXXX",

/**
* @cfg {String} versionString
* @required
* This is the version of your application.
*/
"versionString":"1.0″,

/**
* @cfg {Object} icon
* For iOS, please refer to their documentation about icon sizes:
*
*
* For Android, please refer to the Google Launcher icons guide:
* http://developer.android.com/guide/practices/ui_guidelines/icon_design_launcher.html
* iOS uses 57, 72, 114 and 144; Android uses 36, 48 and 72; if you package for Android you can ignore iOS icons and vice verca
*/
"icon": {
"36":"resources/icons/Icon_Android36.png",
"48":"resources/icons/Icon_Android48.png",
"57":"resources/icons/Icon.png",
"72":"resources/icons/Icon~ipad.png",
"114":"resources/icons/Icon@2x.png",
"144":"resources/icons/Icon~ipad@2x.png"
},

/**
* @cfg {String} inputPath
* @required
* This is location of your Sencha Touch 2 application, relative to this configuration file.
*/
"inputPath":"./build/appname/package",

/**
* @cfg {String} outputPath
* @required
* This is where the built application file with be saved. Make sure that output path is not in your input path, you may get into endless recursive copying
*/
"outputPath":"../build",

/**
* @cfg {String} configuration
* @required
* This is configuration for your application. `Debug` should always be used unless you are submitting your app to an online
* store – in which case `Release` should be specified.
*/
"configuration":"Debug",

/**
* @cfg {String} platform
* @required
* This is the platform where you will be running your application. Available options are:
* – iOSSimulator
* – iOS
* – Android
* – AndroidEmulator
*/
"platform":"iOS",

/**
* @cfg {String} deviceType
* @required
* This is device type that your application will be running on.
*
* If you are developing for Android, this is not necessary.
*
* Available options are:
* – iPhone
* – iPad
* – Universal
*/
"deviceType":"Universal",

/**
* @cfg {String} certificatePath
* This is the location of your certificate.
* This is required when you are developing for Android or you are developing on Windows.
*/
"certificatePath":"certificates/appname_p12.p12″,

/**
* @cfg {String} certificateAlias
* This is the name of your certificate.
*
* IF you do not specify this on OSX, we will try and automatically find the certificate for you using the applicationId.
*
* This can be just a simple matcher. For example, if your certificate name is "iPhone Developer: Robert Dougan (ABCDEFGHIJ)", you
* can just put "iPhone Developer".
*
* When using a certificatePath on Windows, you do not need to specify this.
*/
"certificateAlias":"Joshua Morony",
/**
* @cfg {String} certificatePassword
* The password which was specified during certificate export
*/
"certificatePassword":"***************",
/**
* @cfg {String} provisionProfile
* The path to the provision profile (APP_NAME.mobileprovision) which you can create and then download from Apple's provisioning portal
*/
"provisionProfile":"certificates/embedded.mobileprovision",
/**
* @cfg {String} notificationConfiguration
* Notification configuration for push notifications, can be "debug", "release" or empty if you don't use push notifications in your project.
*/
"notificationConfiguration":"",

/**
* @cfg {Array[String]} orientations
* @required
* This is orientations that this application can run.
*/
"orientations": [
"portrait",
"landscapeLeft",
"landscapeRight",
"portraitUpsideDown"
] }

Check out my latest videos: