Quickstart
The GeoSpark React Native SDK makes it quick and easy to build a location tracker for your React Native app. We provide powerful and customizable tracking modes and features that can be used to collect your users location updates.
Here’s a link to our example app : https://github.com/geosparks/geospark-react-native-example
In your project directory, install from npm, and then link it.
$ npm install react-native-geospark --save
$ react-native link react-native-geospark
iOS
Install using Cocoapods, open podfile and add SDK to file.
pod 'GeoSpark'
Once you have updated your podfile, run pod install in your
terminal.
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'.
Manual Linking
-
Open the iOS module files, located inside
node_modules/react-native-geospark/ios/. -
Open the app workspace file
(AppName.xcworkspace)in Xcode. -
Move the
RNGeoSpark.handRNGeoSpark.mfiles to your project. When shown a popup window, select Create groups.
Android
Install the SDK to your project via Gradle in Android Studio, add the
dependencies below in your app build.gradle file.
dependencies {
implementation 'com.geospark.android:geospark:3.1.0'
}
Import the module in App.js file
import GeoSpark from 'react-native-geospark';
Android
Initialize the SDK with your publishable key.
//In onCreate method of your Application class include the code below.
public class MainApplication extends Application implements ReactApplication {
@Override
public void onCreate() {
super.onCreate();
SoLoader.init(this, /* native exopackage */ false);
GeoSpark.initialize(this, "PUBLISH_KEY");
}
};
iOS
Import GeoSpark into your AppDelegate file.
Objective-C
#import <GeoSpark/GeoSpark.h>
Initialize the SDK in your AppDelegate class before calling any other
GeoSpark methods under this application:didFinishLaunchingWithOptions:
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[GeoSpark intialize:@"PUBLISHABLEKEY" :nil :nil :nil :nil :AWSRegionUnknown];
return YES;
}
Once the SDK is initialized, we need to create or get a user to start the tracking and use other methods. Every user created will have a unique GeoSpark identifier which will be used later to login and access developer APIs. We can call it as GeoSpark userId.
GeoSpark.createUser("Description", success => {
// do something on success
},
error => {
// do something on error
});
The option user description can be used to update your user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal user information like email or phone number.
You can always set or update user descriptions later using the below code.
GeoSpark.setDescription("SET USER DESCRIPTION HERE");
If you already have a GeoSpark userID which you would like to reuse instead of creating a new user, use the below to get user session.
GeoSpark.getUser("USER-ID", success => {
// do something on success
},
error => {
// do something on error
});
You can subscribe to locations and events and use the data locally on your device or send it directly to your own backend server.
To do that, you need to set the location and event listener to true using the below method. By default the status will set to false and needs to be set to true in order to stream the location and events updates to the same device or other devices.
GeoSpark.toggleListener(locations, events, success => {
// do something on success
},
error => {
// do something on error
});
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.
// Call this method to check Location Permission for Android & iOS
GeoSpark.checkLocationPermission( status => {
// do something with status
});
// Call this method to request Location Permission for Android & iOS
GeoSpark.requestLocationPermission();
Android
// Call this method to check Location services for Android
GeoSpark.checkLocationServices( status => {
// do something with status
});
// Call this method to request Location services for Android
GeoSpark.requestLocationServices();
To start tracking the location above Android 10
// Call this method to check background location permission for Android
GeoSpark.checkBackgroundLocationPermission( status => {
// do something with status
});
// Call this method to request background location Permission for Android
GeoSpark.requestBackgroundLocationPermission();
GeoSpark.startTracking(TrackingMode);
Use the tracking modes while you use the startTracking method
GeoSpark.startTracking
GeoSpark has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher is the battery consumption. Android you must use foreground service for continuous tracking.
| Mode | Battery usage | **Updates every ** | **Optimised for/advised for ** |
| Active | 6% - 12% | 25 ~ 250 meters | Ride Hailing / Sharing |
| Balanced | 3% - 6% | 50 ~ 500 meters | On Demand Services |
| Passive | 0% - 1% | 100 ~ 1000 meters | Social Apps |
//active tracking
GeoSpark.startTracking(GeoSpark.TrackingMode.ACTIVE);
// balanced tracking
GeoSpark.startTracking(GeoSpark.TrackingMode.BALANCED);
// passive tracking
GeoSpark.startTracking(GeoSpark.TrackingMode.PASSIVE);
The SDK also allows you define a custom tracking mode that allows you to customize and build your own tracking modes.
Android
| Type | Unit | Unit Range |
|---|---|---|
| Distance Interval | Meters | 1m ~ 2500m |
| Time Interval | Seconds | 10s ~ 10800s |
Distance between location updates example code:
//Update location based on distance between locations.
GeoSpark.startTrackingDistanceInterval("DISTANCE IN METERS", "STATIONARY DURATION IN SECONDS",
GeoSpark.DesiredAccuracy.HIGH);
Time between location updates example code:
//Update location based on time interval.
GeoSpark.startTrackingTimeInterval("INTERVAL IN SECONDS", GeoSpark.DesiredAccuracy.HIGH);
iOS
GeoSpark.startTrackingCustom(allowBackground,pauseAutomatic,activityType,
desiredAccuracy,showBackIndicator,distanceFilter,accuracyFilter);
Example
GeoSpark.startTrackingCustom(true,true,GeoSpark.ActivityType.FITNESS,
GeoSpark.DesiredAccuracyIOS.BEST,true,10,10);
You may see a delay if the user's device is in low power mode or has connectivity issues.
To stop the tracking use the below method.
GeoSpark.stopTracking();
PublishOnly
It will start publishing the location updates which will be available for other users or your backend libraries to listen to these location updates. This method will only publish and will not save location data to our server. We will now have an option to send meta-data as a parameter along with location updates in the below json format.
GeoSpark.publishOnly(arrayOfPublishParameters, metadataJSON);
Example
//arrayOfPublishParameters is mandatory
let arrayOfPublishParameters = [GeoSpark.Publish.USER_ID,
GeoSpark.Publish.APP_ID,
GeoSpark.Publish.APP_CONTEXT];
//Metadata is not mandatory
let metadataJSON = {"METADATA": {"1": true, "2": true, "3":true}};
GeoSpark.publishOnly(arrayOfPublishParameters, metadataJSON);
(optional)
GeoSpark.publishOnly(arrayOfPublishParameters, null);
PublishAndSave
It will both publish location data and these data will be sent to Roam servers for further processing and data will be saved in our database servers. We will now have an option to send meta-data as a parameter along with location updates in the below json format.
GeoSpark.publishAndSave(metadataJSON);
Example
//Metadata is not mandatory
let metadataJSON = {"METADATA": {"1": true, "2": true, "3":true}};
GeoSpark.publishAndSave(metadataJSON);
(optional)
GeoSpark.publishAndSave(null);
StopPublishing
It will stop publishing the location data to other clients.
GeoSpark.stopPublishing();
Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.
Subscribe
GeoSpark.subscribe(TYPE, "USER-ID");
UnSubscribe
GeoSpark.unSubscribe(TYPE, "USER-ID");
| Type | Description |
|---|---|
| GeoSpark.SubscribeListener.LOCATION | Subscribe to your own location (or) other user's location updates. |
| GeoSpark.SubscribeListener.EVENTS | Subscribe to your own events. |
| GeoSpark.SubscribeListener.BOTH | Subscribe to your own events and location (or) other user's location updates. |