Shazron's Cordova (aka PhoneGap) Blog

at Adobe Systems Inc.

InAppBrowser (based on ChildBrowser) in Cordova 2.3.0

The inclusion of the InAppBrowser in iOS and Android will be new for Cordova 2.3.0. You can play with the InAppBrowser today if you download the latest code and help us test.

The InAppBrowser is a built-in web browser for your app that has an API that follows web standards. It follows the API, except for a new window target that we introduced: “_system“. Read our simple specification.

Does this mean the ChildBrowser is going away? Not really. These two plugins can co-exist, and ChildBrowser has added features that are not present in the InAppBrowser, particularly events. [UPDATE: see below]InAppBrowser also has no dependencies on a .xib or external images, so it is easy to integrate for upgrades.

What’s also new with the InAppBrowser implementation for iOS is, the white-list is not applied application wide anymore, the white-list will only apply for the main Cordova UIWebView only. Now you can load non-white-listed URLs into the InAppBrowser and the ChildBrowser.

There are several enhancements for plugins related to this new white-list exception functionality as well – please see issue CB-1889. The enhancements should land before the final 2.3.0 is released.

Please help us test by downloading the latest code or RC and giving this new feature a spin!

[Update Nov 28 2012]: The InAppBrowser on iOS has support for events now (Android in progress). You can listen to the ‘loadstart‘, ‘loadstop‘ and ‘exit‘ events. The callback function is passed an event object that has two properties: type, and url. You will need to grab the latest code and javascript (create a new project).

Example usage:

