com.radiusnetworks.proximity

Class ProximityKitManager

java.lang.Object

com.radiusnetworks.proximity.ProximityKitManager

public class ProximityKitManager
extends Object

This is the main class for interacting with the Proximity Kit SDK.

A ProximityKitManager instance is the primary interface for working with Proximity Kit cloud data. This provides access to the Kit object and serves as the central registration point for notifications of related beacon/geofence events.

For details about the available notifications see the ProximityKitMonitorNotifier, ProximityKitRangeNotifier, ProximityKitGeofenceNotifier, and ProximityKitSyncNotifier.

To initialize a Proximity Kit manager you will need the SDK settings for your kit. These can be found under the kit settings on the Proximity Kit server.

The easiest way to create a KitConfig is to build a Map or Properties of the settings (see KitConfig for the full list of available settings):

  Map<String, String> settings = new HashMap<>();
 // or Properties settings = new Properties();
 settings.put(
         KitConfig.CONFIG_API_TOKEN,
         "PROXIMITY KIT API TOKEN HERE"
 );
 settings.put(
         KitConfig.CONFIG_API_URL,
         "https://proximitykit.radiusnetworks.com/api/kits/YOUR_KIT_ID"
 );
 KitConfig kitConfig = new KitConfig(settings);
 

You can then use the following method to instantiate a singleton ProximityKitManager:

 public class SampleApp extends Application implements ProximityKitMonitorNotifier {
     // Storage for an instance of the manager
     private static volatile ProximityKitManager pkManager = null;

     // Object to use as a thread-safe lock
     private static final Object SHARED_LOCK = new Object();

      @Override
     public void onCreate() {
         super.onCreate();

         // ... kit configuration created per above

         // Standard double check singleton initialization pattern
         if (null == pkManager) {
             synchronized (SHARED_LOCK) {
                 if (null == pkManager) {
                     pkManager = ProximityKitManager.getInstance(
                             getApplicationContext(),
                             kitConfig
                     );
                 }
             }
         }
         pkManager.setProximityKitMonitorNotifier(this);
         pkManager.start();
     }
 }

To receive callbacks when interesting things happen implement one of more of the notifier interfaces: ProximityKitMonitorNotifier, ProximityKitRangeNotifier, ProximityKitGeofenceNotifier, and ProximityKitSyncNotifier. And provide that instance to the manager via on of the notifier setters.

WARNING: the current design internally implements the ProximityKitManager as a singleton. Do NOT assume that this will always be the case. As per the example above we strongly recommend that you keep track of your own singleton instance. This way when the behavior does change your app will not be affected. Be aware that calling ProximityKitManager.getInstance(Context, KitConfig) more than once will replace the existing singleton instance. This may result in unexpected / undefined behavior for your app.

Since:

0.1.0

See Also:

KitConfig, Proximity Kit Overview

Min Android API:

4 - The ability to check the Android SDK level as an integer android.os.Build.VERSION.SDK_INT was added in this API level

Field Summary

Fields

Modifier and Type	Field and Description
protected Context	context Deprecated. Not for public use - no replacement. As of 0.13.0 this field could possibly be retained only as a private implementation detail.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ProximityKitManager(Context context) Deprecated. Not for public use. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)

Method Summary

