Those who pick up a Wii controller or even a PSP handheld expect to devote a certain chunk of time to playing games; even the most casual titles deliver a certain level of experience and accompanying learning curve. Enter Apple’s iPhone, which is redefining the category even further: iPhone users rarely “sit down” to play an iPhone game, no matter how engaging — they play waiting in line at the post office or during a quiet moment at work or while writing blog posts (just kidding). This isn’t to say there’s no room for more structured, traditional games — Subatomic Studios’ super-successful tower defense title Fieldrunners comes to mind — but for many iPhone developers, “casual” is taking on a new meaning.

Apple recently released a list of the top 20 paid apps (link launches iTunes) — of those, 15 are games, most of which can be launched and delved into in mere seconds. Generally speaking, this has no effect on game quality, but it does present unique challenges to iPhone developers. Namely, creating an experience that is familiar with little or no learning curve yet interesting despite abrupt pauses in gameplay.

This early in the iPhone lifespan many games’ uniqueness turns on interfaces and control schemes that utilize the iPhone’s unique features (accelerometer controlling character movement, for example). As the App Store begins to mature, developers will be able to rely on such simple solutions less and less; hardware features will change, as will user expectations. The challenge will be how best to provide a more varied experience — using the accelerometer to control one aspect of movement while touch gestures control another, for example — that can still be picked up and enjoyed almost instantly by the end user. Even now, with the third iPhone interation on the horizon, gamers expect a certain level of novelty; witness the tepid response of Konami’s Metal Gear Solid Touch, which provided simplistic touch-to-shoot gameplay that elicited mostly yawns from critics.

Obviously change of this sort will happen gradually as the iPhone market ages. The winners of tomorrow will be the developers who can adapt the quickest to meet these evolving challenges head on.

Today I will add just one last thing and we will call this a wrap.

In order to grab the rating for another country’s iTunes store, you simply pass in a numeric country code. To make things nice and user friendly, we can add a hash that maps each code to a string that makes more sense to us.

my %stores = ("US", "143441",
"Australia", "143460",
"Brazil", "143503",
"Chile", "143483",
"Columbia", "143501",
"Croatia", "143494",
"Denmark", "143458",
"ElSalvador", "143506",
"Finland", "143447",
"Greece", "143448",
"HongKong", "143463",
"India", "143467",
"Ireland", "143449",
"Italy", "143450",
"Kuwait", "143493",
"Luxemburg", "143451",
"Mexico", "143468",
"NewZealand", "143461",
"Austria", "143445",
"Panama", "143485",
"Philippines", "143474",
"Portugal", "143453",
"Romania", "143487",
"SaudiArabia", "143479",
"Singapore", "143464",
"Slovenia", "143499",
"SriLanka", "143486",
"Taiwan", "143470",
"Turkey", "143480",
"UnitedKingdom", "143444",
"Vietnam", "143471",
"Belgium", "143446",
"China", "143465",
"Czech", "143489",
"Spain", "143454",
"Guatemala", "143504",
"Indonesia", "143476",
"Korea", "143466",
"Malaysia", "143473",
"Norway", "143457",
"Peru", "143507",
"Qatar", "143498",
"Switzerland", "143459",
"SouthAfrica", "143472",
"Thailand", "143475",
"Venezuela", "1435021",
"Canada", "143455",
"Germany", "143443",
"Hungary", "143482",
"Lebanon", "143497",
"Pakistan", "143477",
"Russia", "143469",
"Sweden", "143456",
"Japan", "143462",
"CostaRica", "143495",
"Israel", "143491",
"Poland", "143478",
"UnitedArabEmirates", "143481",
"France", "143442",
"Slovenia", "143496",
"Netherlands", "143452",
"Argentina", "143505"
);

Then we change this line

$coCode = $data{'country'};

to this

$coCode = ($data{'country'})?$data{'country'}:"US";

and this line

$store = 143441;

to this

$store = $stores[$coCode];

That’s all there is to it. I saved this for last because of all the extra code, but it’s a very easy edit.

You can grab the current version and give it a shot. Have fun.

This is the last post in a series of posts which start here.

