Gravatar, globally recognized avatar is an platform (web application?) by Automattic, creators of the blogging platform WordPress. The idea behind gravatar is to associate a picture to a person using his email address. As email addresses are increasingly becoming a way to identify yourself, some commenting platforms use Gravatar APIs to display an icon using the email address you give them.

The Gravatar API is ridiculously simple that, all you have to do is to convert the email address to a MD5 hash and send the MD5 hash to Gravatar which will then return you the image file you requested.

In this tutorial, I’ll explain how to convert any email addresses into a gravatar image as shown below.

At the end of the tutorial is a link to the github repo where the source code of the tutorial is available. As always, I’m not going to start with “Launch XCode, create a view based application, drag this, drag that” cliché. Let’s delve straight into the core. I assume you already have an app to which you are going to add Gravatar support.

Step 1: Add the boiler plate classes

Open your project and a class called, “GravatarHelper” (or anything you like). We will write a helper static function in this class so that it will return a the gravatar URL for a given email address. That’s we will be writing a function that looks like this.

+ (NSURL*) getGravatarURL:(NSString*) emailAddress;

So add a function declaration into the GravatarHelper class that looks like this. In your app, you can call this function to get the gravatar URL from the email address you pass and you can start using that URL to display a thumbnail or icon to the end user.

Step 2: Understand the Gravatar API

The gravatar API is as follows.
1) Trim the email address and convert it into lowercase.
2) Compute the MD5 hash of the email address.
3) Make a request to http://www.gravatar.com/avatar/MD5-hash

Step 3: Curate the Email address

Before computing this hash the email address should be void of spaces and in lowercase. All this can be done using this single line of code

	NSString *curatedEmail = [[emailAddress stringByTrimmingCharactersInSet:
				[NSCharacterSet whitespaceCharacterSet]] lowercaseString];
	const char *cStr = [curatedEmail UTF8String];

Step 4: Compute the MD5 Hash

On iPhone, you can compute the Hash of a string using the CommonCrypto framework. So import the necessary header files

#import <CommonCrypto/CommonDigest.h>
<pre>Now, use the <a href="http://developer.apple.com/library/ios/#documentation/system/conceptual/manpages_iphoneos/man3/CC_MD5.3cc.html">CC_MD5</a> C function to compute the MD5.
 
Your code should look like this now.
<pre lang="objc">    unsigned char result[16];
    CC_MD5(cStr, strlen(cStr), result); // compute MD5
 
	NSString *md5email = [NSString stringWithFormat:
			@"%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",
			result[0], result[1], result[2], result[3],
			result[4], result[5], result[6], result[7],
			result[8], result[9], result[10], result[11],
			result[12], result[13], result[14], result[15]
			];

Now that you have got the MD5 hash of the email address, you can construct the gravatar API request string.

Step 5: Create the Gravatar API Request String

Again a one-liner, just create a NSString by appending this MD5 hash to http://gravatar.com/avatar/
Your URL should look like http://www.gravatar.com/avatar/bff6e45b083ed70f471e91370f3b3460 now.

The API also supports two other parameters,

the first one being the file type. Append .JPG or .PNG to this URL to get the resulting avatar file in that format.

Second parameter is the size of the image. Both these parameters are optional. Gravatar supports sizes of 1px to 512px. For an iphone app you might probably need a 50px icon (or a 100px icon on iPhone 4 retina display).

This parameter can be specified by appending a parameter “s=512″.

Step 6: Construct a NSURL from the string

Return a NSURL constructed from this string back the the caller. That’s it.
The whole function should look like this.

+ (NSURL*) getGravatarURL:(NSString*) emailAddress
{
	NSString *curatedEmail = [[emailAddress stringByTrimmingCharactersInSet:
							   [NSCharacterSet whitespaceCharacterSet]]
							  lowercaseString];
 
	const char *cStr = [curatedEmail UTF8String];
    unsigned char result[16];
    CC_MD5(cStr, strlen(cStr), result); // compute MD5
 
	NSString *md5email = [NSString stringWithFormat:
			@"%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",
			result[0], result[1], result[2], result[3],
			result[4], result[5], result[6], result[7],
			result[8], result[9], result[10], result[11],
			result[12], result[13], result[14], result[15]
			];
	NSString *gravatarEndPoint = [NSString stringWithFormat:@"http://www.gravatar.com/avatar/%@?s=512", md5email];
 
	return [NSURL URLWithString:gravatarEndPoint];
}

Source Code

The complete source code with a demo project is available at github. If you just want the GravatarHelper files, grab it here
1) GravatarHelper

Happy coding

Mugunth


Follow me on Twitter