Gravy SDK v2.0 Overview & Developer Guide

The Gravy AdmitOne​​ SDK 2.0 is a major upgrade in both the SDK interface and the supporting server infrastructure. The change is a culmination of both our experience and developer feedback on previous SDK versions. In addition, this new version has increased efficiency, compactness and location accuracy.

Core Features

This new SDK has core features developers are already familiar with as well as new features being leveraged by the AdmitOne​TM​ 2.0 platform. The SDK product capabilities are:

  • Foreground & Background Modes Support​: The SDK supports running in both foreground and background modes on the device. Developers can seamlessly meet the business rules of their Apps for Foreground Only or Foreground+Background modes within their Apps.
  • Batch location processing​: Location transactions are recorded and sent to Gravy in batches at calculated periods of time. An example of a batch would be all transactions over a 24 hour period. ​Batch location processing reduces the use of the radio to send location data to the servers resulting in reduced battery drain and data usage.
  • COPPA Support​: The SDK supports runtime enabling and disabling of location services. This feature supports user and parental disabling of location collection.
  • Low Battery Consumption:​ The SDK boasts on average 1% battery usage per day to 1% per week when optimally configured on both targeted platforms.

Implementation

The SDK still requires implementations with authentication tokens and the proper application configuration. Developers are admonished to adhere to these requirements and reach out to the SDK Dev team if they have any queries.

  • Configuration properties file [GravyConfig]: This file is added to the application’s assets/resource folder and provides launch options to the SDK.
  • Authentication tokens exist for both Sandbox and Production. Sandbox should be used for development testing and Production when publishing your application to the App Store. The SDK requires the following token:
    • API Key – sample [a0a19040-e3a3- 4469-bac1- 44fc28793403]
  • Location Services enabled: Each platform has requirements for location services. Your application settings and permissions must be configured to allow access to location services. Follow recommended platform guidelines for requesting access to Location Services with key attention to ensure location services are properly accessible in Background mode, as well as Foreground mode, life cycle states of your Application.

Understanding The Application Life Cycle

Application life cycles have minor differences across both platforms. However, the SDK functions with those differences and have commonality in core feature implementations. Your application goes through a launch that involves preparation, background and foreground and then into the background and eventually dies. The SDK settings and runtime configuration are designed to enable functionality during those states and as such you application should implement the recommended requirements for background and foreground location services.

Proper implementation allows the SDK to launch and remain active after state changes such as your application going into the background or being killed. This recovery capability also extends to a device restart.

The SDK implementation is critical to its required capabilities. Developers should follow the recommended practices as deviations may result in interrupted SDK operations. The SDK is designed to run in the background and is a core component of your application background mode/state. This is necessary as the SDK is designed to optimally acquire location transactions while the application is in the background. To that end, your App should register with the OS for the relevant location services including background processing as need. Furthermore, the SDK should be initialized in a component that will remain alive throughout the lifecycle of your application. For iOS this is your ​AppDelegate​ instance and the SDK should be initialized in the ​application:didFinishLaunchingWithOptions: ​method. For Android this is your Application​ instance and the SDK should be initialized in your ​Application.onCreate(​)​.

Selecting The Location Update Interval

The location update interval affects the accuracy of results as well as the overall battery drain. Use a location update interval that is too long, and some attendances will be missed, because the device may move into and out of the geofence associated with an event or place before a location is collected. Collecting more than one location within or near the geofence polygon of an event or place generally increases the probability that the attendance is accurate. However, the smaller the interval between location updates the greater the battery drain.

Gravy’s general guidance is to start with a location update interval of 7 or 8 minutes. Depending on the platform and other apps on the device that request location, the device may be served a location more frequently than it requests (e.g. every 5 minutes). App developers are encouraged to deploy the SDK in their app and monitor battery utilization.

Understanding Battery Utilization As Reported By The Platform

Android

Battery usage for Android is registered as less than 1% per 24 hours. This is not always visible as the OS often reports the battery usage starting at 2%. Developers should verify the SDK implementation is running in the background and their application is receiving location updates. The SDK utilize the FusedLocationAPI Google API Client implementation to register for location updates. This means location updates are routed through the Google Play Services application running on the device. The power consumption of the Google Play Services application may also be an indicator of the SDK location updates impact on battery usage.

iOS

The overall battery usage reported in the last 24 hours will be around 6% – 7% out of the full battery life. Nevertheless this number will vary depending on how actively the device is used (on screen time) as well as how individual applications consume power and the battery percentage remaining.

When monitoring battery usage, a usage percentage is a percentage of the battery that is being used and is represented as a total usage for the entire device ecosystem. For example, if your iPhone has 80% battery remaining but it lists an application has used 50%, that means said application has used 50% of the 20% used and this translates to that application using 10% (not 50%) of your full battery life.

Getting Started

Android 
  1. ​First step is to familiarize yourself with the SDK by running the Sample App provided. Remember to insert your authentication token (API Key). Run the Application and observe the UI for registration and location transmission updates. Pay attention to the following:
    1. SDK gravyconfig.properties file location in the project assets folder.
    2. SDK launch code in MainApplication.onCreate()
    3. SDK communication to the Sample App. This is important to observe how the SDK will communicate location updates and real time content to your application using the GravyStatusReceiver implementation. Your app should follow this model as well to verify SDK implementation is successful and operates as expected.
  2. Add the SDK to your Application.
    1. Add your GravyConfig properties file to your application source assets folder. REMEMBER: ​Set your ​Environment​ to ​SANDBOX​ for testing and ​PRODUCTION​ for App publishing.
    2. ​Implement GravyStatusReceiver for Android.
    3. Update your Manifest with the required permissions.
      1. ​Permissions required by the SDK.
      2. ​SDK service permissions.
    4. Launch the SDK with the authentication tokens.
      1. GravySDK.config()
    5. Update your application source code as follows:
      1. {-​ gravyConfig.properties -}​: This is the configuration file that the SDK uses to launch. Configure the file to your Apps desired settings and place the file in your project’s Assets folder.
      2. {-​ Manifest -}​: Update your manifest with the following:
        • Location Permissions
        • SDK Service Permissions
        • GravyLocationReceiver
        • GravyService
        • GravyBootReceiver
        • GravyStatusReceiver implementing class (optional)
      3. {- Initialize GravySDK -}​: In your Application instance onCreate() method launch the SDK using ​GravySDK.config(context, APIKey)​.
  3. Verify the SDK functionality through the broadcasts in your own implementation of the GravyStatusReceiver.
