#Cordova

Integrate our Cordova Plugin.

#Quick Start

GeoSpark provides an Cordova plugin that enables App developers to track location, geofence and trips.


#Step 1: Install the plugin

In your project directory, install from npm, and then add it.


$ npm i cordova-plugin-geospark
$ cordova plugin add cordova-plugin-radar

#Step 2: Install SDK

iOS

Configure Project

To configure the location services, add following entries to the Info.plist file.

Then, in your project settings, go to Capabilities > Background Modes and turn on background fetch, location updates, remote-notifications.

Then, go to Build Settings in the project targets and change Always Embed Swift Standard Libraries to Yes.


pod 'GeoSpark' 

#Step 3: Initialize SDK

Android

iOS

Import GeoSpark into your AppDelegate file.

Initialize the SDK in your AppDelegate class before calling any other GeoSpark methods under this application:didFinishLaunchingWithOptions:




///In GeoSparkPlugin class include the code below.

@Override
public void initialize(CordovaInterface cordova, CordovaWebView webView) {
    super.initialize(cordova, webView);
        GeoSpark.initialize( this.cordova.getActivity().getApplication(), "PUBLISHABLEKEY");
} 



//Swift
import GeoSpark

//Objective-C
#import <GeoSpark/GeoSpark.h>


//Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions 
launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  GeoSpark.intialize("PUBLISHABLEKEY")
  return true
}

#Step 4: Create User

GeoSpark SDK needs a User ID object to identify the device.


cordova.plugins.geospark.createUser("Description", function(success){
    // do something on success
}, function(error){
    // do something on error
});

#Step 5: Get permissions

Get location permission from the App user on the device. Also check if the user has turned on location services for the device. In addition, get motion permission for iOS.

iOS

Android


// Call this method to check Location Permission for Android & iOS
cordova.plugins.geospark.checkLocationPermission(function(status){
    // do something with status
});
// Call this method to request Location Permission for Android & iOS
cordova.plugins.geospark.requestLocationPermission(function(status){
    // do something with status
});  



// Call this method to check Motion Permission for iOS
cordova.plugins.geospark.checkActivityPermission(function(status){
 // do something with status
});

// Call this method to request Motion Permission for iOS
cordova.plugins.geospark.requestActivityPermission(function(status){
 // do something with status
});



// Call this method to check Location services for Android
cordova.plugins.geospark.checkLocationServices(function(status){
 // do something with status
});
// Call this method to request Location services for Android
cordova.plugins.geospark.requestLocationServices(function(status){

 // do something with status
});

#Step 6. Start Location tracking

To start tracking the location.


cordova.plugins.geospark.startTracking();

#Utility Methods

#Initialize SDK

Android

iOS

Import GeoSpark into your AppDelegate file.

Initialize the SDK in your AppDelegate class before calling any other GeoSpark methods under this application:didFinishLaunchingWithOptions:

//In GeoSparkPlugin class include the code below.
@Override
public void initialize(CordovaInterface cordova, CordovaWebView webView) {
    super.initialize(cordova, webView);
    GeoSpark.initialize( this.cordova.getActivity().getApplication(), "PUBLISHABLEKEY");
}



//Swift
import GeoSpark

//Objective-C
#import <GeoSpark/GeoSpark.h>



//Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions 
launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  GeoSpark.intialize("PUBLISHABLEKEY")
  return true
}

#Set DeviceToken

Android

GeoSpark SDK is capable of sending push notifications to your users. Add Firebase to your Android project to get device token.

iOS

GeoSpark SDK is capable of sending push notifications to your users. Check here to get device token.


GeoSpark.setDeviceToken(this, "FCM DeviceToken");

            

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
  [GeoSpark setDeviceToken:deviceToken];
}

#Create User

GeoSpark SDK needs an User ID object to identify the device. The SDK has a convenience method createUser() to create a user which returns User ID.


cordova.plugins.geospark.createUser("Description", function(success){
    // do something on success
}, function(error){
    // do something on error
});

#Get User

If you already have an User ID, then SDK has a convenience method getUser() to start the session for the existing user.


