Best Practices for Testing Geofences & Beacons

The purpose of this document is to outline best practices when testing Gimbal’s beacons and geofences. It is important to note that typical testing environments differ from real-world user experiences. Below are important steps to consider for optimal testing results in such testing environments.  These include instructions and best practices for using either Gimbal’s ‘Hello Gimbal’ app or your own app integrated with the Gimbal SDK.

USING ‘HELLO GIMBAL’ APPLICATION

DOWNLOAD ‘HELLO GIMBAL’ FOR iOS OR ANDROID FROM THE APP STORE

Hello Gimbal automatically provides an application customers can use for testing, while also providing an opportunity to activate a beacon, create a ‘place’ associated to the beacon and/or geofence and create a ‘communicate’. Gimbal provides the 'Hello Gimbal’ application to make it easier to test, since you can see the arrive/depart events on the screen.

RUNNING ‘HELLO GIMBAL’ AND TESTING WITH BEACONS

Ensure your device has Bluetooth turned on and your beacon is turned off. It is important to make sure the beacon is off until activated. There are cases where the application registers itself before the beacon is activated, which can result in a delay in the beacon resolve on the device. Simply launch the application thereafter and follow directions on screen (and below). Note: once active, your beacon cannot be activated in another account without first deactivating the beacon in the original account.

1.Login to Gimbal Manager Account in a web browser.

2.Using Hello Gimbal, scan server API Key by clicking on ‘QR Code’ on the 'Home' tab.

3.To create a place using a beacon, you must first activate a beacon by scanning the code inside the beacon. Simply hover over the beacon code when prompted within Hello Gimbal.

4.Select 'enable' in your mobile application to opt-in to Gimbal and accept all OS permissions for location and notification.

5.Once the above is complete, within Gimbal Manager’s ‘place’ and ‘beacon management’ tab, you will see a place named ‘Hello Gimbal Place’ and beacon named ‘Hello Gimbal Beacon.’


6.Turn your beacon back on.

7.After a few seconds (~15), you should see a place event arrival "Hello Gimbal Place" with additional information based on the device's proximity to the beacon, for example: 'Immediate' and also the temperature sensed by the beacon.

• To see iOS notification (banner, notification tray) pop up, please make sure the app is in the background state (press the home button on your phone to background the application)

8.One important thing to note about testing, you must depart a ‘place’ before you can arrive at it again. For example, if the triggering event for the ‘communicate’ is a ‘place’ arrival you must actually depart the ‘place’ before you will be able to arrive again and therefore trigger the Communicate.

Tip: If you are currently in a ‘place’ you must first exit prior to an arrival event to be triggered. For a beacon you can depart the beacon either by turning off the beacon and waiting for a few minutes or walking away from range of the beacon (~50 meters).

RUNNING ‘HELLO GIMBAL’ AND TESTING WITH GEOFENCES

Login to Gimbal Manager Account. Simply launch the Application and follow directions on screen. For testing with geofences, you will need to use the “Reset Places” feature of Hello Gimbal, which will mimic downloading a fresh instance of the application. This is to ensure you are departing a place before re-entering.

1.Login to Gimbal Manager Account in a web browser.

2.To create a ‘place’ using a geofence you must: 

• Navigate to ‘Place’ tab in Gimbal Manager and select ‘+ New.’
• Name place ‘Hello Gimbal Place’ and select ‘define a geofence – new geofence.’
• Geofences can be radial or polygonal and customized to your needs.
• For radial geofences, select “radial” from the “Geofence Type” drop-down menu.
• Select your geofence radius (meters) - can be as small as 50 meters or as large as 30,000 meters.
• Search for your location by typing in an address.
• For Polygonal Geofences, select “polygonal” from the “Geofence Type” drop-down menu.
• Zoom into and drag the Google Map to desired location.
• Click for a starting point of your polygon, and drag mouse alongside borders. Click again to release a point, and continue to drag for next border. Finish your polygon by connecting with the first dot.

At the bottom right hand corner, select ‘Create Place.’

