Introducing iOS Beta Builder

For a developer, doing beta releases on iOS can be a real pain sometimes.
For the past few years, we’ve had to go through the same song and dance: gather device IDs, create ad-hoc builds and then try to explain to users how to install them via iTunes. This can be trying for even technical users – non-technical users can get totally flummoxed and let’s not even talk about people on Windows where the files often unzip in strange ways.
Apple, as is typical, has made incremental improvements to this process over time. iOS 4.0 brings Web-based, wireless distribution of ad-hoc apps and the ability to embed provisioning profiles right into the IPA bundle. Your beta users can now install the software without ever using iTunes at all!
The only problem is that it’s not really documented, at least not in an end-to-end manner. On top of that, while Xcode can help you create some of the files needed for distribution, it doesn’t seem to go all the way.
I wanted to use this method to distribute my beta apps but I found myself creating the required XML and HTML files over and over again. There had to be a better way.
Enter ‘iOS BetaBuilder’ – a simple MacOS X app takes your archived IPA file and creates the required manifest and HTML files for wireless distribution. It even zips up a copy of the app for folks on 3.x that need to install via iTunes.
iOS BetaBuilder is freeware and runs on MacOS 10.6 or greater. You’re welcome to use it however you’d like and feedback is encouraged but I’m not in a position to offer any support – you use at your own risk blah blah blah. Bug reports and feature enhancements are welcome, though my time to work on the app is limited. One feature I do want to add is the ability to include your own custom HTML templates so it’s easier to stylize the HTML output.
Apple may well build this into a future version of Xcode but until they do, I hope this helps save you a few minutes. In my beta tests, it’s cut down on the ‘how the hell do I install this’ emails completely.

For a developer, doing beta releases on iOS can be a real pain sometimes.

For the past few years, we’ve had to go through the same song and dance: gather device IDs, create ad-hoc builds and then try to explain to users how to install them via iTunes. This can be trying for even technical users and non-technical users can get totally flummoxed. Let’s not even talk about people on Windows where the files often unzip in strange ways, leaving them totally confused.

Thankfully, Apple has made incremental improvements to this process over time. iOS 4.0 brings Web-based, wireless distribution of ad-hoc apps and the ability to embed provisioning profiles right into the IPA bundle. Your beta users can now install the software without ever using iTunes at all!

The only problem is that it’s not really documented, at least not in an end-to-end manner. On top of that, while Xcode can help you create some of the files needed for distribution, it doesn’t seem to go all the way.

I wanted to use this method to distribute my beta apps but I found myself creating the required XML and HTML files over and over again. There had to be a better way.

Enter ‘iOS BetaBuilder’ – a simple MacOS X app takes your archived IPA file and creates the required manifest and HTML files for wireless distribution. It even zips up a copy of the app for folks on 3.x that need to install via iTunes.

iOS BetaBuilder is freeware and runs on MacOS 10.6 or greater. You’re welcome to use it however you’d like and feedback is encouraged but I’m not in a position to offer any support – you use at your own risk blah blah blah. Bug reports and feature enhancements are welcome, though my time to work on the app is limited. One feature I do want to add is the ability to include your own custom HTML templates so it’s easier to stylize the HTML output.

Apple may well build this into a future version of Xcode but until they do, I hope this helps save you a few minutes. In my beta tests, it’s cut down on the ‘how the hell do I install this’ emails completely.

Download iOS Beta Builder 1.0

While I’ve been working on iOS for awhile, I don’t have a ton of experience with Cocoa proper – I’m sure there are probably some issues that slipped through the testing process.

Screenshots:

How Does It Work?

1. Build your .ipa file using Xcode’s ‘Build and Archive’ option. Choose ‘Save to Disk’.

2. Launch BetaBuilder (or drag and drop the .ipa on to it). If you need to, select your .ipa file. The app should pre-fill the other details.

3. Enter your intended deployment URL. This is the URL on the Web where your beta will be posted / viewed in a browser. This info gets baked into the deployment file.

4. Hit ‘Generate Deployment Files’ and pick a location to output the files.

That’s it – just upload the generated files to your Web server and then hit the URL in the device’s browser. BetaBuilder simply generates the HTML and manifest files needed to make wireless distribution work. As a convenience, it also bundles an iTunes installable ad-hoc version as a zip file.

NOTE: If you are on IIS, you may need to add a MIME type for plist files – should probably be ‘text/xml’.

Follow me on Twitter: @hunter

