Preliminary warnings ...
First, do not worry in the manual official update of documents . This will help you upgrade from 1.0 to 1.1, then from 1.1 to 1.2, then from 1.2 to 1.3, etc. If you want to jump over several versions, you do not know if you are doing the right thing. Therefore, when upgrading, create a new project from scratch.
Also, jump ahead to make sure you're not stuck in this process: if your preg 3.0 Phonegap application uses custom plugins, think very carefully if you want to upgrade at all. Scroll forward to “Beware of custom plugins” to see why.
Step by step
Having said that, this is a step-by-step process divided by lines.
1. Command line
Phonegap 3.0 is a command line tool . It looks a lot worse than it really is. You just need to install several tools that you will use there (basically by typing a command on the command line).
The most important commands you need to know are:
//For Mac and Windows (on Windows, replace slashes by backslashes) cd mySubfolder //Go to the subfolder "mySubfolder" cd /MyTopLevelFolder/SomeOtherSubfolder //Go to any folder using the entire address //Show a list of files and subfolders where you currently are dir //On Windows ls //On Mac
2. Be in the right place
The most important aspect of the command line tool is that you always need to pay attention to where the directory is located . Notify that Phonegap for creating and deploying your application will only work if you are in the main folder for this application.
It is wise to do something with your Phonegap project, you need to go to the project’s home directory using:
cd /Users/yourself/thePathToYourWorkspace/YourCurrentPhonegapProject //On Mac cd D:\ThePathToYourWorkspace/YourCurrentPhonegapProject //On Windows
3. The path to enlightenment
PS: To make sure that the tools you install run correctly, you sometimes need to tell the computer that it should look in several additional directories if it cannot find the file in the current directory. You are editing something called the path variable. See that elsewhere, this is not too complicated, but it is different for Windows and Mac.
4. First select the toolbox toolboxes
To get started, the basic documents are in order. You download and install node.js , which is a tool that will be used by other tools, then use it to install the phonegap / cordova command-line tool .
//Like so, for Mac $ sudo npm install -g phonegap //Note: the "sudo" bit is needed to install a number of necessary files in folders that Apple protects from direct user editing
From now on, you can use the "phonegap" command to perform a number of tasks for your project.
5. Open the workspace
The first thing you need to do is create a workspace that is a common word for the main folder for all your projects (you can do this using Windows Explorer, Finder, or any other user, too, friendly).
For Windows in particular, try to make sure that you can enter the entire path to this folder without spaces. Therefore, never put your workspace in a place like "My Documents", especially since it is a subdirectory of C: \ Documents and settings \ John Doe \. Instead, try something like "D: \ Workspace \".
If you are already using Dropbox for other purposes and not too much trouble to change the location of the Dropbox folder, consider using it to automatically back up your workspace. Just put the Dropbox folder in the D: \ directory or another root directory of the drive. Then add Workspace as a direct subfolder of Dropbox.
Using Dropbox very often can interfere with your development time if file synchronization is in your project. But as a result, you have an automatic backup of many versions of your files: all versions on the current day, some versions yesterday, one version every day earlier.
6. Create your project
Then change to the workspace directory in the command line console using the cd . When you specify Phonegap to set the basic structure of an empty application using the command
$ phonegap create hello com.yourCompanyName.yourAppName HelloWorld
This will create the HelloWorld folder and populate it with several subdirectories of files that are the foundation of your application.
7. Apply it to the woods.
Then you go on to fill this structure . Basically, your application will be a bunch of HTML, CSS, and Javascript files. They are in the main www folder. This folder also contains the config.xml file, which contains many settings for your application, for example, which icon to use, what name to show, show or not to show the Android status bar, which domains to whitelist, etc.
Phonegap combines these files in the / www directory, so you have all your “editable” things. If you do not have your application to do something unusual, like using plugins, then you are good to go.
8. Whitelisting the right way
If any part of your application actually accesses the Internet, even if for something like Google Analytics, you should tell Phonegap a whitelist of the corresponding domain names. As stated above, this is done using tags in MyProject \ www \ config.xml.
This is a complex business because Phonegap has problems with differences between platforms on this issue.
For Android (using Google Analytics as an example), add your domains to the white list as follows:
The reason you add this domain twice is because many online services start with the simple unchecked protocol http: //, but some of their functions can subsequently receive or send code from / to the secure address https: // to same domain.
An asterisk is important because you want to be able to download scripts and other materials from ** www. ** google-analytics.com, as well as from the main site google-analytics.com or any subdomain.
9. Insert additional features
If your application requires special functions (material on which Android will ask users for permission, for example, access to a phone or contact book or to a camera or accelerometer), you need to install plugins in the application project.
Check out the docs here to see how to do this.
Also, make sure you add a line to config.xml that tells Phonegap not to ask for any unnecessary permissions:
<preference name="permissions" value="none" />
The docs say this means that you only ask for one permission (network access), but that’s not entirely true. Example: if you installed the plugin for the camera, the application will ask the user for permission to access the camera, regardless of whether you added the above value = not a single preference tag. The same goes for all other functions / permissions.
10. Beware of custom plugins
In addition, and this seems to be a bug in Phonegap, no matter what your plugins and permission settings are, the application will always try to get three other permissions : RECORD_VIDEO, ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION.
Phonegap simply puts them in the Android manifest, as if you had specified it somewhere. When you create the application for the actual release in the app store, you will need to fix it. How: you edit your AndroidManifest.xml right after your last build, but before signing and releasing the package.
This way you get these nasty permissions. But you must repeat this every time you upload a new version of the application to the application store!
Besides standard plugins, Phonegap has always had many third-party custom plugins. The way they are installed in Phonegap 3.0 is completely different from the previous ones. Lazy experts who already know the exercise say that "this is exactly the same as installing kernel plugins," but no one bothers to give an example anywhere.
If you know how to translate the installation process of the pre-3.0 plugin into the 3.0+ process, add a comment and I will copy it in this guide.
When you are ready to start testing your application, first connect your device (or install an emulator). These commands will be most useful, and not all well-documented ...
$ phonegap build android
Then, when the application does exactly what you want, and you are ready to put it in the application store, you need to take the last few steps to create an application package (.apk) ready for storage .
You need to install 'ant'. In my case, installing everything else means that ant was also automatically installed, and this will probably be the case for you. ant is a tool for creating packages (my dumb conclusion, not a verified fact).
11. Go to where the ant goes
So far, you have shot commands in the command line console from your project home directory. Now, however, you will want to work with the Android apk that you created with these commands, and ant does not know how phonegap does where they can be found.
So, go to the subdirectory ...
cd platforms/android //This is a subdir of blabla/workspaces/myproject.
This is the location of your "wrapper application" of the Java Java application for the HTML / CSS / Js material that you created.
12. Get ready for release
If you need to make changes to the application for the last time (for example, delete strange permission requests from AndroidManifest.xml), do it now. Be sure to edit the AndroidManifest.xml file in the / platform / android folder, and not in / platform / android / bin.
Some changes you have to make due to errors in Phonegap:
- remove unwanted permission requests
- set the version code manually (
Phonegap sets it to 1 , even if you specified otherwise in the config.xml file)
13. Release the ants
If you are really ready to put your stuff in the app store, just run this command. Be prepared for mistakes: you can do these steps at one point easier than I put the whole if-then process in this guide.
ant release
When ant is running, you should find a file called YourAppName-release.apk in the / Platforms / Android / bin folder. This is a file that you can upload to Google Play.
14. Probable problems with the "ant release" ...
a. The application requires a secret key
The key is stored in a private keystore (file). If this is not your first version of the application, get this information from where you saved it and place it in a simple, easy-to-write place, such as D: \ Developer \ Keystores. If this is your first version of the application, create a key.
B. ant cannot find your key
Ant doesn't know where to look for this keystore, so you need to edit the file in the platforms / Android directory to point it in the right direction. The file is called ant.properties. Add these properties using a text editor:
//Point it to the right directory: key.store=/Users/Me/Dropbox/Developer/Keystores/keystoreForMyFirstApp //For Mac key.store = D:\Dropbox\Developer\Keystores\keystoreForMyFirstApp //For Windows //This describes the name of your signing key, as stored in the keystore key.alias=FirstKey
Now you can be ready to place the apk file on Google Play or in another Android store. I was not exhaustive, but these steps must go a long way. Comments are welcome!