- Description
- Setup your account
- Submitting Contributions
- Installing pre-requisites
- Using the Plugin
- Accessing plugin object
- Methods
- initSitumSDK
- setApiKey
- setUserPass
- setCacheMaxAge
- startPositioning
- stopPositioning
- fetchBuildings
- fetchFloorsFromBuilding
- fetchIndoorPOIsFromBuilding
- fetchOutdoorPOIsFromBuilding
- fetchEventsFromBuilding
- fetchPoiCategories
- fetchMapFromFloor
- fetchPoiCategoryIconNormal
- fetchPoiCategoryIconSelected
- invalidateCache
- requestDirections
- requestNavigationUpdates
- updateNavigationWithLocation
- removeNavigationUpdates
- requestRealTimeUpdates
- removeRealTimeUpdates
- checkIfPointInsideGeofence
- requestAuthorization
- sdkVersions
- getDeviceId
- onEnterGeofences
- onExitGeofences
- License
- More information
- Support information
Situm React Native Plugin is a set of utilities that allow any developer to build React Native location based apps using Situm's indoor positioning system. Among many other capabilities, apps developed with Situm React Native Plugin will be able to:
-
Obtain information related to buildings where Situm's positioning system is already configured: floorplans, points of interest, geotriggered events, etc.
-
Retrieve the location of the smartphone inside these buildings (position, orientation, and floor where the smartphone is).
-
Compute a route from a point A (e.g. where the smartphone is) to a point B (e.g. any point of interest within the building).
-
Trigger notifications when the user enters a certain area.
You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.
In this tutorial, we will guide you step by step to set up your first React Native application using Situm React Native Plugin. Before starting to write code, we recommend you to set up an account in our Dashboard (https://dashboard.situm.es), retrieve your API KEY and configure your first building.
-
Go to the sign in form and enter your username and password to sign in.
-
Go to the account section and on the bottom, click on “generate one” to generate your API KEY.
-
Go to the buildings section and create your first building.
-
Download Situm Mapping Tool in Play Store (Only Android devices) and calibrate your building. Check out our user guide for detailed information.
-
You are ready for building your own React Native applications. Please check next steps about requirements
Firstly you need to setup react-native development environment. To get started please follow instructions under section React Native CLI Quickstart on this guide.
In this we assume you have already created an hybrid application with React Native. After that there are some different ways to install the plugin:
yarn add https://github.com/situmtech/situm-react-native-plugin.git
#OR
npm install --save https://github.com/situmtech/situm-react-native-plugin.git
Make sure to delete node_modulles/
at project/node_modules/react-native-situm-plugin/node_modules
.
Note: As of now the SDK is available only on Github. When updating the SDK, make sure to delete the existing one from node_modules/react-native-situm-plugin
.
yarn add react-native-situm-plugin
#OR
npm install --save react-native-situm-plugin
You'll need to add the follow repository in your project gradle file
allprojects {
repositories {
maven {
url "https://repo.situm.es/artifactory/libs-release-local"
}
}
}
You'll need to add depedency in PodFile
target 'YourApp' do
pod 'ReactNativeSitumPlugin', :path => '../node_modules/react-native-situm-plugin/ReactNativeSitumPlugin.podspec'
end
You may need to add a Header Search Path: (screenshot)
$(SRCROOT)/../node_modules/react-native-situm-plugin/lib/ios
In order to use the plugin in a React Native component all you need is the following:
import SitumPlugin from "react-native-situm-plugin";
SitumPlugin.fetchFloorsFromBuilding(building,
(floors) => {...},
(error) => {...},
);
NOTE: This plugin is currently under development. There may be method not implemented yet. Also there may be some API changes as development progresses.
Method that initialize the SDK. This method needs to be called once before using the rest of the methods.
SitumPlugin.initSitumSDK();
Log in into your Situm Account. This key is generated in Situm Dashboard. Return true if apiKey was set successfully, otherwise false
SitumPlugin.setApiKey("SITUM_EMAIL","SITUM_API_KEY")
Provides user's email and password.
SitumPlugin.setUserPass("SITUM_EMAIL","SITUM_USER_PASSWORD")
Set the remote configuration state which allows to use the configuration (location request) stored on the web to find the location of the user.
SitumPlugin.setRemoteConfig("true", (success: any) => {});
Sets the maximum age of a cached response in seconds.
SitumPlugin.setCacheMaxAge(1*60*60) // 1 hour
Starts the positioning system.
const locationOptions = {
buildingIdentifier: building.buildingIdentifier,
};
const subscriptionId = SitumPlugin.startPositioning(
(location) => {
//returns location object
console.log(JSON.stringy(location))
},
(status) => {
//returns positioning status
console.log(JSON.stringy(status))
},
(error: string) => {
// returns an error string
console.log(error)
},
locationOptions
)
Stop the positioning system on current active listener. Make sure to pass subscriptionId
received from start positioning updates for those particular listeners.
SitumPlugin.stopPositioning(subscriptionId, (success: any) => {});
Download all the buildings for the current user.
const getBuildings = () => {
SitumPlugin.fetchBuildings(
(buildings) => {
// returns list of buildings
if (!buildings || buildings.length == 0)
alert(
'No buildings, add a few buildings first by going to:\nhttps://dashboard.situm.es/buildings',
);
},
(error) => {
// returns an error string
},
);
};
Download the information (floors, pois, ...) of a building.
const getBuildingInfo = () => {
SitumPlugin.fetchBuildingInfo(
building,
(buildingInfo) => {
// returns a building info object
},
(error) => {
// returns an error string
},
);
};
Download all the floors of a building.
const getFloorsFromBuilding = () => {
SitumPlugin.fetchFloorsFromBuilding(
building,
(floors) => {
// returns list of floors
},
(error) => {
// returns an error string
},
);
};
Download the indoor POIs of a building.
const getPOIsFromBuilding = () => {
SitumPlugin.fetchIndoorPOIsFromBuilding(
building,
(pois) => {
// returns list of POIs
},
(error) => {
//returns error string
}
);
};
Download the outdoor POIs of a building.
const getPOIsFromBuilding = () => {
SitumPlugin.fetchOutdoorPOIsFromBuilding(
building,
(pois) => {
// returns list of POIs
},
(error) => {
//returns error string
}
);
};
Download the events of a building.
const getEventsFromBuilding = () => {
SitumPlugin.fetchEventsFromBuilding(
building,
(events: any) => {
// returns list of events
},
(error) => {
//returns error string
}
);
};
Get all POI categories, download and cache their icons asynchronously.
const getPoiCategories = () => {
SitumPlugin.fetchPoiCategories(
(categories) => {
// returns list of categories
},
(error) => {
//returns error string
}
);
};
Download the map image of a floor.
const getMapFromFloor = (floor) => {
SitumPlugin.fetchMapFromFloor(
floor,
(map) => {
// map image in Base64 format
},
(error) => {
// returns error string
},
);
};
Get the normal category icon for a POICategory.
const getPoiCategoryIconNormal = (category) => {
SitumPlugin.fetchPoiCategoryIconNormal(
category,
(icon) => {
// returns base64 icon
},
(error) => {
//returns error string
}
);
};
Get the selected category icon for a POICategory.
const getPoiCategoryIconSelected = (category) => {
SitumPlugin.fetchPoiCategoryIconSelected(
category,
(icon) => {
// returns base64 icon
},
(error) => {
//returns error string
}
);
};
Invalidate all the resources in the cache.
SitumPlugin.invalidateCache();
Calculates a route between two points.
const points = [
{
floorIdentifier: floor.floorIdentifier,
buildingIdentifier: building.buildingIdentifier,
coordinate: {latitude:41.37968, longitude:2.1460623},
},
{
floorIdentifier: floor.floorIdentifier,
buildingIdentifier: building.buildingIdentifier,
coordinate: {latitude:41.375566, longitude:2.1467063},
}
];
SitumPlugin.requestDirections(
[building, ...points],
(route) => {
// returns route object
let latlngs = [];
for (let segment of route.segments) {
for (let point of segment.points) {
latlngs.push({
latitude: point.coordinate.latitude,
longitude: point.coordinate.longitude,
});
}
}
setPolylineLatlng(latlngs);
},
(error) => {
// returns error string
console.log(error);
}
);
Necessary step to request progress. Alone this method does not provide progress object. You must feed navigation API with location, as indicated on updateNavigationWithLocation section.
const requestNavigationUpdates = () => {
SitumPlugin.requestNavigationUpdates(
(navigation) => {
//returns navigation object
},
(error) => {
//returns error string
},
{
distanceToGoalThreshold: 3,
outsideRouteThreshold: 50
}
);
};
Usually, position variable should be one of the locations provided by the system on the startPositioning function.
SitumPlugin.updateNavigationWithLocation(currentLocation)
When you are no longer interested on Navigation Updates you should call this method to remove internal allocated resources.
SitumPlugin.removeNavigationUpdates();
Emits the real time location of devices
const requestRealtime = () => {
SitumPlugin.requestRealTimeUpdates(
(locations) => {
// returns list of locations
},
(error) => {
// returns error string
},
{ building: building, pollTime: 3000 }
);
};
When you are no longer interested on realtime location Updates you should call this method to remove internal allocated resources.
SitumPlugin.removeRealTimeUpdates();
Checks if a point on the map is inside a geofence
SitumPlugin.checkIfPointInsideGeofence(
{ coordinate: coordinate },
(response) => {
// returns geofence name and id if point is inside a geofence
}
);
Request location permissions on Android & iOS
SitumPlugin.requestAuthorization()
Returns iOS, Android and react native SDK versions depending on the platform the app is running on.
SitumPlugin.sdkVersions(response=>{
// e.g. {ios: "2.45.0", android: "1.60@aar", react_native:"0.0.3"}
});
Returns user's device Id generated by SitumSDK
SitumPlugin.getDeviceId(response=>{
// e.g. {deviceId: 12345678}
});
Warning This method is available only in Android by now.
Get notified about entering geofences. Take into account:
- This method must be called before the positioning is started.
- Positioning geofences (with
trainer_metadata
custom field) won't be notified. - This callback only work with indoor locations. Any outdoor location will produce a call to onExitedGeofences with the last positioned geofences as argument.
SitumPlugin.onEnterGeofences((geofences) => {
// e.g. [{"polygonPoints": [], "customFields": {}, "updatedAt": "Thu Jan 01 01:00:00 +0100 1970", "buildingIdentifier": "1234", "floorIdentifier": "123456", "code": "", "createdAt": "Thu Jan 01 01:00:00 +0100 1970", "infoHtml": "", "name": "My Geofence", "identifier": "12345678-aaaa-bbbb-cccc-12345678abcd"}]
});
Warning This method is available only in Android by now.
Get notified about exiting geofences. Take into account the considerations described at onEnterGeofences.
Situm-React-Native-Plugin is licensed under MIT License
More info is available at our Developers Page.
For any question or bug report, please send an email to support@situm.com