Modifier and Type	Method and Description
void	clearPartnerIdentifier() Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)
static void	debugOn() Turns debugging on for geofences and beacons.
void	disableGeofences() Explicitly disable geofence support.
void	enableGeofences() Explicitly enable geofence support.
com.radiusnetworks.proximity.proximitykit.BeaconAdapter	getBeaconAdapter() Deprecated. Not for public use. As of 0.13.0, no replacement.
BeaconManager	getBeaconManager() Deprecated. Not for public use. As of 0.13.0, no replacement.
static ProximityKitManager	getInstance(Context context, KitConfig config) Creates an instance of ProximityKitManager.
static ProximityKitManager	getInstanceForApplication(Context context) Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)
Kit	getKit() Current instance of the Kit setup on the Proximity Kit cloud servers.
int	getMaxRegionsBeforeRollup() Deprecated. As of release 0.5.0. This setting no longer does anything, as regions for monitoring and ranging may now be explicitly configured on the ProximityKit server. If you are using this roll up feature, please switch to configuring your ranging and monitoring regions explicitly on the server. Gets the maximum number of regions that may be individually configured in ProximityKit before the regions will start being automatically combined. This method has been deprecated and the setting no longer has any effect.
ProximityKitGeofenceNotifier	getProximityKitGeofenceNotifier() Getter for the currently configured Geofence notification callback handler.
ProximityKitMonitorNotifier	getProximityKitMonitorNotifier()
ProximityKitRangeNotifier	getProximityKitRangeNotifier()
ProximityKitSyncNotifier	getProximityKitSyncNotifier()
void	restart() Deprecated. As of 0.10.0, no replacement. To simply restart the manager use ProximityKitManager.stop() and ProximityKitManager.start(). To use a new configuration create a new manager using ProximityKitManager.getInstance(Context, KitConfig).
void	setKit(Kit kit) Deprecated. As of 0.13.0, no replacement.
void	setMaxRegionsBeforeRollup(int regionCount) Deprecated. As of release 0.5.0. This setting no longer does anything, as regions for monitoring and ranging may now be explicitly configured on the ProximityKit server. If you are using this roll up feature, please switch to configuring your ranging and monitoring regions explicitly on the server. Sets the maximum number of regions that may be individually configured in ProximityKit before the regions will start being automatically combined. By default, each beacon or region in the ProximityKit server results in one monitoring and ranging region. In cases of large numbers of individual beacons configured on the server, these beacons will be combined into a smaller number of matching regions for monitoring and ranging purposes. By default, this value is -1, which means that no rollup will occur. This method has been deprecated and the setting no longer has any effect.
void	setPartnerIdentifier(String identifier) Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)
void	setProximityKitGeofenceNotifier(ProximityKitGeofenceNotifier notifier) Register the geofence notification callback handler.
void	setProximityKitMonitorNotifier(ProximityKitMonitorNotifier notifier)
void	setProximityKitRangeNotifier(ProximityKitRangeNotifier notifier)
void	setProximityKitSyncNotifier(ProximityKitSyncNotifier notifier)
void	setSyncInterval(long milliseconds) Sets the length of time, in milliseconds, between syncs with the Proximity Kit server.
void	start() Start syncing with the cloud and monitoring for various regions.
void	stop() Stop all Proximity Kit activities.
void	sync() Force a kit sync with the Proximity Kit cloud.
protected void	syncIfNeeded() Deprecated. Not for public use - no replacement. As of 0.13.0 this method could possibly be retained only as a private method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

context

@Deprecated
protected Context context

Deprecated. Not for public use - no replacement. As of 0.13.0 this field could possibly be retained only as a private implementation detail.

Not for Public Use

Constructor Detail

ProximityKitManager

@Deprecated
protected ProximityKitManager(Context context)

Deprecated. Not for public use. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)

Creates an instance of ProximityKitManager using the default properties file.

Not for public use.

Parameters:

context - An application Context for the internal services and storage systems.

Throws:

IllegalStateException - If the properties file cannot be found or loaded.

MissingKeyException - If properties file does not contain one or more required keys.

MissingValueException - If properties file contains null or an empty string for a required key value.

NullPointerException - If context is null.

NumberFormatException - If the value set for KitConfig.CONFIG_SYNC_INTERVAL in the properties file cannot be parsed into a long.

Method Detail

disableGeofences

public void disableGeofences()

Explicitly disable geofence support.

Geofences are disabled by default. The necessary location permissions for geofences are runtime permissions for apps targeting Android 6.0 Marshmallow and newer. If location permissions are revoked after being granted then this should be called to disable geofences.

Min Android API:

9 - Google Play services requires this API level.

enableGeofences

public void enableGeofences()
                     throws GooglePlayServicesException

Explicitly enable geofence support.

It is the caller's responsibility to ensure that the application has properly included and configured the Google Play services library. Additionally, it is the caller's responsibility to ensure that the device supports Google Play services as well as having been granted appropriate permissions. Failure to ensure these will result in a GooglePlayServicesException.

Throws:

GooglePlayServicesException - It is the client's responsibility to ensure that Google Play services is properly listed as a dependency, configured, is granted permission, and available on the device. This exception is thrown under several conditions:

• Google Play services library is not listed as dependencies by the calling app
• Google Play services are not properly configured in the calling app
• The calling app failed to disable geofence when Google Play services were not available on the device

See Also:

Setup Google Play services , Checking if Google Play services is available , Google Play Services and Runtime Permissions

Min Android API:

9 - Google Play services requires this API level.

getInstanceForApplication

@Deprecated
public static ProximityKitManager getInstanceForApplication(Context context)

Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)