cordova.plugins.geospark.getUser("UserId", function(success){
    // do something on success
}, function(error){
    // do something on error
});  

#User Description

Adding description for the user makes it easier for you to identify your users, while tracking them in SDK. GeoSpark SDKs provide you with the option to modify the description any time for a user. This can also help you in easily identifying users on dashboard simply via the description.


cordova.plugins.geospark.setDescription("Description", function(success){
    // do something on success
}, function(error){
     // do something on error
});

#Toggle User Events

Use this method after user creation to enable user events for geofence, activity and trips. By default, all user events will be disabled post user creation.


cordova.plugins.geospark.toggleEvents(geofence, trip, activity,
function(success){
    // do something on success
}, function(error)  {
    // do something on error
});

#Get User Event Status

Use this method after user creation to get the current status of user events for geofence, activity and trips.


cordova.plugins.geospark.getEventsStatus(function(success){
    // do something on success
}, function(error){
    // do something on error
});

#Check Location Permission

The SDK requires Location Permission to be granted.

status will be a string, one of:

  • GRANTED
  • DENIED

// Call this method to check Location Permission for Android & iOS
cordova.plugins.geospark.checkLocationPermission(function(status){
    // do something with status
});  
            

#Check Motion Permission

iOS

The SDK requires motion permission to be granted.

status will be a string, one of:

  • GRANTED
  • DENIED

// Call this method to check Motion Permission for iOS
cordova.plugins.geospark.checkActivityPermission(function(status){
    // do something with status
});   
          

#Check Location Tracking

Check whether location tracking is started or not. This method returns boolean value.

status will be a string, one of:

  • ENABLED
  • DISABLED

cordova.plugins.geospark.isLocationTracking(function(status){
    // do something with status
});

#Check Location Services

Android

The SDK requires GPS to be enabled and Location Services to be enabled with High Accuracy.

Status will be a string, one of:

  • ENABLED
  • DISABLED

// Call this method to check Location services for Android
cordova.plugins.geospark.checkLocationServices(function(status){
    // do something with status
});  
            

#Request Location Permission

To request location permissions for the app, call

Status will be a string, one of:

  • ENABLED
  • DISABLED

// Call this method to request Location Permission for Android & iOS
cordova.plugins.geospark.requestLocationPermission(function(status){
    // do something with status
});
                

#Request Motion Permissions

iOS

To request location permissions for the app, call

Status will be a string, one of:

  • GRANTED
  • DENIED

// Call this method to request Motion Permission for iOS
cordova.plugins.geospark.requestActivityPermission(function(status){
    // do something with status
});            
                

#Request Location Services

Android

To enable GPS for the app, call

status will be a string, one of:

  • ENABLED
  • DISABLED

// Call this method to request Location services for Android
cordova.plugins.geospark.requestLocationServices(function(status){
                    
    // do something with status
});

#Start Location Tracking

To start tracking the user location.


cordova.plugins.geospark.startTracking();

#Stop Location Tracking

You can stop tracking the user location.


cordova.plugins.geospark.stopTracking();

#Location listener

You only need to call these methods once, as these settings will be persisted across App sessions.

To listen for location updates, you can add event listeners:

Android

To listen for location in the background, register the receiver by adding a receiver element to the application element in your manifest.

You can also remove event listeners:


<application>
        ...
    <receiver android:name=".GeoSparkPlugin$GeoSparkCordovaReceiver"
                android:enabled="true"
                android:exported="false">
            <intent-filter>
            <action android:name="com.geospark.android.RECEIVED"/>
            </intent-filter>
    </receiver>
    ...
</application>


onDeviceReady: function() {
    this.receivedEvent('deviceready');
    cordova.plugins.geospark.onEvents(app.onGeoSparkEvents);
    cordova.plugins.geospark.onError(app.onGeoSparkError);
}


onGeoSparkEvents: function(userId, location) {
    // do something with userId, location
},
onGeoSparkError: function(error) {
    // do something on error
}

cordova.plugins.geospark.offEvents();
cordova.plugins.geospark.offError();

#Current Location

Get current location of the user. You can set the accuracy from 20 to 100 meters.


