Note: I’ve added a ChildBrowser example to the PhoneGap Starter project. It won’t help with native issues, but if you’re using PhoneGap Build it might give you a working head start.

I’ve seen a bunch of people who are new to PhoneGap/Cordova struggle with getting the ChildBrowser up and running. I fought with it today as well and most of my mistakes were based on old blog posts so I wanted to do a quick post that hopefully shows up in Google for people running into the same problems I had.

I’m starting with a blank project. The ChildBrowser plugin I’m using is here which as of this writing has been updated to support Cordova 1.5 with some potential backwards compatibility with 1.4.1. The simplest thing is to probably just download the source as a zip.

I’m starting with a blank project that has my www folder already referenced by the project. Here are the rest of the steps.

1. Drag all of the .m, .h, and .bundle file(s) from the ChildBrowser folder to the Plugins folder of your project. Make sure the copy option is selected (I think it’s the default).

2. In your project, under the Supporting Files folder, open the Cordova.plist file. You’ll see a bunch of key/value pairs and the one you want is under Plugins. You’ll need to add 2 by clicking the add button that shows when you highlight the Plugins section.

Key: ChildBrowser, Type:String, Value: ChildBrowser.js

Key: ChildBrowserCommand, Type:String, Value:ChildBrowserCommand

3. You also need to make sure that your application can call the external URL you want to load. This is also handled in the Cordova.plist file under ExternalHosts. Add any of the URLs you plan to open to that. You just need the Value, so you can leave the Key as the default. And remember that you can use wildcards, so the entry below lets you go to any subdomain of Google.

Key: Item 0, Type: String, Value: *.google.com

4. Copy over ChildBrowser.js (or the minified version) from the project files to your www folder.

Now you need to go into your HTML and JS files and make some changes. The biggest one is to reference the ChildBrowser.js file.

<script type="text/javascript"charset="utf-8"src="ChildBrowser.js"></script>

And here’s the modified JavaScript I used to get it to work. I created a childbrowser variable, then in onDeviceReady added a call to the install method of the ChildBrowser object. Finally I created a function that handles the URL opening.

    var childbrowser;
 
function onBodyLoad()
{
document.addEventListener("deviceready", onDeviceReady, false);
}
 
function onDeviceReady()
{
// do your thing!
childbrowser = ChildBrowser.install();
navigator.notification.alert("Cordova is working")
}
 
    function onLinkClick() {   
 
    if(childbrowser != null)
    {
        childbrowser.onLocationChange = function(loc){ alert("In index.html new loc = " + loc); };
        childbrowser.onClose = function(){alert("In index.html child browser closed");};
        childbrowser.onOpenExternal = function(){alert("In index.html onOpenExternal");};
 
        window.plugins.childBrowser.showWebPage("http://google.com");
 
    }  
}

This definitely works with Cordova 1.5 and I’m pretty sure it should work with 1.4. Notice that there’s no need to change any of the .m/.h files, so don’t worry about importing anything or changing code that you may have seen in other blog posts.

And I’m pretty sure this is basically how all Cordova/PhoneGap plugins work. Simply copy the OS-specific files into the plugin directory and then copy the JS files and reference them. But ChildBrowser threw me for a loop because of all the blog noise that referenced past versions. So hopefully this helps someone.