Creates an instance of ProximityKitManager.

An accessor for the singleton instance of this class.

A Context must be provided, but if you need to use it from a non-Activity or non-Service class, you can attach it to another singleton or a subclass of the Android Application class.

Throws:

IllegalStateException - If the properties file cannot be found or loaded.

MissingKeyException - If properties file does not contain one or more required keys.

MissingValueException - If properties file contains null or an empty string for a required key value.

NullPointerException - If context is null.

NumberFormatException - If the value set for KitConfig.CONFIG_SYNC_INTERVAL in the properties file cannot be parsed into a long.

getInstance

public static ProximityKitManager getInstance(Context context,
                                              KitConfig config)

Creates an instance of ProximityKitManager.

Sets up a stopped ProximityKitManager with the provided configuration.

WARNING: this currently sets a singleton instance for the application. Do NOT assume that this will always be the case. Calling this method multiple times will overwrite the existing singleton instance. This may result in unexpected behavior if you externally store a reference to old instances. If the prior instance is running configuring a new instance is not allowed and an IllegalStateException is thrown. Until multiple instances are fully supported, we suggest you implement your own ProximityKitManager singleton in your application.

Parameters:

context - An application Context for the internal services and storage systems.

config - The configuration settings for the manager.

Returns:

An instance of ProximityKitManager configured according to config and associated with context.

Throws:

IllegalStateException - If an instance has already been initialized and is currently running.

NullPointerException - If appContext or config are null.

Since:

0.10.0

getBeaconManager

@Deprecated
public BeaconManager getBeaconManager()

Deprecated. Not for public use. As of 0.13.0, no replacement.

Convenience method to access the beacon manager

Not for public use

Returns:

the beacon manager instance bound to this application

Min Android API:

18 - Beacon support is not available until this API level.

debugOn

public static void debugOn()

Turns debugging on for geofences and beacons.

start

public void start()

Start syncing with the cloud and monitoring for various regions.

This will:

• Start syncing data with the Proximity Kit cloud
• Start monitoring for beacons
• Start monitoring for geofences (if enabled)

Set any desired notification callbacks prior to starting the manager. Notifications are not queued. Any notifications which are received prior to a callback being configured will be dropped.

Throws:

IllegalStateException - If another instance of ProximityKitManager is currently running.

Min Android API:

9 - Geofences rely on Google Play services which requires this API level. For API's below this level a warning is issued and geofencing is disabled.

18 - Beacon support is not available until this API level. For API's below this level a warning is issued and beacon support is disabled.

stop

public void stop()

Stop all Proximity Kit activities.

This will:

• Disallow any further syncing
• Unregister all known geofences (if enabled)
• Disconnect from the geofence service (if enabled)
• Unregister all known beacons
• Disconnect from the beacon service

restart

@Deprecated
public void restart()

Deprecated. As of 0.10.0, no replacement. To simply restart the manager use ProximityKitManager.stop() and ProximityKitManager.start(). To use a new configuration create a new manager using ProximityKitManager.getInstance(Context, KitConfig).

Reconfigures the ProximityKit properties at runtime.

This is not really a "restart". It does stop and start the ProximityKitManager instance. But it also plumbs through license manager configuration changes throughout the rest of the library.

You should not need to call this method. Use ProximityKitManager.stop() and ProximityKitManager.start() instead. If you need a new configuration please create one instead using ProximityKitManager.getInstance(Context, KitConfig).

sync

public void sync()

Force a kit sync with the Proximity Kit cloud.

Usage of this API is discouraged. This method is provided mainly for ad-hoc debugging purposes. The majority of kit sync use cases are satisfied by the normal periodic sync defined by the kit configuration's sync interval.

See Also:

KitConfig.CONFIG_SYNC_INTERVAL

syncIfNeeded

@Deprecated
protected void syncIfNeeded()

Deprecated. Not for public use - no replacement. As of 0.13.0 this method could possibly be retained only as a private method.

Sync now but only if it is time

Not for public use.

This is used internally to attempt to sync on various device events. This respects the sync interval configured when the manager is set.

getProximityKitGeofenceNotifier

public ProximityKitGeofenceNotifier getProximityKitGeofenceNotifier()

Getter for the currently configured Geofence notification callback handler.

Returns:

the configured ProximityKitGeofenceNotifier or null if nothing has been configured.

Min Android API:

9 - Google Play services requires this API level.

setProximityKitGeofenceNotifier

