Version

As an iOS developer, you often need to use a web service from your app.

Sometimes you need to use a web service that someone else has written, and sometimes you need to use one of your own!

In this tutorial, you’ll get hands-one experience with using web services, by writing an iOS app that communicates with a simple web service that allows you to redeem promo codes to unlock extra content.

This tutorial is the second and final part of a two part series on custom web services. If you are curious how to develop the web service yourself, check out the first part of the series for full details!

You don’t necessarily have to set up the web service yourself for this tutorial – you can use the one I’ve already set up if you’d like.

This tutorial assumes you have basic familiarity with programming for iOS. If you are new to iOS development, you may wish to check out some of the other tutorials on this site first.

The Choice

This tutorial requires you to create a new View-based application and integrate three frameworks into it: the JSON framework, ASIHTTPRequest, and MBProgressHUD. You also have to make a basic UI for the app so the user can enter in a code to redeem.

But that’s a lot of work, so I thought we’d start this tutorial out with a choice. Are you like this guy?

Do It Yourself!

If you want to create everything yourself, start up Xcode and go to File\New\New Project, select iOS\Application\View-based Application, and click Next. Enter PromoTest for the Product Name, click Next, and save it somewhere.

To add the JSON framework, first download it from its github page. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group JSON. Then drag all of the files from the JSON\Classes directory (JSON.h and several others) into the new JSON group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

To add ASIHTTPRequest, first download it. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group ASIHTTPRequest. Then drag all of the files from the ASIHTTPRequest\Classes directory (ASIAuthenticationDialog.h and several others, but IMPORTANT! don’t add the subfolders such as ASIWebPageRequest, CloudFiles, S3, and Tests.) into the new ASIHTTPRequest group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

Also repeat this for the two files in ASIHTTPRequest\External\Reachability, as these are dependencies of the project.

To add MBProgressHUD, first download it. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group MBProgressHUD. Then drag MBProgressHUD.h and MBProgressHUD.m into the new MBProressHUD group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

The last step is you need to link your project against a few required frameworks. To do this, click on your PromoTest project entry in Groups & Files, click the PromoTest target, choose the Build Phases tab, and expand the Link Binary with Libraries section. Click the plus button in this section, and choose CFNetwork.framework. Then repeat this for SystemConfiguration.framework, MobileCoreServices.framework, and libz.1.2.3.dylib.

Compile your project just to make sure you’re good so far, and now we’re back to the fun stuff!

Implementing the Interface

Let’s make a quick and simple interface to test this web service. As a refresher, the web service takes three parameters:

rw_app_id: The unique identifier for the app. If you’ve been following along with the previous tutorial, there should be only one entry so far, App ID #1.

code: The code to attempt to redeem. This should be a string that’s entered by the user.

device_id: The device ID that is attempting to redeem this code. We can get this with an easy API call.

So basically, all we need is a text field for the user to enter the code (they’ll tap “Go” on the keyboard to start the redemption process), a label for the text field, and a text view to write the result out to.

So click on PromoTestViewController.xib, bring up the Object library by selecting the third tab in the View toolbar (Utilities) and selecting the third tab in the library toolbar (Object library), as shown in the screenshot below.

From the Object library, drag a UILabel, UITextField, UITextView into the main view. Double click the UILabel and change the text to read “Enter promo code:”. Then double click the text view and delete all the text inside, and optionally change the background color of the UITextField to clear in the Attributes Inspector.

You also may find it useful to go to Editor\Canvas\Show Bounds Rectangles so you can see the bounds of the text view.

At this point your layout should look similar to the screenshot below:

Next, you need to set the File’s Owner as the Text Field’s delegate so you can get a callback when the return button is clicked on the keyboard. To do this, control-click on the Text Field, and drag a line from the delegate entry to the File’s Owner.

Also, you need to connect the text view to an outlet so you can set it later. To do this in the cool new Xcode 4 way, first turn on the Assistant Editor (the second button in the Editor tab) and make it show up on the bottom with View\Assistant Layout\Assistant Editors on Bottom. Make sure it’s set to Automatic and that PromoTestViewController.h is visible.

Then select the Text View and control-drag a line from the text view down to right above the @end keyword, set Connection tou Outlet, the Name to textView, and click Connect, as you can see in the screenshot below.

At this point Xcode will automatically create a textView property and instance variable for you.

Finally, open PromoTestViewController.h and mark the class as implenting UITextFieldDelegate as follows:

This simply checks for the error codes that we expect from our web service, and prints a message for each. Or if it’s succcessful, parses the JSON with the JSON framework, and checks the unlock code. Here is where you could grant the user with whatever special content you might want to give them in your app.

Compile and run your project, and you should see something like the following:

Adding a Progress HUD

The app works so far, but when you’re running a task in the background like this it’s often nice to let the user know what’s going on. This is nice and easy with MBProgressHUD, so let’s quickly add it in:

Compile and run your code, and this time a nice progress indicator should appear while the request is running!

Promo Code System: My Experience

Now as promised, I’d like to share my experience using this promo code system in Wild Fables with you guys!

I set up two codes for Wild Fables – one to unlock a single fable (of the user’s choice), and one to unlock all fables. I set up the first one so I could give out codes to friends & family to give them a little extra taste of Wild Fables, and I set up the second one so I’d have a way to give out full access to Wild Fables to professional app reviewers.

One of my favorite things about this system is it allows for unlimited codes. Which was great as 100 people used a code I gave out on Twitter alone (thanks again for checking it out and all the RTs guys, you rule!)!

I also put some codes in some threads on some various iOS forums, our mailing list for Razeware, our Facebook pages, etc. I made a separate code for each place I gave out the code, which is nice because it let me track where people actually cared about the post & used codes, and where people were more like the picture earlier in this tutorial ;]

Another amusing thing was sometimes I’d get emails from “reviewers” asking for a promo code to redeem my app, so of course I’d send them a custom code. But these “reviewers” would also include a pitch to try to get me to advertise on my site. Looking at the redemption table, I can see that several of them didn’t even bother to redeem the code, so I guess their real reason to email me was to get ad revenue, so beware! :]

As far as drawbacks go, as some people noticed the “unlock” is implemented basically by saving data to the file system, so it doesn’t work across all devices like in-app purchases do. You can implement this by creating a login system or such, but that was overkill for what I wanted to do.

So that’s it for my experience! Let me know if you have any further questions.

Where To Go From Here?

Here is a sample project with all of the code we’ve developed in the above tutorial.

Now that you have first-hand experience creating both a simple web service and an app that communicates with it from scratch, you can take the ideas here and create your own web services that do anything you need for your app!

If you have any questions about communicating with a web service from an iPhone app, questions about the promo code system, or advice for others in this matter, please join the forum discussion below!