API Documentation & Usage Guide iOS
You need to add the Location Updates background mode to your app's capabilities; you can either use Xcode's UI or edit the Info.plist file.
In Xcode
Modify Info.plist
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>For iOS 8.0 or later, you need to add NSLocationAlwaysUsageDescription key to your Info.plist file. This key should contain a text string, this text will be displayed when iOS displays Locations services permission's alert in your app.
<key>NSLocationAlwaysUsageDescription</key>
<string>Data stays secure on your phone. GPS will help us to detect arrivals and departures. Data will be posted anonymously.</string>For iOS 10.0 or later, you need to add NSMotionUsageDescription key to your Info.plist file. This key should contain a text string, this text will be displayed when iOS displays device’s Motion & Fitness permission's alert in your app.
<key>NSMotionUsageDescription</key>
<string>Data stays secure on your phone. Motion activity will help us to detect arrivals and departures. Data will be posted anonymously.</string>- Start predict.io - Start getting callbacks from predict.io.
- Stop predict.io - Stop getting callbacks from predict.io.
- Kick start GPS - Manually activate GPS for a short period of time.
- Get predict.io status - Check status of predict.io, whether it is active or not.
- Get the device identifier - An alphanumeric string that uniquely identifies a device to predict.io.
- Set Custom Parameters - Set custom parameters which can then be sent to a user defined webhook url.
- Set Webhook URL - Set a webhook url where all the detected events can then be forwarded along with the custom parameters. This webhook will not support additional authentication. So any additional validation of legitimate requests must take place.
- Home and work zones - Get home and work zones detected by predict.io
- Clear zones history - Clear historic zone data which is used to predict different zones like home or work zones
This starts predict.io if the delegate and the API-Key are set, otherwise it returns an Error.
/*
* Starts predict.io if delegate and API-Key are set, otherwise it returns an Error
* @param apiKey: PredictIO SDK API Key.
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'start' , ['apiKey']);/*
* Stop predict.io
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'stop', []); Manually activate the GPS for a short period of time.
/*
* Manually activate the GPS for a short period of time i.e. 90 seconds
* predict.io manages the GPS for an optimal battery performance
* if you need a more precise location updates in didUpdateLocations: method
* use this method to make sure that the GPS is active.
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'kickStartGPS' , []); This method returns the status of predict.io, PredictIOStatus (i.e. if it is active or not).
/*
* This method returns the status of predict.io i.e. if it is active or otherwise
* Possible return values are,
* Active : predict.io is in a working, active state
* LocationServicesDisabled : predict.io is not in a working state as the location services are disabled
* InsufficientPermission : predict.io is not in a working state as the permissions to use location services are not provided by the user
* InActive : predict.io has not been started. It is in inactive state
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'status' , []);An alphanumeric string that uniquely identifies a device to predict.io.
/*
* An alphanumeric string that uniquely identifies a device to the predict.io
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'deviceIdentifier' , []);Set custom parameters which can then be sent to a user defined webhook url.
/*
* Set custom parameters which can then be sent to a user defined webhook url
* @param key: Key to identify a custom parameter value
* @param value: Custom parameter value
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'setCustomParameter' , ['push_id', 'abcd']);Set a webhook url where all the detected events can then be forwarded along with the custom parameters. This webhook will not support additional authentication. So any additional validation of legitimate requests must take place.
/*
* Set a webhook url where all the detected events can then be forwarded along with the custom parameters.
* This webhook will not support additional authentication. So any additional validation of legitimate requests must take place.
* @param url: The webhook url
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'setWebhookURL' , ['https://example.com/api/notifications']);Use the following properties to get the home and work zones.
/* Home zone of the user detected by PredicIO */
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'homeZone' , []);
/* Work zone of the user detected by PredicIO */
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'workZone' , []);Clear historic zone data which is used to predict different zones like home or work zones.
/*
* Clear historic zone data which is used to predict different zones like home or work zones
*/
cordova.exec(successCallback , errorCallback , 'PredictIOPlugin' , 'clearZoneHistory' , []);- Departing - Invoked when the user is about to depart.
- Departed - Invoked when the user has just departed.
- Canceled Departure - Invoked when the last departure event is unable to validate.
-
Departure Canceled- Invoked when the last departure event is unable to validate. - Detected Transportation Mode - Invoked when transportation mode is detected.
-
Transportation Mode- Invoked when transportation mode is detected. - Suspected Arrival - Invoked when predict.io suspects that the user has just arrived.
-
Arrival Suspected- Invoked when predict.io suspects that the user has just arrived. - Arrived - Invoked when the user has just arrived at the destination.
- Searching In Perimeter - Invoked when the user is searching for a parking space at a specific location.
- Stationary After Arrival - Invoked after few minutes of arriving at the destination and detects if the user is stationary or not.
- Traveled By Airplane - Invoked when predict.io detects that the user has travelled a large distance.
- Did Update Location - Invoked when new location information is received from location services.Event Callbacks Flow Diagram
###Details
This method is invoked when predict.io detects that the user is about to depart
/*
* This method is invoked when predict.io detects that the user is about to depart
* from his location and is approaching to his vehicle
* @param UUID: Trip segment UUID
* @param departureLatitude: The latitude of the location from where the user departed.
* @param departureLongitude: The longitude of the location from where the user departed.
* @param transportMode: Mode of transport
*/
function departing(param) { }This method is invoked when predict.io detects that the user has just departed
/*
* This method is invoked when predict.io detects that the user has just departed
* from his location and have started a new trip
* @param UUID: Trip segment UUID
* @param departureLatitude: The latitude of the Location from where the user departed
* @param departureLongitude: The longitude of the Location from where the user departed
* @param departureTime: Time of departure (The interval between the date and January 1, 1970 at 12:00 a.m. GMT.)
* @param transportMode: Mode of transport
*/
function departed(param) { }This method is invoked when predict.io is unable to validate the last departure event.
/*
* This method is invoked when predict.io is unable to validate the last departure event.
* This can be due to invalid data received from sensors or the trip amplitude.
* i.e. If the trip takes less than 2 minutes(120 seconds) or the distance travelled is less than 1km
* @param departureLocation: The Location from where the user departed
* @param departureTime: Start time of the trip
* @param transportMode: Mode of transport
* @param UUID: Trip segment UUID
*/
function canceledDeparture(param) { }This method is invoked when predict.io detects a transportation mode
/*
* This method is invoked when predict.io detects transportation mode
* @param UUID: Trip segment UUID
* @param: transportationMode: Mode of transportation
*/
function detectedTransportationMode(param) { }This method is invoked when predict.io suspects that the user has just arrived
/*
* This method is invoked when predict.io suspects that the user has just arrived
* at his location and have ended a trip
* Most of the time it is followed by a confirmed arrivedAtLocation event
* If you need only confirmed arrival events, use arrivedAtLocation method (below) instead
* @param UUID: Trip segment UUID
* @param departureLatitude: The latitude of the Location from where the user departed
* @param departureLongitude: The longitude of the Location from where the user departed
* @param arrivalLatitude: The latitude of the Location where the user arrived and ended the trip
* @param arrivalLongitude: The longitude of the Location where the user arrived and ended the trip
* @param departureTime: Time of departure (The interval between the date and January 1, 1970 at 12:00 a.m. GMT.)
* @param arrivalTime: Time of arrival (The interval between the date and January 1, 1970 at 12:00 a.m. GMT.)
* @param transportMode: Mode of transport
*/
function suspectedArrival(param) { }This method is invoked when predict.io detects that the user has just arrived at destination.
/*
* This method is invoked when predict.io detects that the user has just arrived at destination
* @param UUID: Trip segment UUID
* @param arrivalLatitude: The latitude of the Location where the user arrived and ended the trip
* @param arrivalLongitude: The longitude of the Location where the user arrived and ended the trip
* @param departureLatitude: The latitude of the Location from where the user departed
* @param departureLongitude: The longitude of the Location from where the user departed
* @param departureTime: Time of departure (The interval between the date and January 1, 1970 at 12:00 a.m. GMT.)
* @param arrivalTime: Time of arrival (The interval between the date and January 1, 1970 at 12:00 a.m. GMT.)
* @param transportMode: Mode of transport
*/
function arrived(param) { }This method is invoked when predict.io detects that the user is searching for a parking space at a specific location in his/her car.
/*
* This method is invoked when predict.io detects that the user is searching for a
* parking space at a specific location
* @param latitude: The latitude of the Location where predict.io identifies that user is searching for a parking space
* @param longitude: The longitude of the Location where predict.io identifies that user is searching for a parking space
*/
function searchingInPerimeter(param) { }This method is invoked after few minutes of arriving at the destination and detects if the user is stationary or not.
/*
* This method is invoked after few minutes of arriving at the destination and detects if the user is stationary or not
* @param Object contains details about stationary after arrival
* @discussion: The following properties are populated currently:
* UUID: Unique ID for a trip segment, e.g. to link departure and arrival events
* departureLocation: The Location from where the user departed
* arrivalLocation: The Location where the user arrived and ended the trip
* departureTime: Time of departure
* arrivalTime: Time of arrival
* transportationMode: Mode of transportation
* departureZone: Departure zone
* arrivalZone: Arrival Zone
* stationary: User activity status as stationary or not
*/
function beingStationaryAfterArrival(param) { }This method is invoked when predict.io detects that the user has traveled by airplane.
/*
* This method is invoked when predict.io detects that the user has traveled by airplane and
* just arrived at destination, this event is independent of usual vehicle trip detection and
* will not have predecessor departed event
* @param tripSegment: PIOTripSegment contains details about traveled by airplane event
* @discussion: The following properties are populated currently
* UUID: Unique ID for a trip segment
* departureLocation: The Location from where the user started journey
* arrivalLocation: The Location where the user arrived and ended the journey
* departureTime: Time of departure
* arrivalTime: Time of arrival
*/
function traveledByAirplane(param) { }This method is invoked when new location information is received from location services
/*
* This is invoked when new location information is received from GPS
* Implemented this method if you need raw GPS data, instead of creating new location manager
* Since, it is not recommended using multiple location managers in a single app
* @param latitude: The latitude of the new location received from GPS
* @param longitude: The longitude of the new location received from GPS
*/
function didUpdateLocation(param) { }