cordova.plugins.geospark.getCurrentLocation(accuracy, function(success){
    // do something on success
}, function(error){
    // do something on error
});

#Update Current Location

Using updateCurrentLocation method, one can update user current location, you can set the accuracy from 20 to 100 meters (default is 20).

Note: This method should be used only if you need to update the current location of the device with better accuracy. Using this method often might consume battery.


cordova.plugins.geospark.updateCurrentLocation(accuracy);

#Start Trip

Start trips in Geospark SDK, using startTrip() method.


cordova.plugins.geospark.startTrip("TripId", "Description", function(success){
    // do something on success
}, function(error){
    // do something on error
});

#End Trip

End trips in Geospark SDK, using endTrip() method.


cordova.plugins.geospark.endTrip("TripId", function(success){
    // do something on success
}, function(error){
    // do something on error
});    

#Active Trips

Get active trips in GeoSpark SDK, using activeTrips() method.


cordova.plugins.geospark.activeTrips(function(success){
    // do something on success
}, function(error){
    // do something on error
});                    

#setTrackingInAppState

Call this method to configure GeoSpark SDK settings for enabling location tracking during given app states.

iOS

Call this method to configure GeoSpark SDK settings for enabling location tracking during given app states.

Parameter Description
SETTINGS Option 1: FOREGROUND (or) BACKGROUND (or) Terminated
Option 2: ALWAYS_ON

Android

Parameter Description
SETTINGS Option 1: FOREGROUND (or) BACKGROUND
Option 2: ALWAYS_ON

cordova.plugins.geospark.setTrackingInAppState([SETTINGS])

cordova.plugins.geospark.setTrackingInAppState([SETTINGS])

#setTrackingInMotion

Call this method to configure GeoSpark SDK settings for enabling location tracking during given motion tracking.

iOS

Parameter Description
SETTINGS Option 1: Stationary (or) Walking (or) Running (or) AutoMotive
Option 2: ALL

Android

Parameter Description
SETTINGS Option 1: STOP (or) WALK (or) RUNNING (or) BICYCLE (or) DRIVE
Option 2: ALL

cordova.plugins.geospark.setTrackingInMotion([SETTINGS])

cordova.plugins.geospark.setTrackingInMotion([SETTINGS])

#Notification Opened Handler

By using this method inside FirebaseMessagingService class, track the campaigns impressions and counts.


//Android

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    super.onMessageReceived(remoteMessage);
    NotificationManager notificationManager = (NotificationManager)
context.getSystemService(Context.NOTIFICATION_SERVICE);
    ...
    intent.putExtra(GeoSpark.EXTRA,
GeoSpark.notificationReceiveHandler(remoteMessage.getData()));
    ...
    notificationManager.notify(NotificationID, builder.build());
}


//MainActivity.java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    GeoSpark.notificationOpenedHandler(this, getIntent());
}


//iOS
-(void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler{
  [GeoSpark notificationOpenedHandler:response];
  completionHandler();
}

#Logout

Logout from GeoSpark SDK, using logout() method.

NOTE : You need to reinitialize the SDK in case you want to login again.


cordova.plugins.geospark.logout(function(success){
    // do something on success
}, function(error){
    // do something on error
});   

#Disable Battery Optimization (android 6+)

When running the SDK on Android 6 (and higher), it is recommended to ask the user to disable battery optimization for your application. This makes sure that detections continue to work properly when the device is in Doze mode. Moreover, on Android Pie, it prevents Adaptive Battery from bucketing your app based on usage and restricting background processing, all of which that can impact the detection quality of the SDK.

After explaining to the user about the benefits of disabling battery optimization, call the disableBatteryOptimization() method of the GeoSpark class.


cordova.plugins.geospark.disableBatteryOptimization();

#Check Battery Optimization

Check battery optimization

status will be a string, one of:

  • ENABLED
  • DISABLED

cordova.plugins.geospark.isBatteryOptimizationEnabled(function(status){

    // do something with status
});
        

#Changelog

Keep yourself updated.

#v1.0.0 - (October 23, 2019)

  • First release of the 1.0.0 version of the Cordova plugin 🚀🎉