WebSockets in PhoneGap Projects

I’m a big fan of the WebSockets API for all the real-time goodness it offers, but the iOS platform doesn’t (currently) bake the WebSockets API in to mobile Safari. That sucks, particularly because I can enjoy making iOS native apps using awesome frameworks like PhoneGap. However, because I’m using PhoneGap, I can create a PhoneGap plugin that introduces WebSockets to my HTML & JavaScript. So that’s what I did.


I’m assuming you’ve got your PhoneGap project and XCode to manage and build the project. These instructions are going to explain how to get WebSockets working in your project.

Step 1: Cocoa Async Socket

Download and include AsyncSocket.h/.m from the cocoaasyncsocket project in your project directory (or some subdirectory, as you please).

Next, drag these files (AsyncSocket.h/.m) in to the XCode project space – this will include the files properly when the project is built.

Step 2: PhoneGap Plugin: WebSocket

Now download (or fork) the PhoneGap-Plugin-WebSocket project. Now repeat the process you did with the Async project with the WebSocketCommand.h/.m files.

Next, copy websocket.js in to your www directory and include the following after you include phonegap.js:

<script src="websocket.js"></script>

Note: you can also release your project to the web and include the websocket.js script, because it will only introduce WebSockets if a) WebSockets aren’t already available, and b) only if PhoneGap is in place.

So now you’re read to rock and roll with native WebSocket support in your PhoneGap project.


Once you’ve followed the installation, usage is exactly the same as using a WebSocket normally:

var ws = new WebSocket('ws://example.com');
ws.onmessage = function () {
  alert('a message was recieved');

ws.onopen = function () {
  ws.send('I just connected!');

One small caveat, if you need the WebSocket straight away, you will need to wait until the deviceready event fires, but otherwise you can just create the socket on demand.

If you want to learn more about PhoneGap, my conference Full Frontal, is running a full day workshop with Brian LeRoux entirely on PhoneGap, so check it out!

8 Responses to “WebSockets in PhoneGap Projects”

  1. [...] currently include the WebSockets API in mobile Safari. Remy Sharp solved this limitation by creating a WebSockets PhoneGap plugin to introduce WebSockets your installable web app using HTML and [...]

  2. Is there a way to do WebSockets in PhoneGap for Android?

  3. Hi,

    thank you for your job that’s really cool, it gaves me the courage to do the same for Android. check it out : http://github.com/FreakDev/PhoneGap-Android-HTML5-WebSocket

  4. I am thinking of using this on my pirate game. I think websockets should work on andoid since it is chome.

  5. Is it possible to do Web Sockets for Blackberry with PhoneGap?

  6. I tried using the Phonegap Plugin hosted at http://github.com/FreakDev/PhoneGap-Android-HTML5-WebSocket for Android and it seems it doesn’t work the way it should .

    Can I please have some clear pointers on how to use integrate into current project. A sample source code would be great. Thanks

  7. I have web sockets working for IOS and Android using PhoneGap. Trying to find something for Windows Phone using WebSocket4Net. Any examles out there with web sockets using pone gap on windows phone 7?

  8. @Shawn, Can you please share the iOS websocket plugin? I’m unable to compile the above posted source code.

Leave a Reply
Not required

CODE: Please escape code and wrap in <pre><code>, doing so will automatically syntax highlight