Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

The purpose of this page is to highlight the changes to the general setup that need to take place for the Gimbal enablement with the release of Gimbal 2.0 SDK. 

Definitions

New for SDK 2.0:

Places
Gimbal SDK 2.0 introduces the concept of PLACES. A Place can be represented by a single geofence and/or a series of beacons. There can only be one geofence per place. Thus, when you create a Place in Gimbal Manager you can draw a geofence and/or choose a set of beacons to define the Place. A Place represents both Geofence and Proximity.

For example, a Place can be represented by a geofence (circular or polygonal), a series of beacons, or a combination of a geofence and beacon[s].

 

In your mobile application:

Place Entry: Generated when a user enters the Geofence.
Place Exit: Generated when a user exits the Geofence.

 

NOTE: The behavior is the same as Geofences in Version 1.x of Gimbal.

 

In your mobile application:

Place Entry: Generated when a user comes into proximity of any of the beacons in the Place.
Place Exit: Generated when a user leaves proximity of all of the beacons in the Place.

NOTE: If the Place contains only one beacon the behavior is somewhat similar to Visits in Proximity Version 1.x of Gimbal.

 

In your mobile application:

Place Entry: Generated when a user enters the geofence or proximity of any of the beacons in the Place.
Place Exit: Generated when a user exits the geofence and proximity of all of the beacons in the Place.

Previous Definitions:

Gimbal Beacon
Refers to either the physical devices (small white box or smaller blue tag), or the signal that they emit. Beacons do not connect to the internet, they just send out a unique signal used to identify the beacon.
New for SDK 2.0: MobileSmith applications can now send Gimbal Beacon notifications to Android devices.

Proximity
A type of interaction between the phones and Gimbal Beacons. This primarily deals with sightings, which are broken up into arrive, dwell, and depart events.

Geofence
A region of space (typically GPS location with a radius, but polygonal shapes are allowed too) which are set up on the Gimbal server. These are not tied to any physical beacons.

Communication
A more general (and repeatable) version of an instant communication. By design these are not specifically tied to a particular beacon, but they can be due to MobileSmith extensions. This notification will be sent to the app under certain circumstances. When created, you specify the window of time that the communication will be active.

RSSI range
For proximity, the signal strength of the beacon that would constitute an “arrive” visit and a “depart” visit. Values are always negative and values closer to zero are stronger (e.g., -20 is stronger than -30). For example, an arrive strength could be set to -40 (very close) and a depart strength could be set to -70 (fairly far away). Default value is -60 for both. The Gimbal Manager App could be used to measure beacon strength in real-time to make sure that good values for these items are set. 

Sighting Frequency
The interval at which the Gimbal Server will send sighting information to the ‘Sighting Callback URL’.

Exit Interval
The elapsed time that determines when a visit is closed.  If during this elapsed time a sighting is not sent to the Gimbal Server, then the visit is over and a depart event is sent to the Sighting Callback URL.

Sighting Callback URL
When the Gimbal Server receives sighting information, the server will call this URL and send sighting information to the specified location. 

Deep Link
In your Gimbal Manager’s Communications section, in Notification, you can set up your notifications to send your app users directly to a specific page in the app after receiving a Gimbal message. The Deep Link found in the MobileSmith Platform can be plugged into the notification created in the Gimbal Manager to accomplish this.

 

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 

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

 

Assets

The following section will discuss the various assets that need to be created in order to enable Gimbal to work with the MobileSmith platform. Assets created in the Gimbal Manager as well as the iOS Dev Center will be needed to tie everything together.

iOS Dev Center

When creating an app to use with the Gimbal beacons, you will need to have a Push

Certificate, Push Certificate Password and the iOS Bundle ID for the app.  These assets will be used in both the Gimbal Manager and the MobileSmith platform.  Directions on how to obtain all assets needed from the iOS Dev Center are documented in the App Submission Enterprise document located at the following link: Download App Submission Enterprise Document

Gimbal Manager

 

There are several items that you will generate in the Gimbal Manager that will need to be entered into the MobileSmith platform.  Navigate to the Gimbal Manager Login page:

https://manager.gimbal.com/login/users/sign_in

and sign in using your credentials.  If you have not created an account yet, click the ‘Register’ button on this page and follow the process to sign up.

Applications

1. Once logged in, by default you will be placed onto the Applications page.  Click the ‘New Application’ button in the top right corner of the page.

 

2. Select ‘iOS’ as your Platform and enter the iOS Bundle ID you created for your app. Create a separate application for Android following the same steps.

3. New for the SDK 2.0, are the required fields Name and Category; please enter these as appropriate for your application.

4. Click Generate so the system will generate the following information: 

  • Gimbal API Key
  • Application ID
  • Secret

 

5. New for SDK 2.0: the Configuration section, which gives you customization options for your application. Please see the Proximity Enabled Applications portion of the Gimbal documentation for more information. 

 

If you check the ‘Customize Place Detection with Beacons’ option, new options appear for the customization of how the SDK detects Places with Beacons. This section utilizes the RSSI information explained above.

 

Step-by-step guide

 

  • No labels