Installing ChildBrowser into Xcode 4 with PhoneGap 1.0 (Mac OS X, Snow Leopard)

You’ll need the ChildBrowser plugin with PhoneGap in order to return to the app after clicking on an external link. A Done button will appear under the web page, allowing you to exit the web page and return to the app. Very convenient. I’ve had to search and experiment for two weeks before I could piece all the correct steps together. If you landed here early, you can do it all within an hour!

UPDATE 6/5/2012: For PhoneGap-Cordova 1.7.0, use these steps to install ChildBrowser:

UPDATE 3/21/2012: For PhoneGap-Cordova 1.5, use these steps to install ChildBrowser:


Naming a part a “plugin” sounds so innocuous. Just plug it in and it works! Not in this case. If you do not know enough Javascript to finish someone elses work, like me, you’ll have a hard time with this plugin. And if you do not know enough Objective-C language skill to adapt an Objective-C page, then you are really lost – at least with this “plugin.”  If you’ve been attempting to make this plugin and are tearing your hair out, now you know the source of your pain. Here’s the medicine.

1. To download the Childbrowser plugin, visit and click on iPhone/, then Childbrowser/ , then Downloads. I chose the zip option. I dragged the folder from the Downloads folder to the Documents folder in Finder and renamed it phonegap-plugins.

2. Open your Xcode 4 project that already has PhoneGap 1.0 installed and working. (I wrote an earlier post on how to do this.)

3. Right-click on the Plugins folder in Xcode and select to “Add Files to…” the folder.

4. Navigate to the phonegap-plugins > iPhone > Childbrowser folder, and select the ChildBrowser folder. Check “Copy items into. . .” and “Create groups for. . .” A ChildBrowser folder is added to the Plugins folder.

5. Copy/Paste the ChildBrowser.js file from the Childbrowser folder to the www folder from within Finder (not in Xcode).

6. Put this in the head of the index.html file in the www folder BELOW the line for phonegap.1.0.0.js:

<script type=”text/javascript” charset=”utf-8″ src=”ChildBrowser.js”></script>
<script type=”text/javascript” charset=”utf-8″>
var root = this;

/* When this function is called, PhoneGap has been initialized and is ready to roll */
function onDeviceReady()
var cb = ChildBrowser.install();
if(cb != null)
cb.onLocationChange = function(loc){ root.locChanged(loc); };
cb.onClose = function(){root.onCloseBrowser()};
cb.onOpenExternal = function(){root.onOpenExternal();};



function onCloseBrowser()
alert(“In index.html child browser closed”);

function locChanged(loc)
alert(“In index.html new loc = ” + loc);

function onOpenExternal()
alert(“In index.html onOpenExternal”);

(If you see any error circles to the left after pasting in, you’ll need to highlight the quotes or double quotes and redo them in Xcode. The quotes copied from this post may be Windows encoded and need to be overwritten in Xcode. I had to do this when I followed by own post at a later date.)

7. In Supporting Files > PhoneGap.plist, add under Plugins (click the down arrow to the left of Plugins, then click on the + symbol to open a new row):

Key: ChildBrowserCommand
Type: String (default)
Value: ChildBrowserCommand

Key: ChildBrowser
Type: String (default)
Value: ChildBrowser.js

8. You need to associate your external URLs on this page, too. In Supporting Files > PhoneGap.plist, add them under ExternalHosts, like:

Key: Item 0
Type: String (default)

(or whatever URL you need. I had the HTML page containing a lost list of external URLs side by side with the Xcode window and copied/pasted them over.)

9. Open Classes > AppDelegate.m, and add under the existing “#import” declarations but above the “@implementation AppDelegate” line:

#import “ChildBrowserCommand.h”
#import “ChildBrowserViewController.h”

so it looks like this now:

#import “AppDelegate.h”
#import <PhoneGap/PhoneGapViewController.h>
#import “PhoneGapViewController.h”

#import “ChildBrowserCommand.h”
#import “ChildBrowserViewController.h”

@implementation AppDelegate

10. Also in AppDelegate.m, scroll way down and replace the following:

– (BOOL)webView:(UIWebView *)theWebView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
return [ super webView:theWebView shouldStartLoadWithRequest:request navigationType:navigationType ];

with this:

– (BOOL)webView:(UIWebView *)theWebView shouldStartLoadWithRequest:
(NSURLRequest *)request navigationType:
NSURL *url = [request URL];
if ([[url scheme] isEqualToString:@”gap”] || [url isFileURL]) {
return [ super webView:theWebView shouldStartLoadWithRequest:request
navigationType:navigationType ];
else {
ChildBrowserViewController* childBrowser =
[ [ ChildBrowserViewController alloc ] initWithScale:FALSE ];
[super.viewController presentModalViewController:childBrowser
animated:YES ];
[childBrowser loadURL:[url description]];
[childBrowser release];
return NO;

11. Now you need to compose your external links properly. I have the following links (styled for iWebKit 5), which open a ChildBrowser window with a menu bar at bottom. Clicking on the Done button in the menu bar brings one back to the page containing the link. You can also tap the web page in the ChildBrowser window and it will resize to fit the screen.
List style:

<li class=”menu”><a href=”″&gt;
<span class=”name”>Rhythmic Calligraphy</span><span class=”arrow”></span></a></li>

Button style:

<a href=””><button style=”margin-left:10px; width:300px; height:40px; font-family:Helvetica;font-size:1em; text-align:left;”></button></a>

Once your links are correct, do a Project > Clean then a Run to test.

1. If you get this. . .

warning: no rule to process file ‘$(PROJECT_DIR)/Plugins/ChildBrowser/ChildBrowser.js’ of type sourcecode.javascript for architecture armv6 warning: no rule to process file ‘$(PROJECT_DIR)/Plugins/ChildBrowser/ChildBrowser.js’ of type sourcecode.javascript for architecture armv7

. . .then Delete the js files from the Plugins directory (“Remove Reference Only” – this will keep the files on disc, but out of the app).

2. If you get this. . .

Multiple build commands for output file /Users/ . . . /Build/Products/Debug-iphoneos/. . . .app/README.txt

…then go through the folders in Xcode and delete all the README files (choosing “Remove Reference Only” in the dialog – this will keep the files on disc, but out of the app).

3. Does tapping the Done button in Childbrowser show a blank screen? Check if this identifies and resolves the issue:

Specifically, change the following in Plugins/ChildBrowser/ChildBrowserViewController.m:


if(delegate != NULL)
[delegate onClose];
if ([self respondsToSelector:@selector(presentingViewController)]) {
//Reference UIViewController.h Line:179 for update to iOS 5 difference – @RandyMcMillan
[[self presentingViewController] dismissViewControllerAnimated:YES completion:nil];
} else {
[[self parentViewController] dismissModalViewControllerAnimated:YES];

to this:

if(delegate != NULL)
[self.delegate onClose];

if ([[super parentViewController] respondsToSelector:@selector(dismissModalViewControllerAnimated:)]) {
[[super parentViewController] dismissModalViewControllerAnimated:YES];
} else {
[[super presentingViewController] dismissViewControllerAnimated:YES completion:nil];


26 thoughts on “Installing ChildBrowser into Xcode 4 with PhoneGap 1.0 (Mac OS X, Snow Leopard)

  1. Thanks for the great tutorial. I was able to get the childbrowser plugin working.

    Two questions –

    #1 – Popup dialogs (navigator.notification.confirm…) now open the childbrowser. Do you know how to stop this

    #2 – Do you know of a way to suppress the childbrowser launch when going to an iTunes link like this –

    I have a button that users can press to rate the app in iTunes that worked with earlier versions of the childbrowser and Phonegap


    • “I don’t know” is my answer to both of your questions. I’m not versed enough in the plugin or Javascript to make any recommendations. You’ll want to go to the ChildBrowser authors and ask them directly. Sorry I couldn’t be more helpful.

  2. hi
    I am using phonegap 1.1.0 in xcode4.
    When I added a link using anchor tag in body of html file with “”, it opened but when I was trying to open a page from javascript in childbrowser it just show blank page (about:blank).

    this line did not work form me

    I have added all external links, and there is no warning in the project.


  3. Hi Steve. Thank you for the helpful post. Even with your very clear step-by-step instructions, I’m having problems with the Child Browser Plugin.

    I’m am using Phonegap 1.2.0 with Xcode 4.

    For some reason I’m unable to call the child browser using javascript. The code you’ve included above in step 6 to add to index.html should connect to but just launches a child browser page with about:blank. I can click “done” from the header of the child browser and then click the plain link to the YouTube video and that works fine — so it seems the Plugin is installed and initialized, but can’t be called with Javascript. Adding to my confusion is the fact that the logs show it trying to call but returns about:blank.

    I’m very new to IOS development and XCode, but it also struck me that the syntax for the lines you provide to include in the PhoneGap.plist in Step 7 don’t follow the same syntax as all the other entries which use variations of the reverse domain such as This may be fine or unrelated to the problem I’m having with the child browser plugin, but it caused me to pause when I got to it.

    Thanks again for your help.


    • As a partial answer to my own question, I figured out that the changes you recommend making to Appdelegate.m in Step 10 were causing my problems. I took those out and it now seems to work. Let me know if I’m losing something that will be needed later.


  4. I searched for many, many hours toiling over how to install and use this plug-in properly. THANK YOU for the clear, concise directions. My versions of PhoneGap and ChildController are the same as yours, so it all matched up perfectly. Wonderful, thanks.

  5. Great, you saved me, works like a charm with PhoneGap 1.3.0 and Xcode 4.2.1 !

    I now have a problem trying to set the default orientation to landscape, is this possible ?

    Thanks a lot,


  6. Hello again,

    Finalizing my app at last, the only thing I miss is the possibility to display local (app internal that is) PDF files in ChildBrowser ?

    Not sure how to do this so a bit of help would be much appreciated ;-)
    (this is my first app)

    • I’ve managed to do something but I don’t know why the address automatically changes to a about:blank :(

      I use this link : PDF

      (a javascript gets in the head the complete path to be encoded as un URI)

      But when I click on that link in the app, i see this in the console :

      2012-01-13 14:25:51.830 CRT-D[4644:707] View did load
      2012-01-13 14:25:51.835 CRT-D[4644:707] Opening Url : about:blank
      2012-01-13 14:25:51.870 CRT-D[4644:707] Opening Url : file:///var/mobile/Applications/32FE8551-284B-45FA-B48B-309809B7CE18/
      2012-01-13 14:25:51.883 CRT-D[4644:707] New Address is : about:blank

      What am I missing ? Why does the address changes at the last point before opening as it should ?

      • The PDF looks like a local file. It could be that your application or device does not have a PDF reader installed. Put the file on a server and access it through your app and see if it comes up in the ChildBrowser. If so, that may be the problem. You may need PDF reader software in your app. Unfortunately, I have no idea of how this is done with HTML/CSS/JS.

      • Hmmmm i Have an iPad with the native PDF view inside + even Adobe Reader installed, so not sure that’s the problem.

        I’m using here another dummy app and it works …

      • The reader has to be in the app, not outside the app, if you want to read an internal PDF. Evidently CB does not provide that.

        This make sense, though, doesn’t it? CB is made for PhoneGap, which handles HTML, CSS, and Javascript. It handles those file types, not PDF, txt, doc, etc.

  7. Well, I really not now where to check anymore, so if some one wants a little cash in order to find this issue, just let me know !

    ChildBrowser works and opens an external URL as it should, but if I want to open a local PDF file (I’ve tried several stuff found on the web) it loads the file (at least in the log) but immediately changes the address to about:blank :(

    2012-01-13 18:55:26.733 CRT-D[6067:707] View did load
    2012-01-13 18:55:26.739 CRT-D[6067:707] Opening Url : about:blank
    2012-01-13 18:55:26.773 CRT-D[6067:707] Opening Url : pdf/Performance-360-Anatomical-Reference-Guide.pdf
    2012-01-13 18:55:26.784 CRT-D[6067:707] New Address is : about:blank

  8. This worked in my other xcode projects. Just downloaded the new version of phonegap and it seems like this method no longer works…? Can you do an updated tutorial? That would be really great!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.