3.Launch the Hello Gimbal application on your mobile device. If you have already gone through the initial setup process, go to ‘More’ tab in the application and select ‘Refresh Places’. Or if you are launching the ‘Hello Gimbal’ application for the first time, scan server API Key by clicking on ‘QR Code’ on the 'Home' tab and skip the steps to create a Place in the application.

4.You will then see your newly created ‘place’ in the ‘places’ home screen.

Tip: You should avoid drawing polygon geofences smaller than 100m wide

5.To create a Communicate to be triggered by 'Hello Gimbal Place' arrival:

• Navigate to the ‘communicate’ tab in Gimbal Manager and select ‘new communicate’.
• Name the communicate ‘Hello Gimbal’.
• Select your start date to include today.
• Select your event to trigger upon user arrival.
• Select ‘Hello Gimbal’ as your place name.
• For Limits and Frequencies, make sure to select a ‘during these times’ timeframe that falls within the time you are testing. We would suggest setting the dwell time to zero seconds and selecting ‘no’ to frequency limiting.
• Fill in the required fields within the ‘notification’ section. Regardless, of which platform you are using for testing, you must complete the fields for both iOS and Android. Note: this is the text you will see when receiving your test push notification.

6.Select 'enable' in your mobile application to opt-in to Gimbal and accept all OS permissions for location and notification.

7.One important thing to note about testing, you must depart a ‘place’ before you can arrive at it again. For example, if the triggering event for the ‘communicate’ is a ‘place’ arrival you must actually depart the ‘place’ before you will be able to arrive again and therefore trigger the ‘communicate.’

• In order to force an exit, you can do a “refresh Places” in the More tab of Gimbal Manager. Otherwise, you will need to mimic real-world user experience by getting in your car and driving away from the geofenced area, in the same way that your typical app-user would depart. This is not practical in most cases, however.

Tip: An important note when testing geofences – Gimbal’s geofencing platform is built for real-world use-cases, NOT for testing. Gimbal’s geofences are designed with a balance of accuracy, responsiveness, and a small device-battery footprint in mind.  For testing, Gimbal strongly recommends using beacons for repeatable tests.  Since beacons and geofences are both abstracted by our ‘places’ feature, geofenced areas can be mocked by using a beacon.

USING YOUR APPLICATION

HELPFUL HINTS FOR TESTING YOUR APPLICATION WITH GIMBAL

Note: Ensure that the application key belongs to the same bundle identifier as the application in which it is being used. We would suggest testing in your production application on a test device to more easily manage this challenge.

1.Once a test device, QA application and or device has been added to your Gimbal Manager account, you must then activate a Beacon in the organization or create a ‘place’ associated with a Geofence. See above for directions on how to do this in Gimbal Manager.

2.Create Communication to trigger upon Place Arrival.

3.When your Gimbal enabled application enters into proximity of a ‘place,’ the Gimbal SDK will then trigger a Place Arrival Event.

• didBeginVisit’ in iOS
• ‘onVisitStart’ in Android

4.Gimbal SDK will then call on Gimbal Server for any communication(s) associated for this Place.

5.Gimbal SDK will receive Communication and can present it to the application, as appropriate.

6.To receive arrival Communication again, you must exit/depart the ‘place’ first and then re-enter.

• Exit: Gimbal SDK triggers a Place End Event
  • didEndVisit’ in iOS
  • ‘onVisitEnd’ in Android

• Arrive: Gimbal SDK triggers a Place Arrival Event
  • ‘didBeginVisit’ in iOS
  • ‘onVisitStart’ in Android

7.You will also be able to see your arrival event in Gimbal Manager’s Analytics’ Place dashboard. (It may take up to 6 hours after arrival for the place event to be shown in the dashboards)

Note: Place Arrival event will not happen if you are already in the ‘place.’ When testing with beacons, switch the Beacon off to create a departure event. By default, this will take 30 seconds if your application is in the foreground. Turn your beacon back on again, wait ~15 seconds. When testing with a geofence, you must uninstall and reinstall the application to trigger a new arrival event if physically unable to move outside of the geofence boundary.