Glympse En Route Cordova Plugin

Interact with Glympse's native iOS/Android SDKs through this plugin from your Cordova application.

What you need

Before getting started you'll need a Firebase app id from Glympse based on your application's package name. This will allow push notifications from Glympse to be sent to your application on Android. iOS will need separate configuration for push notifications (see Push Notifications)

This plugin requires a minimum of cordova@8

Installation

During installation you'll add the Firebase App ID you received from Glympse.

cordova plugin add @glympse-inc/com.glympse.enroute --variable GLYMPSE_FIREBASE_APP_ID="[YOUR_FIREBASE_APP_ID_FROM_GLYMPSE]"

If you don't yet have this ID you can pass in an empty string, but push notifications won't work until this ID is set.

Starting up the Glympse Platform

The first call to Glympse should be call to init(). This method initializes the plugin and starts to sync basic cached data from the native SDK such as whether or not a user is logged in.

EnRouteManager.init();

Next an application declares whether it uses credentials for login or if login will use an authentication token.

EnRouteManager.setAuthenticationModeCredentials();
// or
EnRouteManager.setAuthenticationModeToken();

Last step during every startup is a call to start()

EnRouteManager.start();

If authentication is needed at this point the authenticationNeeded event will be sent and the application can then perform a login() using credentials entered by the user or by using an authentication token.

Listening for Events

You can add listeners to respond to a variety of events that are emitted by the plugin.

A listener is an object that implements functions matching the events you want to listen for.

Example

var glympseListener = {};
glympseListener.started = function() {
    console.log('Glympse platform started');
}
glympseListener.authenticationNeeded = function() {
    console.log('Glympse authentication needed');
}
glympseListener.loggedOut = function(reason) {
    console.log('Glympse logged out: ' + reason);
}
// etc...
EnRouteManager.addListener(glympseListener);

EnRouteManager events

• available - Occurs after a call to EnRouteManager.init() to notify that the plugin finished its first sync
• started - Occurs after a call to EnRouteManager.start()
• authenticationNeeded - Occurs anytime after a call to EnRouteManager.start() notifying that re-authentication is needed
• loginCompleted - Occurs after a call to EnRouteManager.loginWithToken() or loginWithCredentials()
• synced - Occurs after login indicating that the platform has synced data with the server
• loggedOut(reason) - Occurs after a logout from user action or auth token becoming invalid
• stopped - Occurs when the platform has been stopped
• locationAccuracyUpdated - Platform detected that location accuracy authorization has changed
• predefinedMessagesUpdated - Predefined chat messages for the Organization have changed

TaskManager events

• taskListChanged - Task manager's task list has updated
• taskStarted(task) - Occurs after a call to TaskManager.startTask()
• operationCompleted(taskId) - Occurs when a Task has completed
• taskPhaseChanged(task, phase) - Task has changed to a different phase
• taskChatMessagesChanged(task) - Chat messages for a Task have changed
• taskTravelModeUpdated(task) - Travel mode updated (drive/cycle/transit/walk)
• taskRouteChanged(task) - Calculated route for a Task updated
• taskCreated(taskJsonData) - Occurs after a call to TaskManager.createTask()
• taskCreateFailed(taskJsonData, error) - Call to TaskManager.createTask() failed

AgentManager events

• agentListChanged - Occurs when the list of Agents is refreshed
• agentUpdated - Occurs after a change was made to the logged in Agent (name/email/etc)
• agentUpdateFailed - A call to update the logged in Agent failed

PickupManager events

• pickupListChanged - PickupManager's list of pickups has updated
• pickupChanged(pickup) - Occurs when a Pickup is updated
• pickupAccepted(pickup) - Occurs when a Pickup has entered the live phase. This indicates the customer has started to interact with the Pickup by sharing location or with a manual ETA
• pickupCompleted(pickup) - Occurs when a Pickup is completed
• pickupFailedToComplete(pickup) - The call to complete a Pickup failed
• pickupPhaseUpdated(pickup) - Occurs when a Pickup changes to a different phase
• pickupFailedToUpdatePhase(pickup) - The call to update a Pickup's phase failed
• pickupAssigned(pickup) - Occurs when a Pickup is claimed or assigned to an Agent
• pickupFailedToAssign(pickup) - The fall to claim a pickup failed
• pickupChatMessagesChanged(pickup) - Chat message for a Task have changed

Plugin Usage

Most functions in the plugin's interface serve as a bridge to make a call on the native SDK. It may be helpful to reference the Programming Guide for the native SDK to understand the terminology used in this plugin https://developer.glympse.com/docs/enroute/client-sdk/guides/programming-guide

EnRouteManager

This is the central manager through which all other managers are accessed. It handles the state of the SDK during startup, login, and foreground/background changes.

Methods