In a “real world” situation it might be just as easy to rename the script, modify the images and path names; but we can generalize this a bit in just a few minutes. Follow along below and you should be able to take either approach.

First, initialize a few more variables

my $star;
my $empty_star;
my $half_star;
my $image_path;
my $ext;

then add a few more lines to our splitVars function to see if options are passed in query string

$star=($data{'star'})?$data{'star'}:'star_on';
$empty_star=$data{'empty_star'}?$data{'empty_star'}:'star';
$half_star=$data{'half_star'}?$data{'half_star'}:'star_half';
$image_path=$data{'image_path'}?$data{'image_path'}:'images';
$ext=$data{'ext'}?$data{'ext'}:'gif';

Finally, edit the printHTML function. Find these four lines

    $thisimg='star_on';
    $thisimg='star_half';
    $thisimg='star';
	print "<img src=\"images/$thisimg.gif\" alt=\"$t Star\" />\n";

and change them to this

    $thisimg=$star;
    $thisimg=$half_star;
    $thisimg=$empty_star;
	print "<img src=\"$image_path/$thisimg.$ext\" alt=\"$t Star\" />\n";

Now you can pass in the following options via the query string

• image_path - directory containing your images
• ext - extension for images
• star - basename for full star
• half_star - basename for half star
• empty_star - basename for empty star (no star)

Grab the whole script here or give it a try at http://bsoist.freeshell.org/itunes/getstars3.cgi?id=304570595&html=true&ext=png&image_path=my_images&star=full_star&half_star=half_star&empty_star=empty_star

This is part of a series of posts which start here. The next post is here.

So what we want to do today is add an option for grabbing the data as html instead of a number. It makes sense to leave the number as an option in the event someone still wants to use it for that purpose. At this point, we know we can add two arguments to the URL

1. country=US - which the script currently ignores
2. id=304570595 - the application id

For our new addition we will use an argument named html and pass in 'true' for true and anything else (including nothing) for false. The script will assume false if no argument is passed in.

While we are at it, let’s go ahead and add an option for half stars.

We start by adding these lines

my $htmlformat;
my $halves;
			

with the rest of the variable assignments. Then, we add more to our splitVars function. This should do it

elsif(index($item, "html", 0) >= 0){
	$htmlformat = substr($item, index($item, "html", 0) + 5, length($item));
}
			

Now is a good time to improve on the code that grabs the arguments. The current version is fine for a couple of args but we can see that it will quickly become unwieldy. Let’s clean it up a bit and rewrite the splitVars function as follows:

sub splitVars{
	if (length ($ENV{'QUERY_STRING'}) > 0){
	      my $buffer = $ENV{'QUERY_STRING'};
	      my @pairs = split(/&/, $buffer);
	      foreach my $pair (@pairs){
	           (my $name, my $value) = split(/=/, $pair);
	           $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
	           $data{$name} = $value;
	      }
		$currentSoftware = $data{'id'};
		$htmlformat = $data{'html'};
		$coCode = $data{'country'};
		$halves = $data{'halves'};
	 }
}
		

Now we can change the main logic a bit so we have this:

print "Content-type: text/html\n\n";
splitVars();
$store = 143441;
getReviews();
if($htmlformat eq 'true') {
	printHTML();
} else {
	if ($halves eq 'true') {
		print $result * 2;
	} else {
		print $result;
	}
}
			

Well, now we can clean up some variables we don’t need but we also have a function we haven’t written yet - printHTML.

Let’s get the function done and then I will show you our new version. This function will do exactly what we did with the PHP - with differences in syntax, of course. We end up with something like this.

sub printHTML{
    my $t; my $thisimg;
	$result=$result*2;
	my $half=$result%2;
	$result=$result/2;
	for (my $i=0;$i<5;$i++) {
                if($result>0) {
                    $thisimg='star_on';
                    if($half==1) {
                         $thisimg='star_half';
                         $t='Half';
                         $half=0;
                    }
                } else {
                    $t='No';
                    $thisimg='star';
                }
		print "<img src=\"images/$thisimg.gif\" alt=\"$t Star\" />\n";
		$result--;
	}
}
			

