What I learned writing my first SDK
This summer, I came across an opportunity to write my first SDK, so I leapt at it. As developers, there is something very appealing about writing software for use by other developers. It might be because of the sense of solidarity that you’ve made life easier for sisters/brothers in code, or the thrill of a backseat driver finally getting a chance at the wheel. That is until the realisation that the demographic you’re serving will also be the best equipped to critique your output, this is especially true when producing an open source repository.
So below are some lessons (some key, some trivial) that I learned while coding judo’s Xamarin SDK.
Keep it to yourself
Any class that doesn’t directly serve the use case of your SDK, make it private. Judo Payments is a mobile payment company and the SDK chief goal is to offer merchants/developers a quick, no-fuss option for integrating secure in-app payments into mobile applications.
We are not a credit card number validation company, our main offering is not tools to check if a client’s device has been rooted, we are also not a button bevel construction company (As much as I selfishly pray for the pivot). While all these things have to be present in the SDK to serve its purpose and provide a great experience to our developers, I do not have to present them. By presenting every helper or method you used to construct the SDK, you are muddying the waters of how that SDK is to be used, and you are responsible for keeping it clean and fit for public use.
It’s a big diverse world of applications out there, and by virtue of being a component in larger systems, a SDK has to work in all of these different environments. I work on judo’s Xamarin SDK, so calls can come from any point in the iOS or Android life cycle. That’s a lot of different viewControllers, a lot of different form factors and, due to the fact that I am constantly trying to keep on top of two ecosystems, a lot of potential change.
One way I found helpful in catching as many use cases as possible is while doing final integration testing for a release candidate (where I would add to a test app and see if I could make payments), I would pull a few different open source or template applications off the internet, and wire up the SDK to see if it works. It shouldn’t really be a chore if I have achieved the main goal of making an easy to integrate SDK, and I end up catching a lot of edge cases I wouldn’t have thought of otherwise.
You live light, so others can live easy
It may sound hypocritical but try to use as few SDK’s and value added frameworks within your SDK as possible. Everything you use gets bundled into the finished package, which adds bulk to your end users application, and as this is bundled into the binary, they won’t get to make use of it themselves. So for common components, they may be adding it twice without even realising they are doing so.
This makes life especially frustrating for a Xamarin developer. You have this great opportunity to save space by maximising the use of cross-platform code, but also don’t want to have a heavy cross-platform, code-sharing framework like mvvmCross within your SDK. Since it’s designed to provide everything a developer would need for full blooded cross-platform app development. SDK’s need to be leaner, you are going to have to implement just the parts you require.
What’s in a name
For every public class you make, give it a specific name. Your SDK is going out into a big, bad, varied world and the developer using the SDK has right of way in their own app. The less chance of your class names clashing with theirs, the better. I’ve seen SDK’s provide classes like ‘RESTClient’ or ‘Configuration’. Although you can get around this by fully qualifying the class name like ‘GenericCorp.ThisIsAChore.Configuration’, who want’s to do that? No one.
Scapegoat Deployment Kit
If anything fails in a developer’s app, and there is even a whiff that your SDK might be involved, you are going to hear about it.
One of the advantages of running an open-source repository is you have an open dialogue with developers of all levels, and you get a lot of great feedback. However, the flip side of that is you could get a few red herrings which prompt you to investigate bugs, only to find that the developer have either invalidated his/her view stack, missed a permission, or one of those weird and wonderful quirks of mobile development has arisen where the developer just needed to delete a cache.
Full and verbose error handling really makes the difference when helping folks debug, so do make it a priority. Also, sometimes it IS your bug, so be nice.
Sample app > Documentation
Documentation is great, but a trove of coding examples is king. Documentation should provide the developer with a guide on how to use the SDK, and a deeper glossary for any specific questions they have on the SDK. But a robust and fully-featured sample app making use of the SDK is the quickest way for a developer to see how and in what context the SDK is best used. I also recommend adding a few hints and tricks of how applications within this space work.
Xamarin is great because all SDK components submitted to the store must also contain a sample application demo-ing the SDK. You’re probably going to write one anyway over the course of your SDK development, so you might as well make it a learning tool.
I will be doing a free webinar with Xamarin’s very own Mike James (@MikeCodesDotNet on Twitter) on 28th January 2016, 17:00 GMT. Click on the image below if you’re interested to sign up for it. Hope to see you there!
About Judopay · Judopay simplifies in-app payments, enable frictionless checkouts and intelligently prevents fraud for leading companies globally. Our payments and mobile experts help guide businesses and their development partners to create best in class apps to make paying faster, easier and more secure. Founded by serial financial technology entrepreneurs in 2012, Judopay is backed by leading venture investors and supported by banking and card scheme partners to offer in-app payments that are simple, frictionless and protected.