I needed some kind of application usage analytics service that I can use for our upcoming Mac OS X application. I’ve been using Flurry Analytics for my iOS apps but it looks like they don’t provide an Mac OS X counterpart to their service. Similarly Google Mobile Analytics also doesn’t have a desktop counterpart.

Luckily I found doo’s GAJavaScript tracker from a StackOverflow answer. The framework wraps Google Analytics‘ JavaScript tracker so that you can call it from an OS X application. It works by having a local copy of the JavaScript library and run it from a local HTML file loaded through an invisible WebView.

Then I’ve integrated this framework into my app and distributed the app to just over a hundred beta users. Strangely Google Analytics’ reports for that “app” remained zero hits. That can’t be right since I’ve been receiving feedback from a number of users (meaning that at least some people are using the app, even if only for a short while).  I’ve also debug the app with analytics turned on –  even if nobody else uses the app, the reports should show my own usage of the app. I’ve fiddled with it for a while, trying out various type of tracking codes (e.g. site tracking vs mobile tracking), debug the library and immediately checking the result but it simply doesn’t work: there isn’t any “hit” registered in any of the Real-Time Reports.

What puzzles me is that the answerer claims that this library works perfectly fine. I’m not sure whether there’s some hidden tricks to use doo’s library that I didn’t know about or that this answer was simply lying:

I was using the latest version of GAJavaScriptTracker which is already quite old, the commit date was 7 September 2012. Suspecting that Google Analytics library have changed in the mean time, I’ve downloaded the latest version of ga.js and try it out. Unfortunately it didn’t work.

Being weary for this and having a real need for a desktop analytics library, I decided to roll out my own solution: BSWebTracker. It’s still roughly inspired from doo’s work but completely written from scratch with an entirely different approach. It’s not tightly coupled to Google Analytics and you can easily swap in another analytics provider (Adobe’s SiteCatalyst is one contender – previously Omniture). But it does require you to have a web server as part of the setup.

How it works 

Instead of having a copy of Google Analytics’ JavaScript module inside the app, the library mimics a web browser hitting a predetermined web page. In turn the web “site” is simply an empty web page containing Google Analytics’ tracking code, which then does the heavy work of recording your application’s usage.  BSWebTracker is designed only to load a single URL for the entire app and differentiates various tracking actions by varying Analytics’ utm_xxx parameters. These are the exact same parameters that you can construct using the URL Builder.

Since it uses a WebView and not directly talking to Google Analytics, it was not as straightforward as requesting a URL for every single tracking requests. Requests are serialized so that Google Analytics’ JavaScripts are executed properly even when there is a rapid fire of tracking requests from the app. That is, if the “page” is being loaded or a JavaScript is being executed, the WebView should be left alone and not asked to load another requests, otherwise it’ll just drop whatever it’s doing right now and serves the new request. Thus the library maintains an internal queue of tracking requests and dispatch them one by one.

This imply that you shouldn’t send hundreds of tracking requests in a tight loop – otherwise it may take a very long time for all requests to complete and the user may quit your application long before all tracking requests are sent. Instead send on the completion of a user action like, for example, opening a document or completed a workflow. 

Furthermore BSWebTracker also manages its WebView instance diligently. It’ll discard the instance whenever there are no more tracking requests to send. You wouldn’t want to keep an unused WebView instance around, would you? It’s a heavyweight object – being a full-fledged web browser after all. So even though you shouldn’t burst a lot of requests, you’ll still want to keep them near (time-wise) to each other. In other words, maintain locality of reference. Try to group tracking requests in one lifecycle of your app – for example at startup – instead of sending far-flung requests. If you send requests only once in a while, there might be thrashing of WebView instance creation / destruction as the class creates a WebView instance to solely serve one request and then immediately deallocates it afterwards.

The sequence diagram below illustrates the typical flow of messages between your application, BSWebTracker, and how your tracking data finally ends up in Google.

As you can see from the diagram above, each time your application sends a tracking request, the class will just queue it for later. At the next run loop, it’ll pick up one request and send them over to the WebView. In turn the WebView will load the request and eventually Google Analytics gets to see your tracking request. After the WebView have completed a request, BSWebTracker will pickup another URL from the queue and send them over. This will continue until the last tracking request is completed. Should BSWebTracker tries to dequeue and see that the queue is empty, it’ll discards the WebView instance. 

One last note: currently BSWebTracker doesn’t do much error handling. If your website is down or otherwise cannot be reached, it’ll simply discard tracking requests and not saves them for later retry. It also doesn’t try to store the exact time when the tracking request occur and forward it to the analytics reports (e.g. backdates tracking action) and other fancy stuff. So probably the library will only be useful for online-type apps (like web browsers or instant messaging clients) and will need some adaptation to be used offline.

Get It Now

You can find BSWebTracker in Github, under the very liberal BSD open-source license. Please let me know if you find it useful and use it in your own app.

PS: I’ll always welcome a complementary license of your app ;-)

That’s all for now. Take care!

So you buy your domain, put up your landing page and waited. While waiting for a result, you repeat the same exercise nine more times, each with their own domain, landing page, and e-mail list. So you’ve just spent about $150 and 20 weeks of “after-hours” work to generate ideas, filter out the really sucky ones, write marketing copy, and put up landing pages for each surviving idea.

After a tiring five months, none of your 10 ideas generate any traction. Traffic is low and only your friends that you’ve pestered signed up. Then depression starts weighing in. You then think to yourself: you’re probably not an entrepreneur and probably be better continuing your day job instead.  At least the day job provides sustenance and you don’t need to generate ideas which fails anyway.

Or is it? Lean startup may be a viable methodology but you shouldn’t just blindly trust on it. It’s one way to “skin a cat”, but definitely not a religion (even then you shouldn’t blindly trust religious texts, but let’s save that for another discussion – let’s talk business for now, after all this is a biz-tech blog). Yes, your ideas are probably crappy – but to be fair, the whole Lean Startup craze may also be crappy.

Here’s the fallacy of the above “landing-page-then-see-what-happens” lean methodology:

• How your target customers can find the landing page?
• How can you get early adopters to trust you with their e-mail address?
• Have you done some validation before even putting up the landing page in the first place?
• Are you talking to your target customers using their language?

Keeping all of the above factors in mind, a landing page is a necessary but not sufficient component to launch your app. You really need to do some groundwork before putting up the landing page and deliver tangible value to your potential customers long before you ask them for money. Paying it forward, so to speak.

If you have something real to show – for software this is likely a beta version of the application – you will get:

• Early users who can provide feedback.
• Word-of-mouth marketing from those early users.
• Social proof saying that you’re not just there to harvest e-mail addresses and sell them to spammers.
• More opportunities to talk about your product – often gives SEO benefits (for example, release notes on placed on the website).

Scuttlebutt Example

When I started Scuttlebutt – our Yammer app – signup rates were very low. There wasn’t much text on the app’s landing page that Google can index.  The site was asking for an e-mail address with nothing in return and very few people were willing to give out their e-mail address fearing spam. Yes, I did saw several e-mail addresses tagged with Scuttlebutt’s website using Gmail’s disposable e-mail address trick – signifying that those people didn’t really trust me. 

But I got signups. Why? I did some validations before I bought the domain. There were a number of complaints on Yammer’s support forum about the need of a Mac app (complaints that Microsoft took down not long after the acquisition). In addition there were some questions on Quora showing there were at least some demand for it. Furthermore signups really took off after I’ve been pushing out releases – these were alpha & beta versions of the software. It’s not fully functional nor stable but it’s proof that I’m “for real” and not just trying to harvest people’s e-mail addresses.

Just look at the graph below. This came from MailChimp‘s “list growth” report showing the accumulative number of people who signed up for Scuttlebutt‘s launch list and stayed on that list until now. I’ve annotated it to show milestones as the software progresses and matures.

The official “start” of the project was in June 2012, the time that Microsoft announced that it’s buying Yammer. But really it starts way, way before it. I’ve experienced the need for a native Mac client myself and done some “market research” (e.g. googling, binging, and quoring around) to see if there is a demand.

I’ve also personally tried to contact some of the people who wanted such an app but received no reply whatsoever. Perhaps because I didn’t have anything tangible and I have no social proof nor any credibility that I can leverage at the time. Yet some of those very same people signed up to the beta list once I have a working application.

Then I sent out an offer, asking if people are daring enough to try alpha releases. The signup form was essentially a “notify me when we launch” list with a checkbox to opt-in for beta releases as well. There were 34 people who were offered for alpha releases and 11 opted in – so that’s a 30% conversion rate. Pretty neat huh?

It turned out that releasing crappy alpha versions were very useful. There were a number of important design decisions that were made in this phase that’s would be too hard to change if the app was already matured. Some who wanted the alpha releases even submitted UI mockups that I ended up incorporating in the application. (That’s “crowdsourcing” your UI Design ^_^).

So this is a screenshot from an early alpha version of Scuttlebutt…

After using the above alpha app, an early adopter came up with the following mockup…

Pretty neat, isn’t it?

Back to alpha releases and list growth. The inverse is also true – when I was lagging behind in releases, exponential growth stopped. Just look at the period from January to February. In that graph, you can see that growth was slightly lagging. Keep in mind that until 16 February only 11 people get to use the application – those in the alpha tester list. But word-of-mouth effects from those releases and SEO benefits from posting the release notes helped grow the list.

Then when I started sending out beta releases to a larger group of people, real growth starts. You can see for yourself in the graph. Subscriber count grows exponentially from February onwards. I was providing real value in terms of a working application that they can use on a daily basis, save for a few bugs here and there. It’s not just “a promise and a form” but it was something real and tangible.

What should you do?

If you have an app idea and you’re planning to bootstrap it yourself – or perhaps with just one or at most two other co-founders – with zero outside investments, here’s what I think you should do. 

• First put up a landing page and sign up form anyway. It’s not much useful by itself, but it’s your anchor on the web. Don’t waste too much time on the site or buy custom design, or even too much money on web hosting — it’ going to be a one-page site. Just state your value proposition and put a mailing list form for that. MailChimp has free and pay-as-you-go plans thus you don’t need to spend any money on this until you’ve gotten some traction.
• Start finding people that has the problem that you’re going to solve and contact them. Some entrepreneurs say that you should cold-call them but that’s going to be expensive if your target market is half a world away. You can start the relationship by email/Twitter/LinkedIn and then move on to Skype if it gets somewhere. But don’t count on getting replies from them.
• If you get people on your list, contact them personally using your business e-mail address. That is use yourname@yourcompany.com or yourname@yourproduct.com and not an anonymous email address like support@yourcompany.com (also don’t publish your own email address on the web or otherwise people won’t feel exclusive being contacted by you). Don’t use any mass-mailing software (not even MailChimp) for this.
• Make your app and release it as soon as you can. Despite of all those who say that you need to sell your product first. Pre-selling doesn’t work for software products – even Amy Hoy agrees on this. No, it doesn’t need to be perfect and you don’t need to stage a huge launch for your crappy initial release. Just cobble something up (you’re a competent coder, aren’t you?) that people can play with and work your way from there into a viable commercial product.

In short, stop worshipping that “lean startup” mantra — especially if you’re an un-funded solopreneur that is nowhere near the VC-infested Silicon Valley ecosystem. Put your head down, spirit up, fire up your favorite coding tool, and get down to work. You’ll need to get it out fast to people who need it and ask them whether it’s solving their problems.

If you want to have a barbershop, you don’t just rent an A4-sized plaque somewhere asking people whether they want a hair cut and write down their phone numbers, would you? No. You set up a spot under a nice shady tree then put up your shingle saying “Haircut $10″ and start cutting hairs. Then ask people how the experience was, give them a huge discount for being an early customer and leverage their word-of-mouth marketing.

Take care and good luck!

Apparently my original approach of monitoring HTTP responses for cookies wasn’t enough. Cookies added via JavaScript aren’t visible in the response headers. However “normal” web browsers acknowledges these JavaScript cookies and send them along with their comrades born in the headers. In light of this, you’ll also need to inspect the web scripting environment and also watch for cookies added there.

I found this out the hard way when Yammer did some changes sometime last week and broke Scuttlebutt‘s “show in website” functionality. Scuttlebutt is a Yammer client that allows the user to be logged simultaneously to the site. This is done by separating each WebView instance’s cookie storage – each account gets is own cookie space and therefore Yammer will store distinct session IDs for individual users in their respective cookie jars.

The Code

So I’ve extended my cookie storage to handle cookies obtained from the JavaScript environment. I’ve added a method that can parse JavaScript’s document.cookie string and add it to the cookie storage.

Unfortunately document.cookie only has the name/value pair of those cookies and none of the other attributes. Their paths, expiry dates, domains, and other attributes can’t be accessed from JavaScript. Hence I had to guess the other attributes and apparently these assumptions work quite well with Yammer at the moment:

• Use the document’s current URL as the path for searching existing cookies and for the domain of new cookies.
• If a cookie with the same name is already present, just update its value, nudge the expiry date, and keep all other attributes the same.
• Create new cookies as domain-global with five years’ expiry date, and don’t set the “secure” flag even if the current URL is HTTPS.

Without further ado, here is the method that parses JavaScript’s cookie string and creates or updates cookie instances as necessary.

-(void) handleWebScriptCookies:(NSString*) jsCookiesString forURLString:(NSString*) urlString
{
    if (![jsCookiesString isKindOfClass:[NSString class]]) {
        DebugLog(@"Not a valid cookie string: %@",jsCookiesString);
        return;
    }
    if (![urlString isKindOfClass:[NSString class]]) {
        DebugLog(@"Not a URL string: %@",urlString);
        return;
    }

    if ([@"undefined" isEqualToString:jsCookiesString] || [@"null" isEqualToString:jsCookiesString]) {
        DebugLog(@"Invalid cookie string");
        return;
    }
    NSURL* jsUrl = [NSURL URLWithString:urlString];
    if (!jsUrl) {
        DebugLog(@"Malformed URL String: %@",urlString);
        return;
    }
    
    NSString* const urlDomain = [jsUrl host];
    if (!urlDomain) {
        DebugLog(@"No domain in URL %@ - ignoring.",urlDomain);
        return;
    }
    
    NSArray* cookiesArray = [jsCookiesString componentsSeparatedByString:@";"];
    NSMutableDictionary* cookiesDict = [NSMutableDictionary dictionaryWithCapacity:cookiesArray.count];
    NSCharacterSet* whitespace = [NSCharacterSet whitespaceCharacterSet];
    for (NSString* cookiePair in cookiesArray) {
        NSArray* pair = [cookiePair componentsSeparatedByString:@"="];
        if (pair.count == 2) {
            NSString* key = [pair[0] stringByTrimmingCharactersInSet:whitespace];
            NSString* value = [pair[1] stringByTrimmingCharactersInSet:whitespace];
            if (key.length > 0 && value.length > 0) {
                // don't decode the cookie values
                cookiesDict[key] = value;
            }
        }
    }
    
    // five years expiry for JavaScript cookies.
    // why five years? Because it looks like Yammer's JavaScript-based cookies usually expires in five years.
    NSDate* const cookieExpiryDate = [NSDate dateWithTimeIntervalSinceNow:5 * 365.25f * 24 * 3600];
    
    // we got all  JavaScript's cookie name/value pairs in 'cokiesDict' Now find existing cookies and override their values.
    NSArray* existingCookies = [self cookiesForURL:jsUrl];
    for (NSHTTPCookie* existingCookie in existingCookies) {
        NSString* existingName = existingCookie.name;
        NSString* updatedValue = cookiesDict[existingName];
        if (updatedValue) {
            if (![updatedValue isEqualToString:existingCookie.value]) {
                // override
                NSMutableDictionary* cookieProperties = [NSMutableDictionary dictionaryWithDictionary:existingCookie.properties];
                cookieProperties[NSHTTPCookieValue] = updatedValue;
                cookieProperties[NSHTTPCookieExpires] = cookieExpiryDate;
                NSHTTPCookie* updatedCookie = [NSHTTPCookie cookieWithProperties:cookieProperties];
                [self setCookie:updatedCookie];
            }
            
            // we already found an existing one, don't add it as domain global cookie
            [cookiesDict removeObjectForKey:existingName];
        }
    }
    
    // now set the rest as domain-global cookies
    if (cookiesDict.count > 0) {
        NSString* cookieDomain = urlDomain;
        NSArray* domainComponents = [urlDomain componentsSeparatedByString:@"."];
        if (domainComponents.count > 2) {
            NSMutableString* makeDomain = [NSMutableString stringWithCapacity:cookieDomain.length];
            [domainComponents enumerateObjectsUsingBlock:^(NSString* component, NSUInteger idx, BOOL *stop) {
                if (idx == 0) {
                    return; // skip the first one
                }
                [makeDomain appendFormat:@".%@",component];
            }];
            cookieDomain = makeDomain;
        }
        
        NSString* const cookiePath = @"/";
        [cookiesDict enumerateKeysAndObjectsUsingBlock:^(NSString* cookieName, NSString* cookieValue, BOOL *stop) {
            NSMutableDictionary* cookieParams = [NSMutableDictionary dictionaryWithCapacity:6];
            cookieParams[NSHTTPCookieDomain] = cookieDomain;
            cookieParams[NSHTTPCookiePath] = cookiePath;
            cookieParams[NSHTTPCookieExpires] = cookieExpiryDate;
            
            cookieParams[NSHTTPCookieName] = cookieName;
            cookieParams[NSHTTPCookieValue] = cookieValue;
            
            NSHTTPCookie* cookie = [NSHTTPCookie cookieWithProperties:cookieParams];
            [self setCookie:cookie];
        }];
    }
}

The method takes in a string and a URL because the cookie storage is an application-logic class and shouldn’t be dependent on user interface components like WebView. Besides I also want the class to be portable on both OS X and iOS, just in case I want to do a mobile version of the app.

You use the method by feeding it with the document.cookies and document.URL strings obtained from the JavaScript environment. This is done whenever the user clicks on any link on the web page so that the cookie storage can snatch the web scripting environment’s list of cookies before the web server wants it.

Here’s how you plug in the call to the method above. You’ll need it in WebView‘s decidePolicyForNavigationAction delegate method so that you’ll get a chance to take a snapshot of JavaScript’s cookies before the web view starts spewing HTTP requests. 

- (void)webView: (WebView *) webView decidePolicyForNavigationAction: (NSDictionary *) actionInformation request: (NSURLRequest *) request frame: (WebFrame *) frame decisionListener: (id < WebPolicyDecisionListener >) listener
{
    // … do whatever else you need to do here …
    WebScriptObject* webScript = [webView windowScriptObject];
    NSString* jsCookies = [webScript evaluateWebScript:@"document.cookie"];
    NSString* jsURL = [webScript evaluateWebScript:@"document.URL"];

    // Get the cookie storage – you should keep this instance alive with every other request/WebView
    // that you have with this user. It's also a good idea to persist the storage.
    BSHTTPCookieStorage cookieStorage = …;
    [cookieStorage handleWebScriptCookies:jsCookies forURLString:jsURL];

    // … then let navigation proceed.
    [listener use];
}

That’s just about it. Enjoy! You can find a complete listing of the updated cookie storage in this gist. It took me a few days to come to this conclusion and made a fix for it – I hope you’ll find this useful and save you time and grief.

Take care.

How about ODBC? Macs are certified Unix boxes nowadays and since ODBC is available for Unix, it should also available on Macs.  But Unix ODBC only provides source-level compatibility and thus often requires recompilation of the database drivers’ source code. Unfortunately many database vendors doesn’t provide source code of their ODBC drivers.

There are a number of third-party ODBC driver providers that sells Mac drivers. But how far can you trust these third parties? How complete are their implementations? What about some edge cases that have been solved by the “original” drivers but doesn’t trickle down to third-party drivers? Worse, what if nobody provides a Mac-compatible ODBC driver for your chosen database?

Then How?

So I have this crazy idea: why not use JDBC instead? I couldn’t think any production-quality SQL database that doesn’t have a JDBC driver. Since it’s pure Java, these drivers should also runs on Macs unchanged. Most of the app will still be written in Cocoa to provide the superior user experience and performance that we’ve been accustomed to – but it uses the Java Virtual Machine (JVM) as a library just to run the JDBC drivers to talk to their respective SQL databases.

Benefits

• Guaranteed 100% compatibility with the database – since the drivers are written by the vendors themselves.
• Retains all the great performance and integrations of a native Cocoa app.

Softening the Blow

Is it Radical?

Yes it is… NOT! I believe CyberDuck (the open source Mac FTP Client) also uses this approach. They use Java-based Apache Commons Net as part of their networking code. I found out about it from the Java exceptions dumped in their log messages in the Console.

What about ODBC-JDBC bridge? Yes it may be an option. OpenLink provides a Mac version of their ODBC-JDBC bridge. But remember the law of leaky abstractions – you’re adding yet another 3rd party component between your app and the database. This is yet another component that your user needs to configure and could cause havoc it not set up properly. Not to mention that Apple practically deprecated ODBC since they stopped distributing ODBC Administrator since Snow Leopard.

So there you have it – I’m pondering to do a project on this if there’s significant interest to it.

That’s all for now. Take care!

• What if you get a null value?
• How do you ensure you will get a number object and not a stringified number?
• How do you handle dates?

If any of those cases still haunt you at night, you’ll find your solution right here.

Handling NULL returns

When you read in a value from a JSON dictionary via [NSDictionary objectForKey:], you will encounter one of these cases:

• You’ll get the value that you want – the happy case.
• You’ll get a nil return – meaning that the key wasn’t there in the first place.
• You’ll get an instance of NSNull – meaning that the key exists but the value is null.

It’s the last case that’s a bit puzzling for many Cocoa developers just starting out with JSON. However the protocol does allow null values to be returned. Here is an example JSON snippet which causes that last case:

{
    aKey: null
}

As you can see for yourself, it says that a key exists but the value is null. When you access that dictionary, the value of aKey would be the instance of NSNull (a singleton object), instead of nil. One potential use for that construct is to explicitly clear out a value or remove object relationships in the client side. 

But sometimes you might want to treat null and nil as equivalent. That is you just want either the number or string object that you wanted or nil otherwise – without caring for null conditions. An easy way to do this is to add some category methods to NSNull that returns nil so that you don’t need to explicitly check for NSNull object being returned to avoid “unrecognized selector sent to instance” exceptions.

@implementation NSNull (JSONSupport)

-(NSString*) stringValue {
    return nil;
}

-(NSNumber*) numberValue {
    return nil;
}

-(float) floatValue {
    return 0;
}

-(double) doubleValue {
    return 0;
}

-(BOOL) boolValue {
    return NO;
}

-(int) intValue {
    return 0;
}

-(long) longValue {
    return 0;
}

-(long long) longLongValue {
    return 0;
}

-(unsigned long long) unsignedLongLongValue {
    return 0;
}

@end

With the above methods in place, you can use clean constructs such as the following when accessing your JSON parser results:

NSDictionary* json = …
int numberOfThings = [json[@"things_count"] intValue];

 Which will safely return 0 and not throw an exception even if the server returns null for things_count.

Handling String / Number Conversions

Sometimes when you access a JSON value and you expect a number, you might get a string object instead. This could happen if the server decides to enclose the number between “quotes” – perhaps if it thinks that the number value is too large for you to handle. Similarly you might receive a unique identifier as a stringified number but you want to store it as a 64-bit integer for efficiency or speed (which makes sense if you’re saving the value into a local database).

Then you’ll need to coerce the value into the data type that you want, like so:

NSDictionary* json = …
unsigned long long uniqueID = [json[@"id"] unsignedLongLongValue];
NSString* foreignID = [json[@"foreign_id"] stringValue];
… 

The above works fine if you’re always sure that the server (and the JSON parser) will always return something in id and foreign_id fields that yields to an NSNumber instance. However it’s not a perfect world and there could be a chance that you’ll get a string instead. So it’s a good idea to mirror those methods that NSNumber has and add them to NSString too so that both of these classes have some more methods in common that’ll make them interchangeable:

@implementation NSString (JSONSupport)

-(NSString*) stringValue 
{
    return self;
}

-(unsigned long long) unsignedLongLongValue 
{
    return strtoull([self UTF8String], NULL,0);
}

-(NSNumber*) numberValue {
    NSString* trimmed = [self stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];
    
    NSRange locationOfDecimal = [trimmed rangeOfString:@"."];
    if (locationOfDecimal.location == NSNotFound) {
        // integer
        NSUInteger length = [trimmed length];
        if (length == 0) {
            return 0;
        }

        if (length >= 10) {
            // longer than +/- 2 147 483 647
            if ([trimmed hasPrefix:@"-"]) {
                return [NSNumber numberWithLongLong:[trimmed longLongValue]];
            } else {
                return [NSNumber numberWithUnsignedLongLong:[trimmed unsignedLongLongValue]];
            }
        } else if(length >= 5) {
            // ensure can be +/- 32 767
            if ([trimmed hasPrefix:@"-"]) {
                return [NSNumber numberWithInt:[trimmed intValue]];
            } else {
                return [NSNumber numberWithUnsignedInt:(unsigned int)[trimmed unsignedLongLongValue]];
            }
        } else if(length >= 3) {
            // ensure can be +/- 128
            if ([trimmed hasPrefix:@"-"]) {
                return [NSNumber numberWithShort:(short)[trimmed intValue]];
            } else {
                return [NSNumber numberWithUnsignedShort:(unsigned short)[trimmed unsignedLongLongValue]];
            }
        } else {
            if ([trimmed hasPrefix:@"-"]) {
                return [NSNumber numberWithChar:(char)[trimmed intValue]];
            } else {
                return [NSNumber numberWithUnsignedChar:(unsigned char)[trimmed unsignedLongLongValue]];
            }
        }
    } else {
        // floating-point
        return [NSNumber numberWithDouble:[trimmed doubleValue]];
    }
}
@end

@implementation NSNumber (JSONSupport)

-(NSNumber*) numberValue 
{
    return self;
}

@end 

Handling Date Values

JSON doesn’t say anything much on how to specify dates and timestamps. Most implementations expresses dates as human-readable strings, but there are several de facto prominent date formats that are being used. Even worse, the date format can even change without notification as what Twitter done back in 2007.

Facing this, you’ll need to be lenient and accept a number of popular date formats when parsing date strings that you’ve obtained in JSON. Fortunately I’ve identified a comprehensive set of date formats that occurs pretty commonly appearing in JSON and other human-readable Internet protocol data formats that you can readily use in your application:

@implementation NSDate (JSONSupport)

+(NSDate*) dateWithFuzzyString:(NSString*) dateString 
{
    if (!dateString) {
        return nil;
    }
    NSDate* result = nil;
    
#if !TARGET_OS_IPHONE
	result = [NSDate dateWithString:dateString];
	if (result) {
		return result;
	}
	result = [NSDate dateWithNaturalLanguageString:dateString];
	if (result) {
		return result;
	}
#endif
	
    // Unicode Technical Standard #35: Date Format Patterns
    // http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns (the page is really slow to load)
    // http://webcache.googleusercontent.com/search?q=cache:EzQS_WnAi1IJ:unicode.org/reports/tr35/tr35-10.html+cached:http://unicode.org/reports/tr35/tr35-10.html%23Date_Format_Patterns (alternative from google's cache).

    static NSString* const formats[] = {
        //Sample date: "Tue May 17 06:18:25 +0000 2011" (used by Twitter) 
        @"EEE MMM dd HH:mm:ss ZZZ yyyy",
        // sample date: Tue, 8 Dec 2009 21:30:43 +0800
        @"EEE, d MMM yyyy HH:mm:ss ZZZ",
        // sample date: Friday, 1 July 2001, 11:45 AM
        @"EEEE, d MMMM yyyy, hh:mm a",
        // sample date: 05/22/2007 03:15:23 UTC  (Twitter once switched to this format)
        // http://groups.google.com/group/twitter-development-talk/browse_thread/thread/0ed59aaaff01661c/80ef61a443768587
        @"dd/MM/yyyy HH:mm:ss zzz",
        // sample date: "December 10, 2009"
        @"MMMM, dd yyyy",
        // sample date: "Dec 10, 2009"
        @"MMM, dd yyyy",
        // sample date: 10-Dec-09
        @"dd-MMM-yy",
        // sample date: 10 Dec 09
        @"dd MMM yy",
    };
    
    
    NSDateFormatter* fmt= [NSDateFormatter new];
	fmt.formatterBehavior = NSDateFormatterBehavior10_4;
	[fmt setLenient:YES];
	for (NSUInteger i=0; i<ARRAY_COUNT(formats);i++) {
        fmt.dateFormat = formats[i];
		result = [fmt dateFromString:dateString];
		if (result) {
			return result;
		}
	}	
    return nil;    
}

