tl;dr

We’re happy to announce the release of PrefixedJSONKit, a version of JSONKit which makes it easier to use JSONKit in libraries without worrying about conflicting with other libraries or the apps which use them.

This library works by prefixing the symbols in JSONKit at build time to avoid conflicts with other users of JSONKit or PrefixedJSONKit.

The Full Story

When we set out to make the ApptentiveConnect library for iOS, we settled on JSON for our client-server communication, and JSONKit as our library for handling that on iOS and OS X. JSONKit is a small, high performance library which was easy to integrate into our library.

One problem on iOS, however, is that all the symbols from the app and the libraries the app uses live in the same namespace. Any conflicts in that namespace cause an error when you try to build the app. So, for example, if an app has a class named “Cheeseburger” and a library the app is using has a class named “Cheeseburger”, the app won’t build. For that reason, developers add prefixes to their code to avoid conflicts. The prefix we use at Apptentive is “AT”, so in our library a class might be named “ATCheeseburger”, which wouldn’t conflict with the app’s use of “Cheeseburger”.

The one exception to our prefixing so far has been our use of JSONKit, which uses the “JSON” and “JK” prefixes. Over the last year, more apps and libraries have started using JSONKit, and we’ve started seeing more conflicts between their use and ours. This is a problem for us because it makes it harder for developers to integrate ApptentiveConnect into their apps, and forces a decision on them over whether to use our version of JSONKit, modify our library to use their JSONKit, or modify both to accommodate another library’s use of JSONKit.

For example, we have a customer who uses RestKit in their app. Trying to link both RestKit and ApptentiveConnect in their app results in a build error:

Our solution, available now, is PrefixedJSONKit. We are maintaining a fork of JSONKit which prefixes the symbols exported by JSONKit. So, in ApptentiveConnect, we’ll be using the “AT” prefix for JSONKit symbols, as well. For example, the JSONDecoder symbol becomes ATJSONDecoder in our library, and will no longer conflict with an app or another library’s use of JSONKit. Another library, such as RestKit, could choose to start using PrefixedJSONKit with the “RK” prefix, making their use of the JSONDecoder symbol become RKJSONDecoder. This makes it much easier for multiple libraries to play nicely with each other.

To use PrefixedJSONKit, first add it to your project in Xcode. Then, define your prefix as a preprocessor macro for JSONKIT_PREFIX, as seen below:

So where before instantiating a JSON decoder object would be:

JSONDecoder *decoder = [JSONDecoder decoder];

it would now be:

ATJSONDecoder *decoder = [ATJSONDecoder decoder];

Category methods are also prefixed, so the -JSONStringWithOptions:error: category method on NSDictionary would become -ATJSONStringWithOptions:error:. Easy!

In our example above, not only does RestKit now build nicely with ApptentiveConnect, another library could use PrefixJSONKit and have it play nicely with both, as well:

PrefixedJSONKit is available now on GitHub. We hope you find it as useful as we have!