This tutorial provides instruction on setting up PhoneGap for your web application on the iPhone.
Requirements
- Macintosh computer with Xcode and the iPhone SDK installed.
- iPhone.
- iPhone developer certification. (only necessary to install on iPhone)
Step 1
- b) Open the iPhone project included in the download in Xcode (project file now called PhoneGap.xcodeproj)

- c) Open info.plist and change "BundleIdentifier" to the identifier provided by Apple. If you have a developer license, you can access and run the Assistant at http://developer.apple.com/iphone/manage/overview/index.action and register your App. The bundle identifier should be setup to
be a reverse domain like com.yourcompany.yourapp. Put that in the plist "BundleIdentifier" field. BundleIdentifier can be a string of numbers such as *.5364647 . If you do not have a developer license and simply wish to test phonegap on your desktop simulator, you can skip this step.
-

- Go to the menu Project > Edit Project Settings
- Click on the Build tab. Make sure the Configuration
menu says "All Configurations" menu says "Debug" (I found I had to use the 'Debug' setting otherwise I was getting a gray out 'profile doesn't match Application Identifier' error) and the Show menu says "All Settings".
- Go down to the Code Signing section on the Build tab. Change 'Code Signing Identity' to your info, then change the sub-item to your info as well (probably says "Any iPhone OS Device").
- Go down to the Packaging section on the Build tab. Change the Product Name to "PhoneGap"
- Change the Prefix Header (under GCC 4.0 - Language) (called 'Executable Prefix' in the packaging section of the build tab) to PhoneGap_Prefix.pch
- Close the Edit Project Settings window and choose Save All when prompted.
- Build and run.

Step 2
- Open info.plist and change "BundleDisplayName" to the name of your web application.
- Replace icon.png with your web application's icon 57 by 57 pixels.

- In PhoneGap.plist,
change Offline to 0 and set Callback to the URL you want your application to load. Callback and URL.txt no longer exist in current Phonegap version. Use the index.html file in the WWW directory.
- Change default.png 320 by 480 pixels. (optional)
Step 3
Build your web application at the location listed in url.txt URL.txt no longer exists in current Phonegap version. Place your web app in the WWW directory.
- Change default.png 320 by 480 pixels. (optional)

-
-

Comments (Show all 49)
thikonom said
at 5:37 am on Apr 7, 2009
How can i start writing an app on iphone but in windows?Is there a same tutorial but for windows?I ve download the james douma simulator but what else should i do to start?
Helpppp
Jerry said
at 7:35 am on Apr 11, 2009
I followed the directions but I get "Failed to launch simulated application: Unknown error."
When I look at the Errors and Warnings there too many to count. I'm running Simulator - 2.1 |Debug
Also tried with Simulator - 2.0 |Debug - same result
I followed the above instructions although I couldn't find the entry for PreFix Header
davidgo said
at 5:52 pm on Apr 23, 2009
For the above readers - PhoneGap does not save you from the conventional path of iPhone bureaucracy, which you still have to follow to get things working. In short, start by:
1. Visiting http://developer.apple.com/iphone
2. Creating a developer account (this part is free)
3. Downloading the iPhone SDK
Now you can open the project in xcode and test using the iPhone Simulator.
Additionally, if you want to install your app on an iphone, you will need to:
4. Purchase an iPhone Developer Program certificate (this costs you $99 and can take weeks or months for approval)
5. Create an application in the Developer Program Portal, and follow the instructions there. You'll get the BundleID from Apple if you follow those steps closely.
This process is a royal pain, but it's liberally documented elsewhere. Good luck!
bitnaut said
at 9:48 am on Apr 29, 2009
I managed to finally get this to compile (for some reason Glass.app was still referenced in the project even though no one was building it) under the 3.0 SDK beta 4 but it just crashes randomly when I run it. How have people actually made running apps with this thing? It seems so buggy.
anywherestudio said
at 11:31 am on Apr 29, 2009
I don't think it's set up to work with 3.0 yet, they're probably (wisely) waiting for the final release before they update.
Jay said
at 11:03 pm on May 3, 2009
When I load it on the iPhone, the app displays the Default.png image, shows the buttons for a second, and then crashes... any thoughts on why that might be the case? 1st gen iPhone. Also, is callback url necessary? The wiki post says it's in url.txt but appears to be in PhoneGap.plist
Ralf Rottmann said
at 9:26 am on May 13, 2009
Downloaded the latest package (as of May 13th 2009) via Git. Fresh clean install. "Glass.app" is still referenced and could not get this working. Neither by cleaning the entire project nor by any possible setting. Getting started failed, for me. Any help?
Josiah said
at 11:20 am on May 13, 2009
@Ralf Rottmann:
Check this thread about your Glass issue:
http://groups.google.com/group/phonegap/browse_thread/thread/bf1e2e3b0ded453c/ce2f2bf8cd2064b6?lnk=gst&q=latest+glass#ce2f2bf8cd2064b6
Ralf Rottmann said
at 11:35 am on May 13, 2009
Thanks for your comment. Did not solve the issue, though. I meanwhile found a solution myself and posted it for everybody else here:
http://www.24100.net/2009/05/phonegap-and-iphone-sdk-30-no-launchable-executable-present-at-path/
You can contact me via Twitter: http://twitter.com/ralfrottmann
Hope this helps. Keep up the good work!
SteveT said
at 9:50 am on May 16, 2009
I'm new to macs and xcode development. Do I need to make a copy of the iPhone project for every app I'm going to write? Maybe I missed it elsewhere on this site but is there also a list of files under the project directory that I don't need and can remove? Is it necessary to follow the instructions elsewhere to rename the project so it doesn't have any references to phonegap before submitting my app for approval? Any help would be welcome.
Mihai Radulescu said
at 3:00 am on May 29, 2009
I just try to connect to the gid repository using "git clone git://github.com/sintaxi/phonegap.git" and I get a :
Initialized empty Git repository in /labo/playground/phonegap/phonegap/.git/
github.com[0: 65.74.177.129]: errno=Connection timed out
fatal: unable to connect a socket (Connection timed out)
Mihai Radulescu said
at 3:04 am on May 29, 2009
More I try to download a tar (and a zip) and I try to search the gap.js file but there is no such file. I need this because I want to do the "Building your first mobile application with GeoLocation".
Do I miss something here ?
Charles Lawrence said
at 8:28 pm on Jun 1, 2009
The documentation on this page needs to be fleshed out ALOT. It might seem like old-hat to people who have been doing this for a while, but for someone completely new to trying to set this up, this is missing a lot of pieces. The first case in point is about the Bundle Identifier. 1) Its *not* well documented elsewhere. If I search on "iphone bundle identifier" and don't find any how-to information in the first 6 pages of Google, its not well documented. 2) I ended up going through the assistant on http://developer.apple.com/iphone/manage/overview/index.action and at no point does it tell you "Here's your Bundle Identifier". It generates a random code that looks nothing like com.domain.appname. After hunting and pecking around for 20 minutes, someone said this code is the bundle identifier.
Vineel Shah said
at 7:30 pm on Jun 2, 2009
I found my bundle identifier by opening my ".mobileprovision" file in a text editor and found the value in the "application-identifier" part of the xml. It looked like this:
<key>Entitlements</key>
<dict>
<key>application-identifier</key>
<string>3LL12K7IKZ.*</string>
<key>get-task-allow</key>
<true/>
<key>keychain-access-groups</key>
<array>
<string>3LL12K7IKZ.*</string>
</array>
</dict>
( I changed my idenfier of course, but that's what it looked like." )
My ".mobileprovision" file was created as part of the "provisioning" process that tied my iPhone to my App and my developer account from Apple. I did this on a Macbook Pro running 10.5.7.
simon said
at 7:35 am on Jul 7, 2009
How can i transform my developed widget to iphone, android and blackberry?
Sorry i'm new with phonegap.
I have 3 files: html,js and css for my widget. And now i want create the application for this 3 platforms.
Or does anybody know a good tutorial, where is described how i can do this.
hari said
at 8:13 am on Jul 24, 2009
I downloaded the latest code... I cannot fine "CALLBACK" nor "OFFLINE" options in either PhoneGap.plst or Info.Plst or Settings.plst. ... How can I setup phonegap to load the page from my webserver. thanks,
Bruce Martin said
at 6:40 am on Jul 29, 2009
Ok, I'm lost, why is it complaining about the missing Glass.app? How do I resolve this when I build and run? Thanks.
Radu said
at 3:31 am on Aug 6, 2009
I tried to follow the steps but I ran into problems. First there's no Glass.xcodeproj, but PhoneGap.xcodeproj. So I thought I have a new version of phoneGap and this tutorial is based on an old version but that's not all. I can't find where I should modify the URL to point to my page. I can't find url.txt. I can't find any options like Offline or Callback in PhoneGap.plist. Do you guys have any idea? I installed phoneGap properly as far as I know (with make).
gburkell said
at 12:07 pm on Aug 12, 2009
I've come across the same problem as Hari:
"I downloaded the latest code... I cannot fine "CALLBACK" nor "OFFLINE" options in either PhoneGap.plst or Info.Plst or Settings.plst. ..."
Does anyone know where this is? I must also state I am quite new to programming and to iphone programming so I am sorry if this is a simple question...
iPhoneism said
at 4:12 pm on Aug 25, 2009
Same problems as above. No callback or offline found. Also no url.txt?
Daniel Triphaus said
at 9:41 am on Aug 28, 2009
There is no setting anymore. The application has to be on the phone in the asset-folder, but you can make (even cross-domain) ajax-requests to external servers.
Daniel Triphaus said
at 9:43 am on Aug 28, 2009
Oh sorry, of course it has to be in the www-folder on the iphone!
Ramakant Kulkarni said
at 3:17 am on Sep 2, 2009
Looks like there is a gotcha in the Contacts.m class. This happens if you have a contact on your phone with First Name, Last Name and Email and NO phone number specified (which to me is a valid scenario). You also need to enable the "Get Fourth Contact" button in the example (not sure why it's hidden) by commenting the style for that particular DIV:
<div id="Page2"> <!--style="display: none"-->
The Contacts.m class craps out at line 50 as below:
CFStringRef phoneNumber = ABMultiValueCopyValueAtIndex(ABRecordCopyValue(ref,kABPersonPhoneProperty) ,0);
The app worked just fine once I deleted the contact in concern.
Alan said
at 6:02 am on Oct 13, 2009
@ Daniel Triphaus... How do you do cross-domain ajax requests to external servers? As far as I can tell that is not allowed by any browsers and my attempts have not worked. I'll be honest, I was very excited about the potential of phonegap, but not being able to load external sites is a huge let down.
Martijn Pannevis said
at 7:22 am on Oct 13, 2009
Cross domain AJAX is possible with JSONP. Also the iPhone isn't too strict on "same domain", so normal AJAX requests also seem to work..
Jonathan Lister said
at 8:56 am on Oct 13, 2009
Anybody have any working code to show cross-domain Ajax going on?
J.
Jonathan Stark said
at 9:22 am on Oct 13, 2009
You don't have to do anything special to get cross-domain Ajax working. The cross-domain restriction does not exist when called from a page loaded with the file:// protocol. IOW, if you make a web app on your desktop and open it in a normal desktop browser, you can retrieve data directly from whatever APIs you like (e.g. google, twitter, flickr, etc...).
Since phonegap opens your index.html file using the file:// protocol, you can make normal GET and POST requests to whatever URLs you want and it will just work. I'm working on an app that accesses the Twitter API (via both GET and POST) and I can assure you that it works.
Alan said
at 4:43 pm on Oct 15, 2009
@Jonathan Stark - could you please give an example of cross-domain Ajax working? I have tried it with Jquery with no success from a local file. Here is the code I used:
$("#content").load("www.remote-domain.com");
Thanks for any help you can provide!
Michael Nachbaur said
at 4:49 pm on Oct 15, 2009
@Alan - You might want to consider using an actual URL. The "http://" is important. You should try it.
Alan said
at 5:20 pm on Oct 15, 2009
Sorry about that, I did use http:// I just forgot to put it in this example. So, I ditched JQuery and tried a basic XMLHttpRequest, but still no results... anyone have any input?
req = new XMLHttpRequest();
req.open('GET', 'http://www.remote-domain.com', true);
req.send();
Alan said
at 5:26 pm on Oct 15, 2009
so, what is the purpose behind phonegap if you can't load up remote websites with ease? Don't most people build sites using server-side languages such as php or asp instead of html files? Also, what benefits does phonegap offer over just loading up a UIWebView with a remote url? Thanks for all the help!
Michael Nachbaur said
at 5:47 pm on Oct 15, 2009
@Alan - At this moment I'm actually working on an iPhone app for a client that *heavily* leans on the use of XMLHttpRequest to communicate with a remote server. It is indeed possible, though it might depend on various factors. For instance, are you sure your JavaScript is running? Are you sure the host is up? Is your code being run? When your PhoneGap runs on the phone, or in the simulator, you have very limited access to run-time information.
I'd advise you look into the debug.log and other companion methods for logging to the XCode debug console. I'd also ensure you're using the latest codebase from http://github.com/phonegap/phonegap (as sintaxi's codebase is no longer the official repository, but is rather one of the developers of the PhoneGap project).
Alan said
at 6:35 pm on Oct 15, 2009
@Michael Nachbaur - Ok, I was testing in Firefox, which turned out to be the problem. I was able to test in Safari and it worked... kinda. Pulling in a complete remote site does not work well because none of the resources could be found, I'm guessing this is because the remote site is not using absolute url's for every resource, but that's unreasonable. I guess, I'm going back to my previous question... if phonegap can't load up a remote site, what is it good for? I rely heavily on c# .net code that cannot run locally.
Michael Nachbaur said
at 6:47 pm on Oct 15, 2009
@Alan - Let me put it this way. Almost all mobile platforms (worth developing for) have WebKit, which is what Safari is based on. And between the different implementations there's enough differences that makes compatibility between Android and iPhone (or iPhone 2.2 vs 3.0) enough of an issue that you have to be cautious. Testing on Firefox? Good luck.
So, PhoneGap can communicate with a remote site via Ajax calls. The iPhone application is still an application. Don't think of it as just yet-another web page. It's an app that runs on a machine that has very limited CPU and memory resources. Communicate with a remote site all you like, just don't expect the iPhone app you create with PhoneGap to be a simple web page.
Wuff said
at 7:39 pm on Oct 15, 2009
@Alan - when you use AJAX, you'll just be pulling in the web-server's response for that actual URL. This could be good for accessing an API (eg. JSON objects), an RSS feed, or XML or HTML page if you know the structure of the data on that page. Then you can make your own app (in PhoneGap's own webkit 'window') present that information differently - presumably in a more mobile-friendly, native-feeling interface (using Javascript to parse the incoming data and present it).
(On that topic, though - I'm curious - if a server requires a login and keeps a cookie or session variable for persistance - can AJAX be used still? Is there some way to catch the server information about setting cookies, and send the appropriate tokens back in subsequent AJAX calls to the same server?)
Alan said
at 8:27 pm on Oct 15, 2009
@Michael Nachbaur - I sense a bit of tension in your response. I apologize if I have ruffled any feathers. Testing in firefox was simply a mistake since I'm so used to using it for everything I do. As far as the iPhone running apps and not web pages, I understand that, but honestly, I thought that was what made PhoneGap different. I thought it gave the ability to wrap up a site into an app with very little work. Unfortunately, you are telling me I need to build a website that is strictly html and javascript that pulls chunks of data from a remote service via Ajax. I understand that, it just turns out that this is not the product I was looking for. Once again, thanks for the quick responses!
Chris said
at 1:44 am on Oct 20, 2009
Sorry, I feel this article is not a Getting started Guide anymore, it is too outdated and I just cannot get started at all. I download the lastest source, build it an run it, but find no way to change the HTML layout, not even on static content. Should I simply edit index.html? I tried, but it failed to update to the iPhone application after re-built, it had no effect at all. Can someone just tell be how to create a simple Hello World application, please ?
Becky said
at 10:23 am on Oct 21, 2009
I have to agree with Chris - this is definitely missing some details - especially for newbies to Xcode and iPhone development. I'm willing to put in some extra time to try and figure out the details, but there really aren't many other places to look. Here are my points of confusion:
From further reading, it seems there is no longer a url setting as I can put my web pages in the www directory.
When I load the project into xcode, I can't find the phonegap.js file anwhere. Should I be able to see all of the js files in xCode?
I can build this app but it won't install into the 3.1 simulater - unknown error as reported by Jerry in April (although my build is clean).
I am using 0.8.0 release from 10-13-2009
Any suggestions?
thanks!
Becky said
at 11:01 am on Oct 21, 2009
OK, I guess I just had to complain. I can get this working on my device (3.1.2) but just not in the simulator. I'd like to be able to use the simulator for testing as much as possible so any ideas about getting that to work would be appreciated. I'm still interested in the location of the js files in xcode, though.
Chris said
at 9:21 pm on Oct 21, 2009
Although I am still very confused with many things, I manage to build and run the sample application in iPhone simulator 3.0. Maybe it is not compatible with the 3.1 simulator.
You don't have permission to comment on this page.