What we have now is a version with several options.

1. id - REQUIRED - pass in app id
2. country - OPTIONAL - pass in country code - default is US
3. halves - OPTIONAL - pass in true for number of half stars - default is false, has no effect if next argument is true
4. html - OPTIONAL - pass in true for html instead of a number - default is false

Grab the whole thing over here if you’d like.

This is part of a series of posts which start here. The next post is here.

For the sake of demonstration, let’s look at an example using 3½ stars.

UPDATE:
I obviously neglected to cover an important point when I posted this. For this to work, I will need to modify our Perl script to return the number of half stars. I did that in my script with

print $result*2;
			

but I will add an option for this in Friday’s post.

Here is the html for the stars:

<img src="images/star_on.gif" alt="Star" />
<img src="images/star_on.gif" alt="Star" />
<img src="images/star_on.gif" alt="Star" />
<img src="images/star_half.gif" alt="Half Star" />
<img src="images/star.gif" alt="No Star" />
			

We’re using PHP for this site so if I have the number of half stars, I can set up something like this:

<?php
$stars='7';
$half=$stars%2;
$stars=floor($stars/2);
for($i=0;$i<5;$i++) {
	$thisimg=($stars>0)?'star_on':'star';
	$t=($star=='star_on')?'':'No';
	if ($thisimg=='star' && $half==1) {
		$thisimg='star_half';
		$t='Half';
		$half=0;
	}
	echo "<img src=\"images/$thisimg.gif\" alt=\"$t Star\" />\n";
	$stars--;
}
?>
			

So, now all I have to do is pull the star number before I do that and I’m all set. We replace this line

$stars='7';
			

With these two

$url=http://mydomain.com/path/to/script/getstars.cgi?id=304570595
$stars=file_get_contents($url);
			

So the whole thing looks like this

<?php
$url=http://mydomain.com/path/to/script/getstars.cgi?id=304570595
$stars=file_get_contents($url);
$half=$stars%2;
$stars=floor($stars/2);
for($i=0;$i<5;$i++) {
	$thisimg=($stars>0)?'star_on':'star';
	$t=($thisimg=='star_on')?'':'No';
	if ($thisimg=='star' && $half==1) {
		$thisimg='star_half';
		$t='Half';
		$half=0;
	}
	echo '<img src="images/$thisimg.gif" alt="$t Star" />\n';
	$stars--;
}
?>
			

If you have any experience with this sort of thing, you will know that there are a couple of things to consider. The first is that it may make more sense to return the html instead of the number in the first place and include that html in the page. This is very easy to do in PHP. The second, more important, consideration is that this will call the getstars script AND request data from the iTunes store every time someone visits our page. I wanted to post this info today in case any of you can benefit from it, but I will cover the first of these considerations tomorrow.

This is part of a series of posts which start here. The next post is here.

What I’ve ended up with is much more and I thought someone else might benefit from it. Over the next several days I will post details about how I ended up with our current version as well as some idea how you can put it to use for your own benefit. Today we will start with the basics - how to scrape the iTunes store.

The first step is to decide what data we need and on what page we can find it. We launch iTunes and browse to our application. We find the link that reads 4 Reviews for all versions and click it which takes us to a page that shows the number of stars near the top right hand side of the page. If I can grab that, we’ll be in business. So, we click the back button, find that link again, control-click on it and copy the iTunes URL.

Then we launch a text editor and paste in the URL and not that the important part of the URL is the application id which you find in the query string:

Now we use curl and see what kind of data we get from iTunes. We will use two command line options to ensure we can grab the data:

1. -A
   
   to set the User-Agent.
   
   I use iTunes/4.2 (Macintosh; U; PPC Mac OS X 10.2)
2. -H
   
   to send another header
   
   X-Apple-Store-Front: 143441-1
   
   143441 is the country code for the U.S.

Now we open ~/Desktop/foo.html in our favorite text editor and take a look at lines 667 - 674:

<TextView topInset="0" truncation="right" leftInset="0" styleSet="basic13" textJust="left" maxLines="1"><SetFontStyle normalStyle="textColor">Average rating for all versions: </SetFontStyle></TextView>

 <View alt="" stretchiness="1"></View>