• init() - Called first when using the plugin to initialize the plugin
• setActive(active: bool) - Called when the application enters the foreground(true) or background(false)
• addListener(listener: object) - Called to set a listener for events from EnRouteManager
• removeListener(listener: object) - Called to remove a listener from EnRouteManager
• getTaskManager(): TaskManager - Get the TaskManager object
• getAgentManager(): AgentManager - Get the AgentManager object
• getPickupManager(): PickupManager - Get the PickupManager object
• isStarted(): bool - Returns true if the plugin is in the started state
• isLoginNeeded(): bool - Returns true if a call to login is currently needed
• getLoggedInAgent(): Agent - Returns the currently logged in Agent
• getLoggedInOrg(): Organization - Returns the currently logged in Organization
• getEnRouteToken(): string - Returns the current authentication token for the logged in Agent
• registerDeviceToken(tokenType: string, deviceToken: string) - Registers a push token. tokenType should be "apple_background" for iOS
• handleRemoteNotification(payload: string) - Used to forward a received push notification from Glympse
• setAuthenticationModeCredentials() - Called before start() to specify that credentials will be used for login
• setAuthenticationModeToken() - Called before start() to specify that an auth token will be used for login
• start() - Starts the plugin and native SDK. If the Agent is already logged in this will start to sync data, otherwise the authenticationNeeded event will fire.
• loginWithCredentials(username, password) - Used to login with a username and password
• loginWithToken(token, expireTime) - Used to login with an authentication token. expireTime is epoch time in milliseconds
• logout() - Called to logout the current Agent
• stop() - Stops the plugin and the native SDK. This should be called if it's expected that the user will no longer be utilizing En Route during the current session.
• overrideLoggingLevels(fileLogLevel: number, debugLogLevel: number) - Can be used to increase log output for debugging and development (1=verbose logs, 7=no logs)
• setFetchCompletedTasks(enabled: bool) - Configures the SDK to fetch completed Tasks or to only fetch tasks that have not been completed (default)

TaskManager

Keeps track of currently fetched Tasks that are assigned to the logged in Agent. It's used to update these Tasks if the Agent needs to perform a manual action such as marking a Task as completed or cancelled.

Methods

• addListener(listener: object) - Called to set a listener for events from TaskManager
• removeListener(listener: object) - Called to remove a listener from TaskManager
• getTasks(): Task[] - Retrieve the list of currently fetched Tasks
• refreshTasks() - Manually refreshes the list of Tasks
• startTask(task: Task, duration: number) - Start the provided task with a specified duration in milliseconds. The duration will be extended or shortened as needed by the platform, so it is acceptable to provide a reasonable default such as 1 hour (3600000)
• createTask(taskData: Object) - Create a Task with the provided json object. See https://developer.glympse.com/docs/enroute/api/reference/org/id/create_task/post
• setTaskPhase(task: Task, phase: string) - Update the phase of a started Task
• setTaskVisibility(task: Task, visibility: string) - Update the visibility of a Task (visible, cloaked, or hidden)
• completeTask(task: Task) - Mark a Task is completed. This is a final state for a Task, so if it is initiated by a user you should ask for confirmation
• findTaskById(taskId: number): Task - Lookup a Task by its id number
• addOrUpdateMetadataItem(task: Task, key: string, value: string|number|bool) - Add or update a Task Metadata field. Value can be a string, number, or bool
• setTravelModeForTask(task: Task, travelMode: string) - Update the travel mode for a Task (drive/cycle/transit/walk)
• sendMessageToTask(task: Task, message: string, predefinedMessageId: number, successCallback: function, errorCallback: function) - Send a chat message to this Task as the logged in Agent
• markMessagesAsRead(task: Task) - Set the status of the chat messages for this Task as read. Called when the user views the most recent message

AgentManager

Manages the currently logged in Agent and allows the user to update some of the Agent's properties. Admin and Manager Agents can update other Agents in their Organization.

Methods

• addListener(listener: object) - Called to set a listener for events from AgentManager
• removeListener(listener: object) - Called to remove a listener from AgentManager
• getSelf(): Agent - Get the currently logged in Agent
• getAgents(): Agent[] - Retrieve the list of currently fetched Agents from the Organization
• refreshAgents() - Manually refreshes the list of Agents in the Organization
• updateAgentName(agent: Agent, name: string) - Updates the Agent's name
• updateAgentDisplayName(agent: Agent, displayname: string) - Updates the Agent's name that is displayed to the customer
• updateAgentEmail(agent: Agent, email: string) - Updates the Agent's email address
• updateAgentPassword(agent: Agent, password: string) - Updates the Agent's password
• updateAgentAvatar(agent: Agent, avatar: string, contentType: string) - Updates the Agent's avatar. The avatar parameter is image data as a string. contentType should be "image/png" or "image/jpeg"
• findAgentById(agentId: number): Agent - Lookup an Agent by their id number

PickupManager

Keeps track of currently fetched Pickups from the logged in Organization. All Pickups from the Organization are fetched including ones that are unassigned and assigned to other Agents. This manager is used to update these Pickups if the Agent needs to perform a manual action such as changing the Pickup phase or assigning it to themselves.

Methods

• addListener(listener: object) - Called to set a listener for events from PickupManager
• removeListener(listener: object) - Called to remove a listener from PickupManager
• getPickups(): Pickup[] - Retrieve the list of currently fetched Pickups
• findPickupById(pickupId: string): Pickup - Lookup a Pickup by its id number
• refreshPickups() - Manually refreshes the list of Pickups
• setPickupPhase(pickup: Pickup, phase: string) - Update the phase of a Pickup
• completePickup(pickup: Pickup) - Mark a Pickup as completed. This is a final state for a Pickup, so if it is initiated by a user you should ask for confirmation
• claimPickup(pickup: Pickup) - Assign a Pickup to the currently logged in Agent
• unclaimPickup(pickup: Pickup) - Release assignement of a Pickup
• sendMessageToPickup(pickup: Pickup, message: string, predefinedMessageId: number, successCallback: function, errorCallback: function) - Send a chat message to this Pickup as the logged in Agent
• markMessagesAsRead(pickup: Pickup) - Set the status of the chat messages for this Pickup as read. Called when the user views the most recent message

Push Notifications

On iOS, a cordova application will need to register for push notifications, and pass these push notifications onto the En Route platform.

Glympse will need you to also send your APNS certificate so that we can send notifications to your app.

If your application is already registering for push tokens and handling notification payloads, there are two methods that will need to be called inside of your existing code.

// When a token is available
EnRoute.registerDeviceToken('apple_background', token);
// When a payload is available
EnRoute.handleRemoteNotification(payload);