iOS
  1. The first step to familiarize yourself with the SDK is to run the Sample App provided. Remember to insert your authentication token (API Key). Run the Application and observe the UI for location transmission updates. Pay attention to the following:
    1. SDK GravyConfig.plist file location in the project source folder.
    2. SDK launch code in the AppDelegate
    3. SDK communication to the Sample App. This is important to observe how the SDK will communicate location updates.
  2. Add the SDK to your Application.
    1. ​Add your GravyConfig.plist file to your application project folder. ​REMEMBER: ​Set your ​Environment​ to ​SANDBOX​ for testing and ​PRODUCTION​ for App publishing.
    2. Implement the delegate methods.
    3. Launch the SDK with the authentication tokens.
      1. GravySDK.config().
      2. {-​ gravyConfig.plist -} Add your GravyConfig.plist file into your application project folder.
      3. {- Init GravySDK -} [[[GravySDK sharedInstance] configWithApiKey:ApiKey delegate:Delegate] launch];
  3. Verify SDK is running:
    To verify the SDK is running properly make sure you have done the following.
  1. Included the ​GravyConfig​ property list file in your project with the correct settings.
  2. Turned ON “​Background Modes​” in the Capabilities tab of the target settings, and selected “​Location updates​”.
  3. Included the key ​NSLocationAlwaysUsageDescription​ to the Info.plist with its respective description; this is how or why location services are being used.
    • Note for iOS 11: All three fields, ​NSLocationAlwaysUsageDescription, NSLocationWhenInUseUsageDescription ​and NSLocationAlwaysAndWhenInUseUsageDescription, ​must be included in the info.plist.
  4. Implemented the delegate methods. Location updates will be delivered to the ​deviceLocationChanged​: delegate method.

Detail code implementations for Developers are provided in platform specific guides.

Verifying Your SDK Implementation

The SDK recommended best practices are comprised of the best conditions under which the SDK operates. These best practices are a culmination of our internal tests across platform and OS versions, as well as input from developers like you. Please adhere to these practices in your implementation. If one or more of these recommendations do not fit your needs, please reach out to the Dev Team and we can work together and advise on what is the best option.

Developers should leverage the platform capabilities to verify the SDK is operating optimal in their application. The provided sample App contains the TestMode feature that allows the Sample App to sample registration and location data on the server for that install instance of the SDK. Developers may use this feature to verify SDK registration and location information; this feature also as API endpoints explained below. During testing with the sample App, the tester would run the application that registers and collects location transactions in the background or foreground. Selecting to verify user information from the Sample App will make a call to the Sampling endpoints and retrieve registration and location information from the
server.

It is also recommended that developers test their own applications with the SDK prior to publishing their application to the App Stores. The Developer should validate the SDK in their Applications using the following methods:

  1. SDK Registration callback: this verifies the SDK has registered with the Gravy servers.
  2. Location Updates (in foreground and background): This is also communicated to your application though delegate callbacks and notifications. The developer should verify location updates are entering the application from the SDK when the App is in background and foreground modes and the device is being used (moved) as it would be with a typical user (not stationary) in order to get location updates from the OS.

Test your App extensively in the SDK Production Environment prior to publishing. It is strongly recommended a minimum of two weeks be allotted to acquire adequate location transactions test data from your application. In addition, as part of this verification, developers should obtain test data validation from the Gravy data team prior to publishing the App to the respective App Store.

Technical Specifications

The iOS SDK is now packaged as a Framework and the Android SDK is in Archive (aar) format.

Frequently asked questions about the SDK are its compressed size, published (expanded) size as well as details on typical battery usage.

Android
  • Library aar sIze: 260 KB
  • Library expanded and published: 1.86MB
  • Minimum SDK: API 14.
  • Battery Usage with Default Settings: 1% per 7 days
iOS
  • Framework compressed sIze: 7.1MB
  • Framework expanded and published: 0.3MB – 0.7MB
  • Minimum OS Version: iOS 8
  • Battery Usage with Default Settings: 1% per 7 days

FAQs

Q: What is the SDK impact on battery utilization?
A: Both platform SDKs may have increased battery usage if the SDK is configured outside the boundaries of the default settings. It is for this reason we recommend abiding by our guidelines as the SDK is configured by default for optimal performance.

  • Android SDK has a 1% per week impact on battery utilization.
  • iOS SDK has a 1% per week for optimal batch location processing.

Q: What is the impact of the iOS SDK on App size?

A: The iOS SDK is provided compressed and expanded during build and publish.

  • iOS SDK Framework Compressed: 7.1MB
  • iOS SDK Expanded (published): 0.3-0.7MB

Q: What is the impact of the Android SDK on App Size?

A: The Android SDK is provided compressed and expanded during build and publish.

  • SDK Compressed: 260KB
  • SDK Expanded (published): 1.86MB