-(NSString*) stringValue 
{
    // print date in MIME date format
    // http://tools.ietf.org/html/rfc5322#section-3.3
    // sample date: Tue, 8 Dec 2009 21:30:43 +0800

    NSDateFormatter* fmt= [NSDateFormatter new];
    fmt.dateFormat = @"EEE, d MMM yyyy HH:mm:ss ZZZ";     // sample date: Tue, 8 Dec 2009 21:30:43 +0800
    return [fmt stringFromDate:self];
}

@end

So that’s all there is to it. I’ve packaged all the code snippets above into a gist for you to use – open source under BSD license. Enjoy!

If you’re looking to design a mobile application to further your company’s public relation efforts or otherwise motivate the public to do your bidding, this article will show you how. These are a hard-earned lessons that we obtained during the Earth Hour hackathon last January. 

So the backstory is that I attended an ideation competition last January organized by Newton Circus as part of their UP Singapore project. Structured as a hackathon, the event was primarily driven by the World Wildlife Fund (WWF) as a way to crowdsource mobile application ideas for their upcoming Earth Hour event. This is the last of a two-part series and speaks about the idea that we developed during the event, how we chose to strike out some elements of our idea that turned out to be crucial for winning the event, and what were the key elements of the winning idea that you can apply to your own ideation process. Whereas the first part focuses on the team dynamics during the event.

Lessons Learned

If you’re trying to develop a mobile application to motivate people to do what you want – as long as it’s within legal and moral bounds – these are the key elements that you need to have:

• Enlist people to a higher cause. Intrinsic motivation is the best kind and people have an innate desire be part of something important and feels greater than they are – also be part of a community that opts-in to the same cause. This is probably the most important point than everything else below.
• Feature a virtual pet (tamagotchi) whose well-being is reflected in how the user’s actions matches those that you want them to do. Likely cute-looking pets with large eyes. This triggers people’s nurturing instinct and builds the reward/punishment mechanics into your application without needing to financially reward nor physically punish them. Arguably you may think that this would only be effective for female users, but remember that teenage boys also like to “dress-up” their cars (as in adding accessories, sound system upgrades, and the like), personal computers, or other objects of affection – so this approach should also work for male users, given the right type of virtual pet.
• Have pictures, lots of them. Encourage people to take photos with your application, submitting them, and show them off to their friends. People who are primarily visual thinkers forms about 60% of the population and 80% of players are socializers. Socializing photo taking is what made Instagram a big success and you can grab some of that success too.
• Incorporate social challenges. Again taking advantage of the socializers as the majority, challenges would be more fun if it’s tied to the user’s real-world friends and help foster relationships between them. Levelling up and surpassing the scores of people you know would likely be more achievable and fun rather than trying to match the world champion that’s light years ahead.
• Don’t be yet another social networking site. You’ll face an uphill battle to get people on board. It’ll be a chicken-and-egg problem since people won’t use a social network site or applications if most of their friends are not already on them. Instead identify your primary target demographic and integrate your specific experiences with the sites that they are already using. In practice, there isn’t that many social network sites tochoose from. 
• Make this a free app to minimize friction in installing it. Remember that these kind of apps aren’t likely to solve specific pain points that the user has – probably solves your pain points more – and getting users to pay for it will be a tough sell. Having a paid app also inhibits the network effect that hinders the app’s mass adoption.

Our Idea

We decided to find the flaws in the Earth Hour “I Will If You Will” campaign and our proposal will be about fixing those flaws. Essentially the “I Will If You Will” campaign is a challenge posted by members of the public – and sometimes famous people – to do something silly if some number of people wants to do a particular good deed for the planet. The idea is to promote awareness for various small everyday actions that helps the ecosystem while having fun in the process. 

Our team saw that the biggest flaw in this campaign is the lack of validation in the “you will” part. All that they need to do is click on the “Accept Challenge” button to be counted as a person who did that particular challenge. There is no way to find out whether the challenge was really fulfilled. Another problem area is that the challenges tend to be one-off actions and doesn’t encourage people to be consistent in doing it all the time. That won’t be much help for the long run. For example, turning up their air-con temperature by one degree won’t save much energy if only done for one day.

We saw that there need to be some way to validate the actions performed and keeping people engaged in incorporating environmentally-friendly actions in their daily lives. Then we designed this elaborate process of:

• Accepting challenges and announcing the challenge accepted.
• Posting proof of their good deed performed.
• Crowdsourced validation through votes (both up and down votes à’la Stack Exchange) and peer pressure.
• Building communities and tribes by facilitating camaraderie with nearby people who have accepted similar challenges.

Also we designed a reminder system to keep people engaged and continue performing fulfilling their challenges and thus doing good deeds to the environment. All of these is unified by an “earth profile” of the person that shows the “earth points” that they have accumulate. Furthermore their continuous challenge fulfillments provides nurture to a virtual pet and thus the pet’s well-being is reflected through how much good deed they’ve done for the environment and how consistent they’re doing it.

Because discussions were prolonged to very late at night we needed to quickly streamline the features and package it into a coherent workflow. Unfortunately because the team member who suggested the virtual pet idea (named “Bob”), in the process of streamlining that feature got removed along with the challenges, reminders, and various other tidbits.

We ended up of having a very streamlined “photo taking” app that augments Earth Hour’s “I Will If You Will” challenge. It focuses on the “You Will” part and allows people to submit evidences of their challenge fulfillment instead of just clicking on the “Accept Challenge” button. In turn this photo is posted to their Facebook and Twitter accounts to show their friends that they have done this good deed (and also somewhat validates the act) and to encourage their friends to do a similar good deed.

In retrospect we should have kept the virtual pet and have more iterations on making the social challenges more engaging and fun. Perhaps iterating on the virtual pet (“bob”) and make it more visually appealing thus attractive to the judges.

Anyhow you can find a copy of our presentation and clickable mockup of the app below. That’s all for now. Until next time!

The World Wildlife Fund wanted a mobile application to support their upcoming Earth Hour event and similarly their “I will if you will” environmental awareness campaign. They worked with Newton Circus and UP Singapore and organized an event to crowdsource the idea. In other words, they arranged a contest so that many people will come and contribute their ideas for free. It was framed as a hackathon event that took place in NUS’ U-Town complex at 25-27 January 2013.

Since the dayjob company was one of this event’s sponsors, I volunteered to be a participant. There were five of us from the dayjob company and we took in three additional participants as part of the group. Our team consisted of primarily technical researchers and software developers but the other three participants did not have any software engineering backgrounds.

These are the lessons I learned during the hackathon:

• Lean & mean is still the best.
• Get down to work fast.
• Keep it simple but not simpler.

On Being Lean & Mean

Having a small team is important since it keeps the discussion focused. However each team member need to be both a do-er and a thinker so that they all constantly contributes during their entire process. In this sense, a do-er is some kind of hands-on skills but not necessarily programming skills – mainly graphics design, writing, organizing thoughts – in general skills that produces immediate results. Strange enough, there wasn’t much time to do some actual programming during the event, but nonetheless application design skills will come in handy. Finally pure managers with no technical skills but only armed with extensive NATO (No Action, Talk Only) politician’s skillset won’t be much useful.

Our group has plenty of room for improvements in this area. Team members got pulled out at various times during the event either because of personal commitments or professional tasks. The dayjob company was one of the sponsors who provided a software to be used during the event and there wasn’t any dedicated technical support crew and hence at time we needed to help the organizers on some technical issues with the software. Note that this was an enterprise software that isn’t generally available for casual tinkering.

Technical issues aside, there weren’t much synergy in the various skillset of the group members. Some members were having difficulties in grasping some of the basics of designing a mobile application – even though there were no programming involved. Basic stuff like understanding the basic concepts of a scrolling list, insight on what various other mobile applications that are available, or even keeping up with the general flow of the group’s discussion. Furthermore there was more than one alpha-person in the group and some of them weren’t much of a do-er at the first half of the time – although close to the end they finally rolled up their sleeves and made worthwhile contributions.

On Getting Down to Work

The effective time available for real work is one day. It will be best if you can fit it in an 8-hour day and not 12-hour day as fatigue will creep in and make you ineffective by the 7th hour. There isn’t much time to go through all the four stages of group development – once your group is formed on Friday night, and have its initial discussion, the group should have completed the norming stage by Saturday morning.

The diagram above shows how it should have happened. As you can see for yourself, the actual work happens in Saturday and there isn’t much time available for the group to warm up – it needs to briskly go through the storming and norming phases and get down to work fast. There need to be several iterations and the team shouldn’t pull an all-nighter for these idea sessions since the creative brain will just grew wary and productivity will go south.

Sadly our group took too much time in the storming and norming phases and did not have enough iterations. A possible cause can be attributed to the lack of insight on how a software product should be designed and what are currently available in the market. Another possible problem points is the presence of more than one dominating personality. Then again the team got distracted because some team members need to take care other commitments outside of the event.

On Keeping It Simple but not Simpler

Don’t throw good ideas away. How do you make sure you’re not throwing out good ideas? By rapid iteration and reviews. You’ll really need to quickly iterate through ideas within the first four hours of Saturday and have it finalized just after lunch time so you can get down to fleshing out the details and have it roughly done within an eight hour day.

Our group went through a rough storming period at the first half of Saturday and there were many ideas generated but made through only one iteration. When we finally taken a step back to take a birds’ eye view of the idea, feature-set, and flow of the application, we realized that it was an incoherent set of features and then threw most of it away. This was done when almost half of the group members checked out and went home. But in hindsight there was one good feature that we had but threw away. Why we realized the feature was a good idea? Because the winning proposal has that feature (stay tuned and I’ll describe more on the idea on the next post).

Conclusion

The hackathon event was interesting if you have a weekend to spare and you’d like to try your hand working in focus groups. In retrospect, the dynamics were pretty similar to what happened during my MBA in ITB but with a significantly compressed time frame and there was no 3-5 pages of Harvard-published case study to read beforehand. On the other hand it might not be an appropriate venue if you’re looking for (or validating) an idea that you can launch as a solopreneur.

So I tried to work things around by coding screen elements based on the screen percentage ratio. I have completed in making my app versatile enough to be displayed in Android screens which are normal, large and extra large. I tested it using the emulator on Samsung Galaxy S, Galaxy S2, Galaxy S3, Galaxy Ace, Note, Note 2, Google Nexus 7, HTC One X. I do not want to support for smaller screens since I found most of the devices with small screens are running Android OS lower than 2.3.3.

My approach is basically the same with the post I made on the 16th of Jan. But here I would like to discuss about coding TextView and EditText, so their display will be based on the screen ratio. My approach might not be perfect, but I see it is sufficient enough to make my app versatile.

1. Decide the dimension of a label you want to display. Its height or width. Lets say based on the screen below, I want to display the word ‘Yellow’ around 15% of the screen width, and for the display ’00:00′, I want the first ’00′ to be 24% of the screen.

2. Resize the dimension of the current TextView or EditText. You can only resize the elements once you call the setContentView() method.
a.Get the dimension of the screen.

		WindowManager w = getWindowManager();

		Display d = w.getDefaultDisplay(); 
		int measuredwidth = d.getWidth(); 
		int measuredheight = d.getHeight(); 

b. We are going to resize the TextView or EditText using the below method. I don’t want to be too precise in creating the dimension. The method has three parameters. The first is the element to be resized, the second is the minimum ratio of the element, the third parameter is the maximum ratio of the element.

c. Call the method above and update the text elements. I only called the previous method once or twice, then I just resize the other text elements based on the returned value. I found my application loads a lot faster when I do this.

3. Share the standard size between Activities. We will need to do this, because we want the size of the screen header, footer, labels to be consistent between screens.

That’s it. Below are the screen displays when I try to run my app on Galaxy Ace, Galaxy S3, and Google Nexus 7. I got the configuration from http://en.wikipedia.org/wiki/Comparison_of_Android_devices#Smartphones

Display on Galaxy Ace emulator, the screen display is 480×320 HVGA, with 3.5 inch size.

Display on Galaxy S3 emulator, the screen display is 1280×720 HD, with 4.8 inch size.

Display on Google Nexus 7 emulator, the screen display is 1280×800 HD, with 7.27 inch size. Please don’t mind the Devonthink label displayed on the left. It is from my own system.

It hope it helps on you development :).

Regards
Aireen Deviani

Below is the screen from Samsung Galaxy S3.

Below is the screen from Samsung Galaxy S2.

At first I thought it’s because Galaxy S3 is categorised as a “Large” screen, and Galaxy S2 is categorised as a “Normal” skin. But apparently the are both categorised as “Normal” screens. I noticed it by slightly modifying the layout for the normal layout. Perhaps it is because I chose Android 2.3.3 as my development platform, I have no idea, but I chose 2.3.3 because by doing so, I can support a larger pool of devices.

Things appear to be in a dead end, and I was thinking whether I should just support Samsung Galaxy S3 devices. But then, my husband recommended me to try to use a more HTML like approach. Instead of letting the Android framework determine the sizes of the screen elements based on the dpi of the elements, the approach is to specify the screen elements programmatically as a percentage of the screen width and height.

At first I was reluctant doing the experiment, but then I decided to give it a try. After trying here and that his solution appears to be a working solution. Here I am sharing with all of you on the approach I have taken.

1. Measure the height and width of the screen.

		double measuredwidth = 0;
		double measuredheight = 0;
		WindowManager w = getWindowManager();

		Display d = w.getDefaultDisplay(); 
		measuredwidth = d.getWidth(); 
		measuredheight = d.getHeight(); 