public void setProximityKitGeofenceNotifier(ProximityKitGeofenceNotifier notifier)

Register the geofence notification callback handler.

If a handler is already registered this will overwrite it without warning. Providing null as the notifier will clear an existing registered callback.

Parameters:

notifier - The geofence notification callback or null to clear the existing callback.

Min Android API:

9 - Google Play services requires this API level.

setProximityKitMonitorNotifier

public void setProximityKitMonitorNotifier(ProximityKitMonitorNotifier notifier)

getProximityKitMonitorNotifier

public ProximityKitMonitorNotifier getProximityKitMonitorNotifier()

setProximityKitRangeNotifier

public void setProximityKitRangeNotifier(ProximityKitRangeNotifier notifier)

getProximityKitRangeNotifier

public ProximityKitRangeNotifier getProximityKitRangeNotifier()

setProximityKitSyncNotifier

public void setProximityKitSyncNotifier(ProximityKitSyncNotifier notifier)

getProximityKitSyncNotifier

public ProximityKitSyncNotifier getProximityKitSyncNotifier()

getKit

public Kit getKit()

Current instance of the Kit setup on the Proximity Kit cloud servers.

The instance of the Kit may change after a successful sync. Be aware when holding references to the Kit that it may become stale and will no longer reflect the actual Kit in use.

Returns:

current instance of Kit reflecting the last sync with the Proximity Kit cloud

setKit

@Deprecated
public void setKit(Kit kit)

Deprecated. As of 0.13.0, no replacement.

Used by the system when sync'ing data from the server.

Not for public use.

getBeaconAdapter

@Deprecated
public com.radiusnetworks.proximity.proximitykit.BeaconAdapter getBeaconAdapter()

Deprecated. Not for public use. As of 0.13.0, no replacement.

Not for public use.

Returns:

As of 0.13.0 this always returns null.

Min Android API:

18 - Beacon support is not available until this API level.

setPartnerIdentifier

@Deprecated
public void setPartnerIdentifier(String identifier)

Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)

Sets the partner identifier string for analytics. Limited to 255 characters.

Parameters:

identifier -

Since:

0.7.0

clearPartnerIdentifier

@Deprecated
public void clearPartnerIdentifier()

Deprecated. As of 0.10.0, replaced by ProximityKitManager.getInstance(Context, KitConfig)

Clears the partner identifier string for analytics.

Since:

0.7.0

setSyncInterval

public void setSyncInterval(long milliseconds)

Sets the length of time, in milliseconds, between syncs with the Proximity Kit server.

This method is provided mainly for ad-hoc debugging purposes. The majority of kit sync use cases are satisfied by setting the interval through the KitConfig instead.

This does not change the value of the manager's base KitConfig. Instead it updates the current interval. This will be reset on the next app start.

Note that syncing does tax battery life as well as consume network bandwidth, so we do not recommend setting this to a low value.

The minimum value is 300000L ms.

Parameters:

milliseconds - Length of time, in milliseconds, between syncs with the Proximity Kit server.

See Also:

KitConfig.CONFIG_SYNC_INTERVAL

setMaxRegionsBeforeRollup

@Deprecated
public void setMaxRegionsBeforeRollup(int regionCount)

Deprecated. As of release 0.5.0. This setting no longer does anything, as regions for monitoring and ranging may now be explicitly configured on the ProximityKit server. If you are using this roll up feature, please switch to configuring your ranging and monitoring regions explicitly on the server. Sets the maximum number of regions that may be individually configured in ProximityKit before the regions will start being automatically combined. By default, each beacon or region in the ProximityKit server results in one monitoring and ranging region. In cases of large numbers of individual beacons configured on the server, these beacons will be combined into a smaller number of matching regions for monitoring and ranging purposes.

By default, this value is -1, which means that no rollup will occur.

This method has been deprecated and the setting no longer has any effect.

Parameters:

regionCount -

getMaxRegionsBeforeRollup

@Deprecated
public int getMaxRegionsBeforeRollup()

Deprecated. As of release 0.5.0. This setting no longer does anything, as regions for monitoring and ranging may now be explicitly configured on the ProximityKit server. If you are using this roll up feature, please switch to configuring your ranging and monitoring regions explicitly on the server. Gets the maximum number of regions that may be individually configured in ProximityKit before the regions will start being automatically combined. This method has been deprecated and the setting no longer has any effect.

Returns:

region count

See Also:

ProximityKitManager.setMaxRegionsBeforeRollup(int)