Gimbal v1 to v2 Upgrade

Gimbal SDK Changes

Here are some key differences in the v1 and v2 SDK APIs:

iOS

  • Version 2 API no longer requires the Gimbal API key to be in the UserContext.plist file. Ensure that your application always calls the "setAPIKey:options:" during application startup
  • Places now not only represent a geofence, but can also now represent one or more beacons. This means a place entry will be generated once you enter the geofence defined on the place, or when the device begins to see beacons associated to that place. To exit the place, the device must no longer be in the defined geofence (if defined), and no longer see any beacons associated to that place
  • Communicates setup in the Gimbal Manager are now automatically presented as a NSLocalNotification. If you would like to handle the presentation or filter the communications that are about to be presented, make sure to implement the "communicationManager:presentLocalNotificationsForCommunications:forVisit:" method.
  • In the Version 1 APIs, the unique identifier used was the string represented by the "receiverId" property in the FYXAppInfo object.In Version 2 API, this is now represented by the "applicationInstanceIdentifier" property in the Gimbal.h interface
  • To register your application for instant push, you don't need to add any properties to the UserContext.plist or any additional calls to register for Gimbal push notifications. You just need to upload your APNS certificate in Gimbal Manager
  • For full documenation on v2 APIs, please refer to the following pages:

Android

  • Version 2 API no longer requires the Gimbal API key to be in the usercontext.properties file. Ensure that your application always calls the "Gimbal.setApiKey(this.getApplication(), "## API KEY ##") during application startup
  • Places now not only represent a geofence, but can also now represent one or more beacons. This means a place entry will be generated once you enter the geofence defined on the place, or when the device begins to see beacons associated to that place. To exit the place, the device must no longer be in the defined geofence (if defined), and no longer see any beacons associated to that place
  • Communicates setup in the Gimbal Manager are now automatically presented as a Notification (collapsed notifications if more than one). Whenever a push is sent to the client, Gimbal will call the CommunicationListener method PresentNotificationForCommunications. Your application can now decide whether or not to raise a notification to the User or allow the Gimbal SDK to raise the notification on your behalf
  • In the Version 1 APIs, the unique identifier used was the string represented by the "receiverId" property. In Version 2 API, this is now represented by the "applicationInstanceIdentifier" property in the Gimbal interface
  • To register your application for instant push, you need to call Gimbal.registerForPush ("## GOOGLE API KEY ##") in your application
  • For full documenation on v2 APIs, please refer to the following pages:

Gimbal Manager Changes

  • All analytics related to application running the Version 2 API's are located in the Gimbal Manager, Analytics->Analytics Beta
  • The iOS and Android v2 Gimbal SDKs ship with a Basic Sample App which has source code to help you understand how to integrate the v2 APIs in your application
  • For an overview of places, login to Gimbal Manager -> go to the Places tab and click on "Places Guide"
  • Manage your Application Configurations
    • v2 allows you to manage Application Configurations in Gimbal Manager. These configurations include the ability to individually turn on/off Geofence monitoring, Beacon monitoring, Communicate Delivery and Managing Ad Ids
    • You can also set a Global Arrival/Departure RSSI for your application in Gimbal Manager
  • Manage your Gimbal Geofences
    • For any of your existing geofences, they will have automatically transitioned to the Places tab with the Place name being same as geofence name
    • To create new geofences, you would create a new place and draw a geofence inside of the place
  • Manage your Gimbal Beacons
    • For your existing beacons, you will need to create Places to contain either 1 beacon per place or a group of n beacons per place
    • You can create new Places from the Places tab in Gimbal Manager
    • v2 also allows you to specify custom Arrival/Departure RSSI values per place. These settings are all managed in the Gimbal Manager and can be changed dynamically without requiring a change to the application client code
    • To set your custom arrival/departure RSSI per place, select a Place in Gimbal Manager and click on "Show Advanced Options"
    • Moving forward, when you activate new beacons, you have an option to specify whether the system should auto-create a place for the beacon
  • Gimbal Communicate
    • If you are using Gimbal communicate to trigger content for geofences, nothing changes in the Gimbal Manager setup between v1 and v2 geofence communicates
    • If you are using Gimbal communicate to trigger content for beacons, you will need to create new communicates which will trigger content on Places (which will consist of one or more beacons)
    • Clone your existing communicate which will create a new one. In the new communicate, go to Triggers and specify the Place at which you want to the content to be delivered. You no longer need the beacon name to be passed as a communicate attribute
    • Until all your users completely transition from v1 to v2 SDK, you should leave both communicates active. Only one of the communicates will be delivered to the user depending on which version of the SDK is running on the user's device