</VBoxView>
   <VBoxView alt="">
 <View alt="" stretchiness="1"></View>

     <HBoxView rightInset="6" alt="4 stars" leftInset="6">

What we are after is the part that reads 4 stars on line 674. We could use regular expressions or some other technique to pull out what we need. Easiest thing in this case is to split the file up. Let’s use Perl for this. First we call use curl as we did before and assign the output to a variable by using the backticks. We will also throw in the -s option to suppress the progress indicators:

my $riz = `curl -s -A "iTunes/4.2 (Macintosh; U; PPC Mac OS X 10.2" -H "X-Apple-Store-Front: 143441-1" 'http://ax.phobos.apple.com.edgesuite.net/WebObjects/MZStore.woa/wa/viewContentsUserReviews?id=304570595&pageNumber=0&sortOrdering=2&type=Purple+Software'`;	

Then we split using the section Average rating for. Some applications will have Average rating for all versions: and others will have Average rating for the current version: so by using just Average rating for we will get what we want in all cases:

$riz = substr($riz, index($riz, 'Average rating for', 0), 300);

So, we split it and keep the second half. Then, we split again just before the 4 by using rightInset="6" alt=" and keep the second half. Next, we split at a simple ", keep the first half and then grab the first character:

$riz = substr($riz, index($riz, "rightInset=\"6\" alt=\"", 0)+20, 100);
$riz = substr($riz, 0, index($riz, '"', 0));
$result = substr($riz, 0, 1);

The only thing to do now is look for any half stars. If this app had 4½ stars, we would have found 4 and a half stars so we need to check for that and then print the result:

if(index($riz, 'and a half', 1) > 0){$result += 0.5;}
print $result;

Anytime we run the script we will get a numeral indicating the number of stars. We can throw in a bit more to generalize it so we can grab ratings for other apps or other stores. This should do the trick:

#! /usr/pkg/bin/perl -w
#! /usr/pkg/bin/curl

use strict;
use warnings;

my $result = -1;
my $store;
my $coCode;
my $appId;
my $counter = 0;
my $currentSoftware;
my $temp;
my $flag = 0;

print "Content-type: text/html\n\n";
splitVars();
$currentSoftware = $appId;
$store = 143441;getReviews();
print $result;		

sub splitVars{
my $item = "";
my $riz = $ENV{'QUERY_STRING'};
if($riz){
	my @rizray = split("&", $riz);
	foreach $item (@rizray){
		if(index($item, "id", 0) >= 0){
			$appId = substr($item, index($item, "id", 0)+3, length($item));
		}
		elsif(index($item, "country", 0) >= 0){
			$coCode = substr($item, index($item, "country", 0) + 8, length($item));
		}
	}
}
}

sub getReviews
{
    my $riz = "test";
    $riz = `curl -s -A "iTunes/4.2 (Macintosh; U; PPC Mac OS X 10.2" -H "X-Apple-Store-Front: $store-1" 'http://ax.phobos.apple.com.edgesuite.net/WebObjects/MZStore.woa/wa/viewContentsUserReviews?id=$currentSoftware&pageNumber=0&sortOrdering=2&type=Purple+Software'`;

   $riz = substr($riz, index($riz, 'Average rating for', 0), 300);
   $riz = substr($riz, index($riz, "rightInset=\"6\" alt=\"", 0)+20, 100);
   $riz = substr($riz, 0, index($riz, '"', 0));
   if(length($riz) != 0){
	if($result == -1){$result = substr($riz, 0, 1);}
	else{$result += int(substr($riz, 0, 1));}
	if(index($riz, 'and a half', 1) > 0){$result += 0.5;}
	$counter++;
   }
}

Now we save it as getstars.cgi, make it executable, and put it in our webspace and we’re all set. Hit the URL with http://yourdomain.com/path/getstars.cgi?id=304570595 and we get the number of stars.

Ignore the country code in the Perl for now — I will add more tomorrow to take advantage of that and I didn’t feel like stripping it out for today’s post.

This is part of a series of posts which start here. The next post is here.