Gimbal’s location platform is designed to work in a variety of application development environments. Gimbal provides native support for Android and iOS applications, however it is possible to incorporate third-party platforms such as Xamarin, enabling seamless integration of your mobile application.
For this blog we are fortunate to be able to share the expertise of Kurt Herrmann, a key Web and .Net Developer for New Belgium Brewing, based on his experience with the development of their application ‘Beer Mode.’ With Kurt’s help we have created a high-level outline of what is required to integrate the Gimbal SDK using Xamarin while also addressing the challenges, caveats and OS-level differences he came across during this integration process.
Beer Mode is New Belgium’s mobile app that provides all things New Belgium Beer to their loyal fans and new discoverers. Beer Mode includes news, blog posts, and event information, including New Belgium’s marquee ‘Tour de Fat’ and ‘Clips’ events. Additionally, it delivers specific product details and tasting notes for all of their beers including purchase locations (both on- and off-premise). Finally, the app rewards folks who sign up in-app with points and includes automatic entry into New Belgium promotions and giveaways. Location has always been key for New Belgium to help people find their beer in real world situations and the Beer Mode app enables them to significantly ‘up their mobile game’ with real-time location-based messaging for events, brewery tours, retail giveaways or coupons – the sky is the limit.
Kurt has been kind enough to share with us his experience integrating Gimbal’s location platform into the Beer Mode app which is built on Xamarin.
If you are unfamiliar with Xamarin, start by reviewing the documentation provided here:
*Click here for a hands-on walkthrough of creating a Xamarin.iOS binding for an existing Objective-C library.
*Click here for instructions on creating a Xamarin.Android Java Bindings Library from an Android .JAR file.
Both documents provide a detailed walk-through of the process for each platform. In brief, each OS requires a platform-specific “binding” project in order to create a wrapper which allows Xamarin .NET code to call into the native SDK/library.
Android-Specific Implementation Guidelines
For Android, these binding projects can be built immediately once the source JARs are inserted into the correct directory (JARs) and then setting their BuildAction to EmbeddedJar. However this doesn’t always mean that it will build and compile properly. Fortunately, Xamarin’s Android binding projects have been structured to give developers the ability to override many properties of source SDK classes in order to allow SDKs to be wrapped according to .NET rules. Developers can choose to use the XML transform files in the Transforms folder to alter the output, or they can add custom code into the Additions folder (or both, in New Belgium’s case).
New Belgium’s development team used both of the methodologies mentioned above to address these issues and successfully compile the Xamarin application with the Gimbal SDK.
Gimbal’s SDK is optimized for native OS development so there are a few important notes in reference to build errors or warnings that may appear at compile-time. These errors and warnings are addressed in the comments within the source code in New Belgium’s Github repository. The majority of these concern class visibility and method return types, which will be specific to each implementation and should be straightforward to work through.
New Belgium also opted to keep the Java naming convention for the generated namespace, i.e., Com.Gimbal.Android.X. Metadata.xml can be used to completely change namespaces, but this is optional.
Click here to link to the Android app.
iOS-Specific Implementation Guidelines
Binding iOS SDKs is more complicated because iOS binding doesn’t automatically traverse the input hierarchy, nor does it output a comparable class library. Developers have to define the API or class structure for the SDK beforehand and anything not defined at this stage will not be generated. A common mistake at this point is for a developer to forget to define classes, which will lead to runtime errors caused by a library that is not referenced. However, Xamarin has a tool called ‘Objective Sharpie’ which can automatically generate API wrappers.
New Belgium successfully used Objective Sharpie to build a wrapper for the two Gimbal libraries, libGimbal.a and libGimbalExperience.a, which were placed in the standard class file ApiDefinition.cs. The only manual alteration required was the wrapping of some Gimbal enumerations based on ‘longs’ instead of ‘nints’, which are in the standard StructsAndEnums.cs file.
Once the binding projects were completed, New Belgium was able to utilize them in their target projects. Just as if they were using native Android or iOS apps, New Belgium had to configure their target apps with appropriate changes for AndroidManifest.xml or Info.plist to get the correct permissions for background location monitoring and Bluetooth. The above example applications show the most basic Gimbal use case – logging events when known locations or beacons are sensed. However, this guide should help with the basic implementation details and can be used for even more complex integrations with Gimbal’s platform.
Click here to link to the iOS app.
*Certain links have been updated since original post to reflect updated Xamarin documentation (as of June 1st, 2019).
Click here for a link to both the Android & iOS Bindings and sample projects.
If you have any questions around implementing the Gimbal SDK into Xamarin or other third-party applications, please email firstname.lastname@example.org.