Comments

87 Comments so far. Leave a comment below.
  1. John,

    Fantastic! Thank you!
    Works perfectly!

  2. Is this only for Enterprise ad hoc distribution? Any convenient way for standard ad hoc?

  3. Hunter,

    No, it works fine for standard.

  4. One problem, it wouldn’t work for an ipa file with spaces in its name. You need to url encode the filename before writing it to the manifest. I manually changed the filename “beta build 0.1.2.ipa” to “beta%20build%200.1.2.ipa” in the manifest to get it to work.

    Other than that, this method of ad hoc distribution is awesome! Thanks for building the utility. (If you want to release the source on github or similar I’d be happy to submit patches)

  5. Samuel,

    Can I get the source code ? I’d like to improve your tool (add version number, localization, etc.)

  6. Hi Hunter,

    This looks great! Any chance you’ll share the source code or provide a console based app with parameters?

    I can share some ant build files that compile and build the ipa file, if you’re interested :)

    Cheers,
    Shawn

  7. Hunter,

    Hey Guys,

    Glad that you are finding it useful and it sounds like you have some ideas to make it even better so with that in mind, I’ll get it setup on GitHub (today or tomorrow – watch this space) so that everyone can hack on it – there’s not a whole lot to it.

    Whoops on the URL encoding thing – I’ll put in a fix before I publish.

    Cheers.

  8. Hunter,

    The code is on GitHub here:

    http://github.com/HunterHillegas/iOS-BetaBuilder

    Enjoy. I had to pull the icon out – it’s not licensed for distribution that way… but I’m asking IconFactory to see if they’ll allow it.

  9. We announced a similar tool a couple days ago.

    1. Upload ipa to service
    2. Have your testers notified when a new build is available
    3. Monitor if your testers have downloaded or used the build, and how they are using it.

    Check it out http://www.testflightapp.com

  10. Hunter,

    Trystan,

    That looks cool – it certainly does a lot more than BetaBuilder.
    Are you guys planning to charge for the service?

    Hunter

  11. And we did another one :) http://github.com/TheRealKerni/Hockey

    Upload the files to the server, add client code into the beta apps, webpage is created automatically, clients check either manually, daily or each time the apps open (the beta tester can decide).

    Seems we should join forces :)

    • Hunter,

      Yeah, what you guys are doing is awesome!

      Funny to see a bunch of people working on this problem all release stuff in the same timeframe.

  12. This is great!

    This will eliminate SO many headaches for any of my testers on iOS 4+

    Thank you SO much!

  13. chad,

    This process works, however, I can only install it on my device? Other devices start to download, get to about 90% and then alert a message “Unable to Download ” is there someting I’m missing?

    • Hunter,

      Is it possible you used a debug build and not an ad-hoc build with the proper provisioning?

    • Amar Kulo,

      I had the same problem and the real problem is in provisioning profile. I’m using com.my_name.program_name profile for signing and it works on my iPhone but when I try to download it like this it doesn’t work. I’m receiving the same error message, I can see that it’s downloaded and installation starts but then it fails. For me it was solution to have team provisioning profile installed on iPhone, then it will install from web. I didn’t looked too much into this so I don’t have better solution at the moment.

  14. Rob Bonner,

    Hello,

    I have run through this process, and get the load page great on the phone, but just get an alert saying “cannot connect to http://www.????.com“. The odd thing is I just did connect to the site to load the page, so DNS is working great. Anyone else having this issue?

    Great UI BTW!

    • Hunter,

      Hi Rob,

      One thing to check is that the value you use for the ‘Full Web Deployment Path’ does indeed match the Web server path where you uploaded the generated files.

      Verify that and re-generate and hopefully that’ll fix it. The error you see typically means that the link in the generated HTML file isn’t correct.

      • Kerry,

        I’m having the same issue as Rob, when I click on install from my iPhone I get the “cannot connect to http://www…” error. I know that the Web Deployment Path is correct because if I cut and paste it straight from Beta Builder into Safari on the Mac it brings up the correct page. It looks like there is something going on with the webserver trying to serve the manifest.plist file. I’m not a web dev, but could something be going on where the server doesn’t know how to deal with the “href = itms-services://?action=download-manifest&url=http://www…” statement?

      • Hunter,

        Interesting. In my config using stock Apache 2.2, it works.

        If you want to email me (address on contact page), I’m happy to work with you to try to figure it out.

      • Kerry,

        Thanks Hunter. I just sent you an e-mail with the pertinent info. Let me know if you did not get it.

        Kerry

      • Kerry,

        The other thing you may need to do for IIS servers is add a MIME type for the .ipa file. It should be:

        .ipa application/octet-stream

      • Hunter,

        Just a note – if you are on IIS, make sure you have a MIME type entry for .plist files – ‘text/xml’.

    • Burt,

      This is becaue you have not specific the MIME type…

      Add MIME Type for plist as Text/xml

  15. You might be interested in http://blog.flirble.org/2010/10/16/app-ad-hoc-beta-publishing/ where I used BetaBuilder as a building block for almost fully automating the publication of a new beta.

  16. zerodtkjoe,

    Thanks for the info

  17. A cool tool, thanks!

    I found that I can customize the generated index.html
    by editing (carefully!) the html template file /Applications/BetaBuilder.app/Contents/Resources/index_template.html.

    Perhaps this could be mentioned in the documentation.

    Rudi

    • Hunter,

      Documentation? What documentation? :-)

      Yes, you’re right – it should be easier to discover this feature.

  18. Troy,

    You saved me. Thank you.

  19. CJ,

    Thanks for this great tool.

    A possible enhancement request. We are trying to do nightly builds of our app. We have Xcode setup to build and Archive the app nightly, but it still requires us to perform this task manually. Is there a way to script Beta Builder to take in parameters (for the required fields) so I can include in our shell script for automatic deployment?

    Thanks for any assistance

  20. Larry,

    Worked perfectly and took a lot of the hassle out of this process. Thanks for putting this together.

  21. I hate to leave a useless comment, but this worked so well I just have to thank you – the slickness of the generated HTML is a real plus. Thanks again!

  22. Bogdan,

    Thank you! This is fantastic!

  23. Dee,

    Hi, this seems like a dumb question (I can probably google it but this might be faster/more accurate). If I use this tool, do I still need to add the UDIDs of the test devices to the ad hoc provisioning profile? Or will it bypass it?

    Thanks.

  24. Shawn,

    Silly question, I’ve got the IPA File, but when I click the Generate Deployment Files it seems to just generate a manifest.plist, a beta_archive file with the .ipa and beta_provision.mob, and the .ipa file. I’m sure I’m missing something, but not sure what it is I’m missing.

    • Shawn,

      Scratch that, it appears that OSX at some point had asked for a permission related to the file system. The Dialog box buggered off and the app was never actually given permission. ALL IS GOOD.

  25. Sounds great, but woe I must be a dunce, I can’t figure this out.
    1) Can’t figure out how to create an .ipa file with XCode 4. There is no archive and build option, but there is a Build for Archive option, then an archive option which creates an .xarchive file. The organizer is supposed to allow you to create an .ipa file from this by clicking on the archive then hitting share, but there is no option to create an .ipa package. *iOS App Store Package (.ipa) not present, it says “no packager exists for this archive”.
    2) OK, gave up on that and created my own .ipa file by creating a “Payload” directory and putting my enterprise license signed app in there and zipping it and changing the .zip to .ipa.
    3) Dragged that into the BetaBuild app, and it read it, so sounds good. Wasn’t totally sure what to put in the URL so put in my website domain / Payload.zip.
    4) Build the package and renamed it to Payload.zip.
    5) Uploaded Payload.zip, index.html, and manifest.plist to my website
    6) Went to my iPad in Safari and types in mydomain/index.html. Got the web page, clicked on “Tap here to installed ….”, got the error message “Cannot connect to mydomain.com”. Bizarre, that domain is perfectly fine.

    Totally hit a wall.

    • Hunter,

      With Xcode 4, if you create an archive, Xcode will allow you to ‘Share’ that archive and export an IPA. If you’re not given IPA as a choice and it does an Xarchive, there’s likely something in your project preventing it, such as inclusion of a static library. Xcode will only create an IPA if it can create a self-contained bundle of everything and if you have the copying flags setup incorrectly/differently in your project, it won’t work.

      This is a little bit out of scope for this app, since it’s assuming you have a properly built IPA but perhaps it can be helpful to someone.

  26. I got to work sort of. A lot of the below information is not clear in the documentation:

    Create a folder Payload

    Put the application in there

    Zip it up

    Rename .zip to .ipa

    Drag the .ipa file into the BetaBuilder application icon which will launch the application.

    Put in bundle identifier (at one point this was entered automatically by the application, but that stopped working for some reason), Has to be exactly the same name as the one in the info.plist. Note that spaces in the name are generally replaced with a dash.

    Put in App name (e.g. Mercury). Must be the same as the app filename

    Put in URL where you will place the html file (NO ending slash)

    Click Generate

    Rename index.html to some name (e.g. dl.html)

    Upload the following 3 files:
    your .ipa file
    manifest.plist (Created by generate above)
    dl.html (Created by generate above)

    On the iPad 1 it works fine, however it appears that on the iPad 2, the icon doesn’t show up? There is artwork that can be included in the .ipa Package like iTunesArtwork, but this doesn’t appear to be the problem. There is a way to get XCode to create the .ipa file using Build and archive, but I can’t figure out how to get XCode to build an .ipa file (despite what the documentation says, it simply doesn’t work). Perhaps if we get that to work it will be cleaner and work properly.

    See http://en.wikipedia.org/wiki/.ipa_(file_extension) for more information. There are some other files which can be put in there (iTunesArtwork and iTunesMetadata.plist), but they don’t seem to be necessary. If we get XCode to generate this, presumably, these will be in there.

    • Hunter,

      Thanks for the comment. I’d personally recommend using Xcode to create the IPA instead of doing it manually as you’re suggesting above.

  27. bg,

    Had the same prob w Xcode producing only archive.
    Found out that I had to set Skip Install to YES on the targets of my dependencies (I used CorePlot static library in my app). AND Also moved ALL headers of CorePlot targets to Project in Build Phases.

    Maybe someone could help me with my prob getting Cannot Connect to server.
    I am using port number with it, could that be a problem?
    my download link looks like this:

    Install app

    Any thought?

  28. bg,

    sorry here it is “http:///?action=download-manifest&url=http://aaa.aaa.edu:XXXX/app.plist”

  29. bg,

    figured out. it was iss mime server problem.
    For IIS, use IIS Manager to add the MIME type in the Properties page of the server:

    .ipa application/octet-stream

    .plist text/xml

  30. barney,

    Very nice app, thank you Hunter… Q: what do i do about the icon pngs?.. on the Xcode “enterprise” option they require you to add a URL.

    • Hunter,

      Hi Barney,

      I haven’t had my coffee yet this morning and I’m a little slow… Not totally sure what you’re asking. Can you expand?

      - H

  31. Jordy,

    Thanks a lot! Great stuff!

  32. Ray,

    Hi Hunter.

    Of course, many thanx for the app. Works up to ‘installing’ under the icon, and then hangs for a while. If I touch the icon, the ugly ‘Unable to Download…’ message hits me. plist is correct, ipa was created with Release and Archive and a DEV profile, so I’m stuck. Any thoughts ?

    • Ray,

      Ignore it, I fixed it by deleting the ‘broken’ app on the phone thru many wiggles, deletes, rinse, repeat.

      Thanks anyway.

  33. Beta builder version 1.0 supports only the iOS 4.0 or early users. But, we require iOS 5.0 or later users. So, is there any Beta builder which is support the iOS 5.0 or later users?

  34. denosya,

    Great tool !
    Thank you

  35. Sven,

    Hi,

    just bought the app store version, but still cannot install the app on ios 6 : it shows the installing icon , then the apps name and the error message “app cannot be loaded”

    what is going wrong ?

    • Hunter,

      Hello,

      Difficult to say without more details but by far the most common problems are:

      - The UDIDs you’re trying to install on to aren’t included in the provisioning profile.
      - The Web site / URL details aren’t correct (i.e. missing http://).

      I’d recommend taking a look at those two things to ensure everything is ship-shape. You can also check the output of the device console via Xcode Organizer for additional clues.

      If you’re still stuck, feel free to send an email to info@hanchorllc.com with more specifics.

  36. Sven,

    Hi,

    thank you for the quick response – it works now :)
    I changed the bundle identifier from appname
    to de.companyname.appname and it worked !

    kind regards,
    Sven

  37. Thank you so much for this! It worked the first time! Whoo whoo!

  38. yama,

    Hi Guys,
    work you very much, it works very well, mad my life easy

    Cheers
    Yama

  39. Hello, I had a TradeMark sign in my applications bundle display name. Only in that case BetaBuilder was not able to create the index.html file. So, I had to move to testflightapp for that particular project. Any suggestions?

    When I remove the TM sign, it works fine. Note that the TM sign shows fine in my devices and this is a requirement for the project.

    BetaBuilder is otherwise great and really helpful tool.

  40. ungo,

    Is this work for developer program?
    and can i install my app more than 100 devices?

  41. Ok, I will like to know if this method is legal or not. It works like a charm but I don’t want to involve to my potencial users/customers in a beta distribution of my app in a illegal way. Do you know something about it? Could Apple complaint about it?

    • Hunter,

      No, it’s not illegal or in any way against the developer agreement. All of the normal rules of the developer program still apply.

  42. Jeremy,

    THANK YOU for making this app. I love it, but I just upgraded to the version in the App Store and discovered one slightly annoying difference from v1.0: you can’t generate deployment files into the same folder as the IPA. It either deletes it if overwrite is checked, or doesn’t allow creation. You must choose a different folder. Is this by design?

    • Hunter,

      It doesn’t sound like it. Can you give me steps to reproduce? If I verify it’s a bug, I’ll make sure to fix it.

      • Jeremy,

        Cool. I just save my .ipa file from xcode to a folder called /archive. Then I point your app to that file, type in my URL, and hit “Generate Deployment Files.” Then I point it to the same folder as the .ipa. If “Overwrite Existing Files” is checked, it deletes the .ipa and then complains that it can’t find the .ipa. If that checkbox is not checked, it says ““col.ipa” couldn’t be copied to “Archive” because an item with the same name already exists.”

        Why, yes. Yes it does. :) Thanks for your quick response and for taking a look at this! Again, thank you so much for making this app and simplifying the process.

  43. H,

    We have reached out 100 device limit in the Apple Developer Portal. Can this method get around that 100 person limit?

  44. Hey Hunter!

    Quick question. Everything seems to be correct except when I got to the website I designated and click the “tap here to install” it says cannot connect to null?

    Any suggestions?

    Thanks for your time

    -Andrew

  45. Well I got the same issue when uploaded a build over my server; when user open the url and tap on link it shows cannot connect to null ..
    What I did, I just put the build over my public dropbox directory (after generating from bete builder again) and tried again; It worked; Don’t know it was my server’s issue or what .. still finding the exact issue;

  46. Gaurav Arora,

    I was having a problem in creating beta download and the Error would not go away. After investing few hours, I came across this tool and it works awesome.

    Saved me so much time. Thanks a bunch.

  47. Adam Nilsson,

    Hi Hunter!

    I have tried to download my app to my ipad but the installation stops at 80-90%. The app size is 500MB is that to big?

    • Hunter,

      I believe that the max size for an iOS app is 2GB. BetaBuilder doesn’t enforce any limits so I’m not sure what’s up there. Perhaps the Web server is crapping out or something going on with your connection?

      • Nicolas,

        I have just bought the Beta Builder from the Appstore. And it happened the same to me. It stops al 80% and gives an error. App can’t be installed at the moment…

      • Hunter,

        Hi,

        In all previous cases of this sort of issue, there’s either a problem with the provisioning profile (i.e. devices are missing) or the deployment Web server path doesn’t match.

        If you’re getting partial downloads, it’s likely the provisioning. Be sure that all devices are part of the provisioning profile and that the IPA is actually built with the profile you think it is using. You can crack the IPA open and verify that if you’re not sure.

        Hunter

  48. Antonio,

    I have tried modifying the contents/resources/index_template.html file in the appstore version of the application version 1.8.1 and the then reopening the application to compile a file and it doesn’t work, it defaults back to the original text. Is there another file I should be modifying?

  49. amit,

    Hi Hunter,
    First of all sorry I’m asking a question which is not related to the beta builder.
    Actually, I’ve a doubt regarding the re-signing.
    My problem statement is: I’m getting an *ipa file from vendor which is signed with developer certificate and I don’t have the src code for this application.
    Now I dont want to give vendor my companies enterprise distribution certificate and at the same time I want this ipa to be hosted at some secure server along with the manifest file.
    So I could find one approach: resign the ipa with the enterprise distribution certificate and host the resultant ipa file and manifest file to some server.

    So now I just wanted to know, is there any other way where we dont have to give our enterprise distribution certificate to the developer and ipa can be shared with the large audience (not on the app store, but some secured server).

    Please let me know if you have some other better idea.
    Thanks.
    Amit.

Add Your Comments

Required
Required
Tips

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <ol> <ul> <li> <strong>

Your email is never published nor shared.

Ready?