2. Declare the layout of your screen as usual using the xml files. We will only modify it programmatically.

3. Modify the dimension of your screen element based on the screen width and height. Below is a sample of the code.

 

		RelativeLayout.LayoutParams ballsParam = new RelativeLayout.LayoutParams(ViewGroup.LayoutParams.FILL_PARENT, 		ViewGroup.LayoutParams.WRAP_CONTENT);
		int topMarginBalls = (int) (measuredheight*0.02);
	    ballsParam.topMargin=topMarginBalls; 
	    int widthMarginBalls = (int)(measuredwidth*0.9);
	    ballsParam.width = widthMarginBalls;
	    int leftmargin = (int)(measuredwidth*0.05);
	    ballsParam.leftMargin = leftmargin;
	    ballsParam.height =  (int)(measuredheight*0.18);
	    RelativeLayout ballsLay = (RelativeLayout)findViewById(R.id.containBalls);
	    ballsLay.setLayoutParams(ballsParam);

4. Repeat the step for each of your screen element.

5. Run the emulator or install it to your device to see it in action.

Below is the modified layout using the new logic. It is not finished yet, but I hope you get the picture.

The display from Samsung Galaxy S3.

The display from Samsung Galaxy S2.

Of course, I will also test the application on the emulator to emulate other devices. If you don’t hear anything about me, then there is no problem. I will update you if there is an issue to the solution.

Regards
Aireen Deviani

I encountered this exact problem while working on Scuttlebutt – our upcoming Yammer client. Although Yammer provides a REST API for 3rd party clients, there are a number functionalities that are absent from the API and thus need to fall back to Yammer’s web interface. Unfortunately the web interface doesn’t make use of the OAuth2 access token normally used by the REST API but instead it relies on a number of cookies that were set just after the user logs in. If Scuttlebutt only support one account, this shouldn’t be a problem since it can just use Cocoa’s URL loading system to handle those cookies. But supporting multiple Yammer accounts means needing to have a separate “cookie space” for each account and that means I needed to implement my own cookie storage and plug it in to Cocoa’s web client infrastructure.

How Cookies Work

In simple terms, an HTTP cookie is a key-value pair set by a web server as it sends a web page back to the browser. In turn the web browser is expected to return those key-value pairs back to the web server as it requests subsequent pages from the same server. Of course there are variations to that generic flow such as the cookie’s scope – which web pages that can also receive those cookies apart from its originating web page, how long should the browser keep the cookie, and various other tidbits. Wikipedia has a more extensive overview on HTTP cookies if you like to dive deeper on this.

Because cookies are set by the server and then sent back by the browser, there are two integration points where you need to handle cookies from a web client’s perspective:

1. Extract the cookies from an HTTP response and save them somewhere.
2. For each HTTP requests, decide which cookies that are appropriate and embed it in the request.

Plugging-in Your Custom Cookie Storage

By default the URL Loading System handles cookies for you and will save these cookies in a shared location. In OS X, cookies are shared on a per-user basis. All applications will share the same set of cookies as far as the user is concerned, but different users of the same machine will have their own set of cookies shared across all applications that they use. However there is no notion of multiple users on an iOS device and thus cookies are private for each application.

Both of those approaches imply that an application cannot present the illusion of more than a single user for a given website. To do that, you need to disable Cocoa’s cookie handling system and plug in your own implementation.

Plain HTTP Request / Response

To plug in your own cookie handling system to HTTP requests you make yourself, you’ll need to call [NSMutableURLRequest setHTTPShouldHandleCookies: NO] to disable the system’s built-in cookie handling. Then you’ll need to add in those cookies to the HTTP headers just before you run the request.

The code for a request could look like this:

// requestURL is the target URL
NSMutableURLRequest* request = [NSMutableURLRequest requestURL:requestURL];

// disable the default cookie handling
[request setHTTPShouldHandleCookies:NO];

// cookieStorage is your custom cookie storage object 
// which should add in the appropriate cookies as HTTP header values
[cookieStorage handleCookiesInRequest:request];

// run the request
NSData* result = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error]

Whereas the code for handling a response looks like the following:

NSHTTPURLResponse* response = …;

// cookieStorage is your custom cookie storage object 
// which should scan for cookies in the response's HTTP headers and save them for later.
[cookieStorage handleCookiesInResponse:response];

You can use a similar approach to the above when you use AFNetworking‘s AFHTTPRequestOperation class. I’ll explain more on cookieStorage and handleCookiesInRequest: later in this article.

Plugging Your Own Custom Cookie Storage to the WebView class

Adapting a WebView to use your own cookie storage is also quite similar. The primary difference is that instead of creating your own NSHTTPRequest and NSHTTPResponse instances, you’ll need to implement WebView’s delegate methods so you can modify the ones that it uses. You do this in your WebResourceLoadDelegate protocol implementation and set your implementation object as the WebView‘s resourceLoadDelegate. Implement these methods of the protocol to hook WebView‘s URL loading system to your cookie handling code:

• webView: resource: didReceiveResponse: fromDataSource:
• webView: willSendRequest: redirectResponse: fromDataSource:

The following code snippet shows you how to do this:

- (void)webView:(WebView *)sender resource:(id)identifier didReceiveResponse:(NSURLResponse *)response fromDataSource:(WebDataSource *)dataSource
{
	if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
		// cookieStorage is your cookie storage implementation.
		BSHTTPCookieStorage* cookieStorage = ...;
		[cookieStorage handleCookiesInResponse:(NSHTTPURLResponse*) response];
	}
}


- (NSURLRequest *)webView:(WebView *)sender resource:(id)identifier willSendRequest:(NSURLRequest *)request redirectResponse:(NSURLResponse *)redirectResponse fromDataSource:(WebDataSource *)dataSource
{
	// cookieStorage is your custom cookie storage implementation.
	BSHTTPCookieStorage* cookieStorage = ...;
	if ([redirectResponse isKindOfClass:[NSHTTPURLResponse class]]) {
		[cookieStorage handleCookiesInResponse:(NSHTTPURLResponse*) redirectResponse];
	}
	
	NSMutableURLRequest* modifiedRequest = [request mutableCopy];
	[modifiedRequest setHTTPShouldHandleCookies:NO];
	[cookieStorage handleCookiesInRequest:modifiedRequest];
	return modifiedRequest;
}

You’ll need to capture cookies both when the WebView receives a response and when it receives a redirect. That’s why there are calls to handleCookiesInResponse in both method implementations. Whereas sending cookies is only done in one place,  webView: willSendRequest: redirectResponse: fromDataSource: that is called when the WebView is about to execute an NSURLRequest and gives you a chance to modify that request.

Onwards to Implementation!

As you can see from the above usage scenarios, these are the bare minimum external interfaces that you need to write a cookie storage class:

• -(void) handleCookiesInResponse: (NSHTTPURLResponse*) response;
• -(void) handleCookiesInRequest: (NSMutableURLRequest*) request;

The first method above reads HTTP response headers for cookies and saves those cookies when found. Whereas the second method uses the URL in the request and modifies the HTTP headers to add in the appropriate cookies for that URL.

Accordingly the class should also need an internal method to save cookies are found in a response and another one to determine what cookies that are applicable for a given URL:

• - (void) setCookie: (NSHTTPCookie *) aCookie;
• - (NSArray *) cookiesForURL: (NSURL *) theURL;

Caveat Emptor!

If you need to persist your cookies, please be aware that NSHTTPCookie doesn’t support serialization. As of OS X 10.8 and iOS 6.0 the class still doesn’t implement the NSCoding interface that’s needed to serialize the object into persistent storage. Fortunately it’s pretty straightforward to add serialization support to the class via an Objective-C Category (hint: use the properties and initWithProperties: methods to convert the between NSHTTPCookie and NSDictionary objects).

Introducing BSHTTPCookieStorage

I’ve coded up a bare-bones HTTP cookie storage implementation class that you can find below. It’s a pretty basic implementation and doesn’t support cookie expiration (e.g. cookies are retained indefinitely until overwritten by another one). However the cookie storage supports NSCopying and NSCoding protocols and thus can be cloned and saved to persistent storage. This is the same class that Scuttlebutt uses as part of its Yammer API access classes.

BSHTTPCookieStorage.h

//
//  BSHTTPCookieStorage.h
//
//      Created by Sasmito Adibowo on 02-07-12.
//  Copyright (c) 2012 Basil Salad Software. All rights reserved.
//  http://basilsalad.com
//
//  Licensed under the BSD License <http://www.opensource.org/licenses/bsd-license>
//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
//  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
//  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
//  SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
//  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
//  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
//  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
//  THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

#import <Foundation/Foundation.h>


/**
 Stores cookies.
 */
@interface BSHTTPCookieStorage : NSObject<NSCoding,NSCopying>

- (NSArray *)cookiesForURL:(NSURL *)theURL;

- (void)setCookie:(NSHTTPCookie *)aCookie;

/**
 Removes all stored cookies from this storage
 */

-(void) reset;

-(void) loadCookies:(id) cookies;
-(void) handleCookiesInRequest:(NSMutableURLRequest*) request;
-(void) handleCookiesInResponse:(NSHTTPURLResponse*) response;


@end


// ---


@interface NSHTTPCookie (BSHTTPCookieStorage) <NSCoding>

@end

// ---

BSHTTPCookieStorage.m

//
//  BSHTTPCookieStorage.m
//
//  Created by Sasmito Adibowo on 02-07-12.
//  Copyright (c) 2012 Basil Salad Software. All rights reserved.
//  http://basilsalad.com
//
//  Licensed under the BSD License <http://www.opensource.org/licenses/bsd-license>
//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
//  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
//  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
//  SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
//  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
//  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
//  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
//  THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


// this is ARC code.
#if !__has_feature(objc_arc)
#error Need automatic reference counting to compile this.
#endif

#import "BSHTTPCookieStorage.h"


@interface BSHTTPCookieStorage() <NSCoding>

/*
 Cookie storage is stored in the order of
 domain -> path -> name
 
 This one stores cookies that are subdomain specific
 */
@property (nonatomic,strong,readonly) NSMutableDictionary* subdomainCookies;

/*
 Cookie storage is stored in the order of
 domain -> path -> name
 
 This one stores cookies global for a domain.
 */
@property (nonatomic,strong,readonly) NSMutableDictionary* domainGlobalCookies;


@end


@implementation BSHTTPCookieStorage

@synthesize subdomainCookies = _subdomainCookies;
@synthesize domainGlobalCookies = _domainGlobalCookies;

- (void)setCookie:(NSHTTPCookie *)aCookie
{
    // only domain names are case insensitive
    NSString* domain = [[aCookie domain] lowercaseString]; 
    NSString* path = [aCookie path];
    NSString* name = [aCookie name];
    
    NSMutableDictionary* domainStorage = [domain hasPrefix:@"."] ? self.domainGlobalCookies : self.subdomainCookies;
    
    NSMutableDictionary* pathStorage = [domainStorage objectForKey:domain];
    if (!pathStorage) {
        pathStorage = [NSMutableDictionary new];
        [domainStorage setObject:pathStorage forKey:domain];
    }
    NSMutableDictionary* nameStorage = [pathStorage objectForKey:path];
    if (!nameStorage) {
        nameStorage = [NSMutableDictionary new];
        [pathStorage setObject:nameStorage forKey:path];
    }

    [nameStorage setObject:aCookie forKey:name];
}


- (NSArray *)cookiesForURL:(NSURL *)theURL
{
    NSMutableArray* resultCookies = [NSMutableArray new];
    NSString* cookiePath = [theURL path];
    
    void (^cookieFinder)(NSString*,NSDictionary*) = ^(NSString* domainKey,NSDictionary* domainStorage) {
        NSMutableDictionary* pathStorage = [domainStorage objectForKey:domainKey];
        if (!pathStorage) {
            return;
        }
        for (NSString* path in pathStorage) {
            if ([path isEqualToString:@"/"] || [cookiePath hasPrefix:path]) {
                NSMutableDictionary* nameStorage = [pathStorage objectForKey:path];
                [resultCookies addObjectsFromArray:[nameStorage allValues]];
            }
        }
    };

    NSString* cookieDomain = [[theURL host] lowercaseString];
    
    cookieFinder(cookieDomain,self.subdomainCookies);
    
    // delete the fist subdomain
    NSRange range = [cookieDomain rangeOfString:@"."];
    if (range.location != NSNotFound) {
        NSString* globalDomain = [cookieDomain substringFromIndex:range.location];
        cookieFinder(globalDomain,self.domainGlobalCookies);
    }
    
    return resultCookies;
}


-(void) loadCookies:(id) cookies
{
    for (NSHTTPCookie* cookie in cookies) {
        [self setCookie:cookie];
    }
}


-(void) handleCookiesInRequest:(NSMutableURLRequest*) request
{
    NSURL* url = request.URL;
    NSArray* cookies = [self cookiesForURL:url];
    NSDictionary* headers = [NSHTTPCookie requestHeaderFieldsWithCookies:cookies];
    
    NSUInteger count = [headers count];
    __unsafe_unretained id keys[count], values[count];
    [headers getObjects:values andKeys:keys];
    
    for (NSUInteger i=0;i_subdomainCookies = [self.subdomainCookies mutableCopy];
        copy->_domainGlobalCookies = [self.domainGlobalCookies mutableCopy];
    }
    return copy;
}

@end

// ---

@implementation NSHTTPCookie (BSHTTPCookieStorage)

-(id)initWithCoder:(NSCoder *)aDecoder
{
    NSDictionary* cookieProperties = [aDecoder decodeObjectForKey:@"cookieProperties"];
    if (![cookieProperties isKindOfClass:[NSDictionary class]]) {
        // cookies are always immutable, so there's no point to return anything here if its properties cannot be found.
        return nil;
    }
    self = [self initWithProperties:cookieProperties];
    return self;
}


-(void) encodeWithCoder:(NSCoder *)aCoder
{
    NSDictionary* cookieProperties = self.properties;
    if (cookieProperties) {
        [aCoder encodeObject:cookieProperties forKey:@"cookieProperties"];
    }
}

@end

// ---

The code above is also available as a Github Gist.

That’s all for now. Thanks for reading this ^_^