var ref ='', '_blank');
ref.addEventListener('loadstart', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('loadstop', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('exit', function(event) { alert(event.type); } );

// also, you can do ref.removeEventListener('loadstart', myfunc) .. etc

[Update Nov 30 2012]: Changes for InAppBrowser events for Android are in cordova-android now.

[Update Jan 7 2013]: If you have a multi-page app, and you use InAppBrowser, and you use iOS 6, you must use iframe bridge mode. More details here.

Written by shazron

November 21, 2012 at 8:06 pm

99 Responses

Subscribe to comments with RSS.

  1. Here’s a screenshot of what the UI looks like, it has a simple bottom toolbar: – here’s one with the location bar specified:


    November 21, 2012 at 8:28 pm

    • Sounds interesting! Can I load local html files with javascript accessing the cordova api in the AppBrowser? Or is the AppBrowser only considered to be a browser for external web pages? Can I pass JSON data to AppBrowser? I’m looking for a solution to the following scenario: From the main webview to open a second webview that can access the cordoa api via javascript. I need a second window to build a large web document with javascript. The user should be able to close the second webview and gets back to the main webview.


      November 23, 2012 at 3:01 pm

      • 1. Yes
        2. Yes
        3. Not currently – you can pass data through the File API I suppose.


        November 25, 2012 at 1:55 pm

    • this is not working. I took the files from the linked coded repo, drag & drop the bin to the termin and create the project. However,”_blank”) open in the same webview. Do I miss something?


      November 25, 2012 at 9:09 am

      • It is working. Make sure you call after the deviceready event like all the other Cordova APIs, and that you created a _new_ project with the new JavaScript included.


        November 25, 2012 at 1:54 pm

      • Did you ever get this fixed? Same thing is happening to me.

        Carlos Soto

        December 10, 2012 at 5:40 pm

      • Carlos, it is working. If you can post your sample project somewhere I can take a look.


        December 10, 2012 at 7:44 pm

      • Hi Shazron,

        Thanks for the reply, there are still links on the site redirecting to the wrong version I think:

        The article links to for the newest code. Shouldn’t this be by now?
        This could also explain why is not working for some people.

        Newest code works fine.

        Cool stuff,

        Carlos Soto

        December 10, 2012 at 8:52 pm

      • Ah yes, I thought I got all the links: corrected.


        December 10, 2012 at 9:02 pm

    • I try to load a local file in the InAppBrowser and the local file should have access in the InAppBrowser to the cordova api.I don’t get this to work. The deviceready event is not firing in the InAppBrowser.


      November 28, 2012 at 5:47 pm

      • Sorry, my mistake. The InAppBrowser cannot access the Cordova API, it does not have the hooks to do so in the native code.


        December 6, 2012 at 5:59 am

  2. Youtube videos continue to play even after browser is closed.

  3. An easy fix may be…

    LINE: 308

    – (void)close
    [self.webView reload];
    if ([self respondsToSelector:@selector(presentingViewController)]) {
    [[self presentingViewController] dismissViewControllerAnimated:YES completion:nil];
    } else {
    [[self parentViewController] dismissModalViewControllerAnimated:YES];

    By telling the webview to reload stops it.

  4. I have 2.3.0 running on xcode 4.5.2 and have an app working in the simulator.

    My code to init InAppBrowser is here:

    My code to call a PDF from the same page is here:

    When I run it in the simulator and tap the link, InAppBrowser displays, but is blank, and when I close it, the PDF is displayed in the window as if if had been navigated to. Here is a short video showing this:

    InAppBrowser is clearly working, but something is wrong. Can you advise?


    November 28, 2012 at 5:16 am

    • Hi Chad, I keep getting a download of zero bytes for the video. Took a look at your code — I assume the cordova-2.2.0.js is just a typo in there. Do you have a full example, perhaps with a link to an online PDF so we have the same conditions?

      Can you re-check the video upload? Not sure what is going on yet.


      November 29, 2012 at 1:57 am

      • Here, try the video here: password ‘video’.

        cordova-2.2.0.js is the cordova js file that was included in the package when I downloaded it using your ‘Please help us test by downloading the latest code’ link above. I never had 2.2.0 installed, I went from 1.6.0 to this version, 2.3.0. I figured since its a prerelease you hadn’t changed the version number on the file yet.


        November 29, 2012 at 4:12 pm

    • Was this issue ever addressed? I’ve been having trouble loading PDF files which are located on the phone/device. Thanks.

      Sean Riordan

      January 11, 2013 at 2:57 pm

      • Yes. See the latest Jan 7 update at the end of the updated post.


        January 11, 2013 at 7:20 pm

      • Thanks, just saw that. Didn’t realize those comments were connected – thought they were separate. I appreciate the information. On-device PDFs are going to make my project so much easier with InAppBrowser.

        Sean Riordan

        January 11, 2013 at 7:30 pm

  5. The article links to for the newest code. Shouldn’t this be by now?
    This could also explain why is not working for some people.


    November 29, 2012 at 3:55 pm

    • Yes, sorry — the repos were renamed a couple of days after the article was posted. Corrected now.


      November 30, 2012 at 1:54 pm

      • I have updated my cordova install and now have 2.3.0rc1.js, Thanks for that. However, I am getting the same results. The InAppBrowser is working, but the PDF is not loading inside of it. See the video for a visual: password ‘video’.

        My code to init InAppBrowser is here:

        My code to call a PDF from the same page is here:


        November 30, 2012 at 9:16 pm

      • Ah I see what’s wrong. You shouldn’t have a value in your href attribute, set it to “#”. What’s going on here is it launches the onclick handler (to InAppBrowser) and also loads the pdf in the main Cordova view (the href value)


        December 1, 2012 at 12:23 am

      • Thanks – I see what you are saying and have changed my code to work better, but I am getting the same result. I do have to leave the href value in due to the way this site is setup, but the code shown here should prevent the a from firing. Please take a look and let me know if you see anything I am doing wrong. Some of the new code comes from the same concepts as ChildBrowser.

        Revised HTML:

        Revised JS:

        Console in xCode when run in iOS sim: (the path to the file is correct and the file exists there)

        At this time I do not see the PDF load behind the InAppBrowser any longer, but the PDF is not loading in the InAppBrowser


        December 1, 2012 at 5:14 pm

      • Hi – still hoping to get a bit further support on this. I feel like I’m so close. Am I wrong in attempting to load the PDF from its full root location? I tried the web root and URL and those weren’t working either.


        December 6, 2012 at 4:43 am

      • Can you print out the actual path that is being passed to


        December 6, 2012 at 4:48 am

      • Thank you! The path sent to the console is /Users/Chad/Library/Application Support/iPhone Simulator/5.1/Applications/54FC9F4E-4E3A-491D-8225-9E31C18D5888/

        You can see all the relevant info from my comment above on 12/1/2012


        December 6, 2012 at 5:21 am

      • That is the first parameter to Won’t work then. It should be either a path that has a prefix protocol of http:// or file://

        If it’s inside of the current folder (www), the first parameter should just be “assets/documents/installation_guides/DU-WS-0001_Rev_J.pdf”


        December 6, 2012 at 5:26 am

      • Thank you – I was completely overengineering it based on what I had to do to get ChildBrowser working in the past. Your suggestion was correct, other than the page calling the PDF is 1 level down so it needed a ../ on the front. Thanks for your help!


        December 6, 2012 at 5:41 am

  6. […] details here. In a nutshell, this has the same functionality as the ChildBrowser, and has events support as […]

  7. Hi I found a bug for the childBrowser it’s probably also in the inapp browser.

    For URL contains unicode the URL can’t be open
    for example the following url wont open because it contains unicode:


    All url with unicode need to be encoded before pass to NSURL like this

    NSString* encodedURL = [url stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
    NSURLRequest* request = [NSURLRequest requestWithURL:[NSURL URLWithString:encodedURL]];


    December 14, 2012 at 9:53 am

    • We ran into this problem with FileTransfer. The problem with us encoding it is, if it is already encoded, you don’t want to encode it again — and detecting whether a string is already encoded is not reliable (too long to get into it here).

      For Unicode strings, my suggestion is to encodeURI() it first. Thus for, you would do:‘ハングル’), ‘_blank’);


      December 14, 2012 at 6:00 pm

      • That’s great thank you for the suggestion


        December 20, 2012 at 11:59 pm

  8. […] details here. In a nutshell, this has the same functionality as the ChildBrowser, and has events support as […]

  9. Is there a way to implement the “onLocationChange” event as ChildBrowser?

    Carlos Soto

    December 22, 2012 at 12:02 pm

  10. The InAppBrowser is a great feature addition! Thank you!

    Here is my question. Is it possible to use the InAppBrowser for links structured this way?:
    a href=”” target=”_blank”

    It is working correctly when using the JS “” on-click call, but I am wondering if there is a way to detect the target attribute value for “a” tags, and follow the same pattern as the JS call.

    Any information is greatly appreciated.


    January 3, 2013 at 6:25 pm

    • It won’t be handled automatically by Cordova. You can add some JavaScript on load that will find all anchor tags and add the equivalent onclick handlers when the target=”_blank” attribute is set.


      January 3, 2013 at 8:51 pm

  11. Advisory (updated the post): If you have a multi-page app, and you use InAppBrowser, and you use iOS 6, you must use iframe bridge mode. More details here:


    January 7, 2013 at 8:40 pm

  12. Has there been any movement (or plans) to get this on the Windows Phone 7? What is currently the best option for having this functionality on Windows Phones? Thank you


    January 7, 2013 at 8:54 pm

    • For Cordova 2.4.0, we are planning InAppBrowser for Windows Phone 7 and Windows Phone 8.


      January 7, 2013 at 9:08 pm

  13. […] (formerly called ChildBrowser). You can read more about InAppBrowser in Shazron Abdullah’s blog post. We have done extensive testing on this feature, but as always, report any bugs to our issue […]

  14. […] dazu im Blog-Eintrag von Adobes Jesse MacFadyen. Eine weitere Neuerung stellt die sogenannte InAppBrowser API dar. Dahinter verbirgt sich ein integrierter Webbrowser für mit PhoneGap erstellte Apps, der über […]

  15. […] dazu im Blog-Eintrag von Adobes Jesse MacFadyen. Eine weitere Neuerung stellt die sogenannte InAppBrowser API dar. Dahinter verbirgt sich ein integrierter Webbrowser für mit PhoneGap erstellte Apps, der über […]

  16. it works but there is no location bar to close browser/go back to app :/


    January 21, 2013 at 5:14 am

    • Yes, that is by design if you use _self. This is the same if you used document.location — the difference is (based on the spec), if the url is not white-listed, it is shown in the InAppBrowser.


      January 21, 2013 at 5:28 am

      • I am currently using _blank. It doesn’t show on _self either


        January 21, 2013 at 6:21 am

      • There is something wrong with your configuration. Then you are not using InAppBrowser, and it is loading in your Cordova webview. You have to wait for the deviceready event before calling any Cordova APIs.


        January 21, 2013 at 6:37 am

    • Make sure you are loading the correct cordova.js file. It took me 10 hours to figure out that Iwas trying to do this with my Android cordova.js file referenced instead of the cordova.ios.js file.


      March 20, 2013 at 10:51 am

  17. Loadstart and loadstop events are missbehaving for me, only on iOS. Some “loadstop” only fire after i click the “Done” button. Some “loadstart” fire without urls. I really miss the “onLocationChange” of Childbrowser.

    Pablo Zignani

    January 23, 2013 at 3:57 pm

    • never mind. That behavior happens when there is an error in the JS of the callback. Very strange indeed, but fixed 🙂

      Pablo Zignani

      January 23, 2013 at 6:19 pm

    • I’m also having issues with LoadStart. It fires on sub-page loads such as ad-networks which I don’t want. I miss the onLocationChange from ChildBrowser as well. loadstop doesn’t work for me as the user may click away prior to the page fully loading.

      I also tried rolling back to ChildBrowser but can’t get it to load in the new Cordova 2.6 stack (at least with my require.js setup).


      April 22, 2013 at 4:45 pm

  18. Shazron,

    I’m trying to open a PDF on Android. The PDF is located on the local FS under /sdcard/Download/Menu.pdf for example. I can open a URL like just fine. But the IAB opens and it’s blank and I really get no error message or anything. Here is my code snippet:

    var fileUrl = ‘file:///sdcard/Download/Menu.pdf’;
    alert(‘attempt to open: ‘ + encodeURI(fileUrl));

    // now try inAppBrowser
    var ref =, ‘_blank’, ‘location=yes’);

    It’s definitely calling the IAB since my logcat shows IAB output (like that it’s using ‘_blank’, etc).
    Any help would really be appreciated.


    January 30, 2013 at 9:22 pm

    • Unfortunately I am not entirely familiar with how Android handles PDFs. It may be that you don’t have a default viewer, and/or the Android WebView does not display PDFs natively.


      January 31, 2013 at 7:43 am

      • Shazron, thanks for your reply. If I navigate to the PDF in “My Files” (android folder navigation) and click it then it opens with “Open Office”. I’m not getting an error or anything, just a blank screen in the IAB (with the Done button at the top and the fwd/back buttons on top left).

        I’ll look at Simons blog… hopefully he may have an answer.


        January 31, 2013 at 2:37 pm

    • Kurt, try asking Simon on his Cordova Android 2.3.0 blog post:


      January 31, 2013 at 7:46 am

  19. Hi Shazron,

    When i open an external page in the InappBrowser, the page does not fit inside it. Horizontal scrolling is needed to see the full page.

    The same URL when opened in the mobile safari, the page fits nice and no horizontal scrolling is needed.

    Is there any setting i am missing…

    Your help is really appreciated..



    February 2, 2013 at 10:33 am

    • Post your code somewhere as a test case that anyone can run, to verify.


      February 8, 2013 at 2:59 pm

  20. I’m not sure if I am being daft, but is it still possible to have a link in a phonegap app (on iOS) that opens the page in safari?
    I have added target=”_blank” to the link, also I have added the url to the config.xml so it is whitelisted, and also in config.xml “OpenAllWhitelistURLsInWebView” value=”false”.
    While trying to sort this I came across a comment on stakcoverflow that said it was not possible any more.

    Thanks for any thoughts



    February 13, 2013 at 5:09 pm

  21. I can not stop video after inappbrowser is closed.
    I read many answer about that problem.
    But could not understand because i have no knowledge about program language.
    What i know is Only html and cssl.
    Can i get some easy answer?


    February 16, 2013 at 5:44 pm

    • I suppose you posted on the PhoneGap Google Groups? There are some answers there.


      February 19, 2013 at 8:58 pm

  22. Anybody knows how to add a loading indicator in InAppBrowser. While loading a page, InAppBrowser displays just a blank space until something downloaded. If the page takes a few seconds to download, I am like what is going on… there is an error or the internet is just slow.

    Thanks for any tips.

    abc abc (@firstid)

    February 19, 2013 at 5:33 pm

    • An alternative I suppose is to load a local HTML file with some loading graphic, and on a setTimeout in that page (say 500ms delay), do a document.location on the actual URL you want.


      February 19, 2013 at 8:57 pm

      • Well, it’s not ideal though. And then in my case I have several redirections (oauth thing), so I need to display some loading for each page.


        March 13, 2013 at 1:09 pm

  23. In case this hasn’t been officially mentioned yet … we need a way to control the width/height and x/y placement of the InAppBrowser UIWebView on the screen … ideally w/out having to modify the core CDVInAppBrowser.m file.

    Chris Emerson

    February 26, 2013 at 4:53 pm

  24. Hi sharzon

    is this issue fixed for Android. I just renamed phonegap-version to 2.3.0 in order to use inAppBrowser but I still have this issue. I’m using build.phonegap to make packages. Do I need to do something else because I’m not including this inAppBrowser anywhere I’m just using it in code ?


    February 26, 2013 at 5:10 pm

  25. It would be great if you could supply HTML as the content of the browser.


    February 27, 2013 at 8:53 pm

  26. Nice feature! How can I customize the navigation bar?


    March 7, 2013 at 11:47 am

    • You can’t without going into the code. We have several feature requests against it, like customizing the Done button caption.


      March 11, 2013 at 5:39 am

      • Thank you, I gave it a look into the code and found where the elements can be changed (like the arrows for “back” and “forward”). Anyway I haven’t found the way to change the “Done” caption, have you any quick code tips?


        March 11, 2013 at 10:15 am

  27. Is there support for webos?


    March 15, 2013 at 6:14 am

  28. Can you please let me know if we can open local HTML/JS/CSS files using InAppBrowser method? I know it sounds weird but id like to know if we can. Instead of giving the URL, can we give the path to the local html?

    var ref =‘path/xyz.html’, ‘_blank’);


    March 28, 2013 at 2:21 pm

    • Yup, it should work for local files (relative to www), at least I know it does work on iOS.


      April 2, 2013 at 11:29 pm

  29. Hi, Can you please let me know, how can we perform onLocation change function of child browser in inapp browser?


    April 8, 2013 at 9:08 am

  30. I am doing google ouath+ cordova 2.3.0+ childbrowser. I want to replace all childbrowser functionalities with inappbrowser.But i found function onlocation change , that function is called during signin button is clicked.not during webpage is started loading or not stoping…so how will i modify that…


    April 9, 2013 at 3:53 am

  31. Hi shazron,
    That’s great , thanks for the suggestion,it works perfectly.InAppBrowser is a great.


    April 11, 2013 at 10:47 am

  32. My apologies if I’m missing something obvious, but I’m a bit new to phonegap. . .

    I’m using the inappbrowser with great success. The target is set to _self, since I don’t want the control bar at the bottom of the screen. Of course, I lose all my lovely JavaScript and such at that point. I want the content from an external source to take over the screen, but I still want to be able to check to see if I lose network connections. Sadly, I have to take the HTML as is from the external location.

    Question: is there any way to display the external page without the nav bar at the bottom of the screen and still be able to respond to events (page load, network status, etc)?


    May 6, 2013 at 3:54 pm

  33. I spent a good deal of time getting Google OAuth 2 and childbrowser to work on Android…eventually all working fine with google drive. Tried on iOS and can’t get past the “Allow Access” button in the childbrowser. Just found out about inAppBrowser but no luck looking for google OAuth example. Can anyone advise.or point me to an example? Project running out of time/money. Many thanks


    May 30, 2013 at 7:34 pm

  34. Hello Shazron,
    I am trying to implement google oauth into my app and I was wondering how to change the onLocationChange to the loadstart/loadstop functions. I have tried using them by adding an eventListener but nothing has worked…


    June 20, 2013 at 5:32 pm

  35. Hi Shazron,

    My android phonegap application has a title bar in the each screen. I would like to add InAppBrowser just below that title bar. I used InAppBrowser in my app, but it displays a separate window on top of my application. I just want to add that browser window below the title bar of the app by resizing it. Not on the top of my app.

    Can you please tell me that how can I do this by modifying the source code of InAppBrowser? Please tell me form where I should start

    Thanks in Advance..!!


    September 2, 2013 at 6:59 pm

  36. this is ridiculous. i’ve been workign on this for 3 days now and i cant seem to get it. why wouldnt this be in the main package of cordova when installed?

  37. Hi Shazron, thanks for fielding all the Qs on the InAppBrowser (IAB)!

    Here is my issue: My index.html is a local page on the device that shows up in a WebView. On click of one of the links, I open an IAB to show content from the server side. I now need to use the barcode plugin from within the IAB. I have gotten it to work from the WebView, but it seems to be inaccessible from the IAB. I tried using executeScript for all the plugin script files, but this has not worked. You mentioned lack of support for cordova APIs from within IAB in one of your earlier responses, I believe it is referring to the plugins. Has that changed? I found another link that seems to suggest this will not work:!topic/phonegap/HHT7D6oWMUE. Any ideas? I am using PhoneGap 3.4. Thanks!


    May 6, 2014 at 7:44 pm

    • No, the IAB was never designed to use Cordova plugins, sorry. It is in a totally untrusted environment.


      July 8, 2014 at 6:01 pm

Comments are closed.

%d bloggers like this: