Skip to main content

App Launcher Partner Guide

Documentation Overview

The RapidSOS App Launcher provides a RapidSOS Partner the ability to make their web application directly accessible and available for launch within RapidSOS Portal. 

This document is intended for prospective or active App Launcher Partners. It provides information on the App Launcher, details required for development and testing, as well as additional useful information to consider. 

 

App Launcher Overview

 

Solution Flow

The App Launcher has the following three core capabilities:

  1. The ability to launch a Partner Web App in a new browser tab via a button click in RapidSOS Portal
  2. The optional ability for a Partner Web App to eliminate additional user logins via the RapidSOS Identity Management API 
  3. The optional ability for a Partner Web App to receive data via the RapidSOS Deeplink API

The following diagram depicts a high-level solution flow of the App Launcher. 

 

Figure 1: App Launcher Solution Overview

 

Solution Details

 

Launching Web Apps

All App Launcher solutions appear within the RapidSOS Tools Menu for authorized users in RapidSOS Portal. There are two categories of App Launcher solutions.

  1. Global
  2. 911 Only

The difference between these two solution categories is when each is accessible inside RapidSOS Portal as outlined in the following table:

#

App Launcher Category

Accessible when user in 'All Events View'

Accessible when user in '911 Event View'

Accessible when user in 'Alert Event View'

Disclaimer below description in Tools Menu

1

Global 

Yes

Yes

Yes

#N/A

2

911 Only

No

Yes

No

See ’Views in RapidSOS Portal' below for details on ‘All Events View’, ‘911 Event View’, ‘Alert Event View’.

 

Once a user selects an App Launcher solution in the Tools Menu, the corresponding Partner Web App opens in a new browser tab. 

RapidSOS App Launcher inside RapidSOS Portal

Figure 2: App Launcher Solutions in the Tools Menu in RapidSOS Portal

 

Single Sign-On 

The RapidSOS App Launcher’s Single-Sign On (SSO) is an optional feature designed to allow RapidSOS Portal users access to a Partner Web App without any additional login to help streamline their operational workflows. Specifically, RapidSOS offers an OpenID Connect (OIDC) compliant identity server for supporting SSO where RapidSOS acts as the Identity Provider (IDP), the Partner Web App acts as the Service Provider (SP), and the SSO is initiated by the SP. The following diagrams show this architecture flow:

RapidSOS SSO can integrate with any OpenID Connect Identity Provider. Popular services like Auth0, OneLogin, AWS Cognito and Okta all support this. You can also integrate directly to your own custom identity management service.

Figure 3: SP initiated SSO with OIDC Overview

 

Figure 4: SP initiated SSO with OIDC Flow Diagram

You can find our OpenID Connect well known configuration for our:

  • Sandbox environment here
  • Production environment here

Figure 5: Initial Landing Page

Initial landing page will be shown when setting SSO for the first time. Login prompt will be initiated to store the cookie on your local browser. After the cookie has cleared, the next attempt to login will re-appear.

 

Receiving DAta 

The RapidSOS App Launcher has an optional feature that allows a Partner Web App to receive data from the RapidSOS Emergency Response Data Platform. Partners utilizing this feature can provide smarter, more contextualized solutions that better streamline ECC workflows than those simply using the RapidSOS App Launcher to redirect users to their web app without any data/context. Partners can receive data from RapidSOS by utilizing the RapidSOS Deeplink API. The following diagram outlines the receiving data architecture:Figure 5: Receiving Data Mechanism Overview

The data available to share is in part a function of the current ‘View’ of the Portal user making the launch. Partners can be configured to receive the following information from the RapidSOS Emergency Response Data Platform:

Data Field Name

Details/Description

Example

Available in 'All Events View'

Available in '911 Event View'

Available in 'Alerts Event View'

ecc_account_id

A unique identifier for the launching ECC

“ecc_account_id”: "NY_1234"

Yes

Yes

Yes

bounding_box

A pair of lat/longs that represent the most top left point and most bottom most point the launching ECC’s jurisdictional boundary.

“bounding_box”: {

 

  "top_left": {

 

    "latitude": 40.74,

 

    "longitude":-73.98

 

  },

 

  "bottom_right": {

 

    "latitude": 40.71,

 

    "longitude": -73.94

 

  }

Yes

Yes

Yes

query

The phone number of a selected 911 event

"query": "tel://15555555555"

No

Yes

No

Please see the Deeplink OpenAPI Specification hereNote that this link is a truncated version of the Open API Specification

 

Developing and Testing an App Launcher Solution

Partners can develop and test their App Launcher solutions within the RapidSOS Sandbox environment. The following sections are designed to help provide instruction on how you, as a Partner, can develop and test your App Launcher solution. 

Please note the following:

  • Login credentials will provide access to a specific RapidSOS Portal account that has its own jurisdictional boundaries. 
  • If you would like to set the jurisdictional boundary of your existing Sandbox Portal account to a different region, please contact partnernetwork@rapidsos.com 
  • If you don’t have login credentials, please contact partnernetwork@rapidsos.com

 

Accessing Sandbox

The RapidSOS Sandbox environment provides a complete replica of the RapidSOS Portal browser application including the App Launcher capability. 

You can access RapidSOS Portal on Sandbox by performing the following:

  1. From your web browser navigate to the Sandbox RapidSOS Portal URL: https://sandbox.rapidsosportal.com
  2. Click the Login button at the upper right corner
  3. Enter your Username and Password

Please note the following:

  • Login credentials will provide access to a specific RapidSOS Portal account that has its own jurisdictional boundaries. 
  • If you would like to set the jurisdictional boundary of your existing Sandbox Portal account to a different region, please contact partnernetwork@rapidsos.com
  • If you don’t have login credentials, please contact partnernetwork@rapidsos.com

 

Launching a Web App

Your Partner Web App will be available to launch from the Tools Menu in RapidSOS Portal. To launch, a Portal User will select the Tools Menu button in the top left of the screen, locate the your Partner Web App from the Tools drop-down list, and select it. Note that depending on the configuration, your Partner Web App may require the Portal user to have a 911 call selected in RapidSOS Portal in order to launch. 

Upon selection, the browser will open a new tab and the Portal user will be directed to a URL you specify. Please contact partnernetwork@rapidsos.com to let us know what URL your App Launcher solution should open to.

RapidSOS will append a 'rsos_token' query parameter to the specified URL. This secure token will contain an encrypted form of the data you want to receive from RapidSOS. The following sections describe how you can mimic creating this token yourself for testing as well as how you would decrypt this token to retrieve data from RapidSOS. 

Please note: Your web browser must be configured in its setting to successfully open a new browser tab. Utilizing incognito browser may result in multiple requests for login-credentials. See the following for instructions for the web browsers supported by RapidSOS Portal: Chrome, Firefox, Edge, Safari

 

Creating a Secure Token 

Although in practice RapidSOS will be responsible for generating the secure token and providing it as the 'rsos_token value appended to the URL you specify, the following section contains instructions on how to create a secure token, to help conduct your own testing.

Creating a secure token entails the following steps:

  1. Generating a User JSON Web Token (JWT)
  2. Specifying Data to Receive
  3. Sending a Deeplink request

 

Generating a User JWT

A user JWT authenticates you as a user in the Sandbox environment and is required in order to create a secure token. The following request will generate a user JWT which you’ll need to store for use later on (see the Sending a Deeplink Request). Use the login credentials which were provided for your dedicated account on the sandbox environment

curl --location --request POST 'https://api-sandbox.rapidsos.com/v1/scorpius/user/api-token-auth' \
--header 'Content-Type: application/json' \
--data-raw '{
	"email": [sandbox account email],
	"password": [sandbox account password]
}'

 

Specifying Data to Receive

The secure token contains the encrypted data that you have specified you would like to receive. RapidSOS enables App Launcher Partners to receive the following information from the RapidSOS Emergency Response Data Platform. 

  • Phone number of a selected 911 call in RapidSOS Portal (“query”)
  • ECC Account ID (“ecc_account_id”)
  • ECC Jurisdiction Boundary Box (“bounding_box”)

Please contact partnernetwork@rapidsos.com to let us know what data you would like to receive from us.

Below are examples of the data available to receive:

"query": "tel://15555555555"

“ecc_account_id”: "NY_1234",

“bounding_box”: {

  "top_left": {

    "latitude": 40.74,

    "longitude":-73.98

  },

  "bottom_right": {

    "latitude": 40.71,

    "longitude": -73.94

  }

}

Please note the following:

 

Sending a Deeplink Request

To generate the secure token, you’ll need to test decrypting (see Decrypting a Secure Token section lower in this document), make a Deeplink API request using both the user JWT you generated (see Generating a User JWT listed above) as well as data want to receive (see Specifying Data to Receive described above).

curl --location --request POST '[app launch URL]' \
--header 'Authorization: Bearer [User JWT]' \
--header 'Content-Type: application/json' \
--data-raw '{
	"query": "tel://15555555555"
“ecc_account_id”: "NY_1234",
“bounding_box”: {
  "top_left": {
    "latitude": 40.74,
    "longitude":-73.98
  },
  "bottom_right": {
    "latitude": 40.71,
    "longitude": -73.94
  }
}
}'


}'

Please note the following:

  • The value of [app launch URL] will be provided after your application and RapidSOS Portal account have been configured on the RapidSOS Sandbox environment. A successful response will contain a single key/value: { "url": "https://www.partnerwebsite.com?rsos_token=[Encrypted Token]"}
  • The URL 'https://www.partnerwebsite.com' provided in the example must be changed to whatever URL you specify to use. Contact partnernetwork@rapidsos.com to let us know what URL you want your Web App to open to.
  • The encrypted token is everything after 'rsos_token='

 

Decrypting a Secure Token

Whether you have received a secure token from RapidSOS or you have created a secure token yourself (see Creating a Secure Token described above), you can decrypt the token and extract the data embedded in it by making a POST request to the unauthenticated app token decrypt endpoint using the token as shown in the the following example:

curl --location --request POST 'https://api-sandbox.rapidsos.com/v1/deeplink/<partner application>/decrypt' \

--header 'Content-Type: application/json' \

--data-raw '{

"token": "<rsos_token value>"

}'

The above returns the unencrypted token payload.

Please note: The deeplink ‘partner_web_map’ is an example only and must be changed to the specific endpoint that will be configured for you.. Contact partnernetwork@rapidsos.com if you're not sure of your partner decryption endpoint.

 

Additional Information

Partner Eligibility 

For a 3rd-party to make their web application accessible from the RapidSOS Portal via the App Launcher, they must be an approved integration partner that serves public safety. Please contact partnernetwork@rapidsos.com for additional information and approval.

 

Operations & Usage Compatibility

The following important operational aspects must be clearly understood in relation to implementation and usage compatibility.

URL Whitelisting

As the operability of the web app is the partners responsibility, the partner is also responsible for ensuring the domains and subdomains their web app utilizes are properly whitelisted at agencies. 

Please note: RapidSOS can help assist in that process through posting the necessary URLs on the RapidSOS Support and Training Centers when requested.

 

ECC Enablement 

The ability to launch your web app in RapidSOS Portal will only be enabled at agencies authorized by you, the partner.

 

 Views in RapidSOS Portal

View Name

Details/Description

Example

All Events View

When ‘All Calls’ is selected such that any and all 911 Events (calls and/or texts) and Alert Events that fall within the ECC’s jurisdiction are shown on the map. This is also known as ‘Jurisdiction View’.

911 Event View

When a 911 Event (call or text) is selected in the 911 queue. 

Alerts Event View  

When an Alert Event is selected in the Alert queue. 

 

Helpful Resource Links

For more information about integrating your partner web application solution with RapidSOS Portal, email: partnernetwork@rapidsos.com.

 

Items for RapidSOS 

Below are the summary of items a Partner needs to provide RapidSOS to implement the RapidSOS App Launcher.

Item

Description

Constraint

Optional/Required

App Launcher Solution Category Global or 911 Only (See details above) #N/A Required

Base URL

The URL opened after the Partner solution is launched from RapidSOS Portal.

 

Note that the base URL can be configured per environment e.g. sandbox, production, etc..

Must be a valid URL. e.g. 'https://rapidsos.com'

Required

SSO Redirect URL

The URL the RapidSOS Identity Management system will redirect to after authenticating a RapidSOS Portal user. See Single Sign-On above for more details.

Note that this is only required if the Partner App Launcher solution is utilizing SSO. Upon receiving this redirect URL, RapidSOS will provide the necessary SSO access credentials.

Must be a valid URL. e.g. 'https://rapidsos.com' Optional

Solution Name

The text of the solution's Tools drop-down menu option in RapidSOS Portal.

Max length is 30 characters including spaces.

Required

Solution Description

The text description of the solution that appears in Tools drop-down menu.

Max length is 280 characters including spaces.

Required

Partner Name

The text that appears in the RapidSOS Portal Admin page that identifies the creator of the Web App.

#N/A

Required

URL Whitelist Guide

The URLs an ECC needs to access in order to utilize the Partner Web App.

#N/A

Optional

Supported Web Browsers

The web browsers that are supported by the Partner Web App.

#N/A

Optional

Support Contact

The name and email address of the Partner Web App team member who should be notified in the case of any technical issues or questions that the RapidSOS support team cannot answer.

#N/A

Required

User Manual

The user training manual for Partner Web App.

#N/A

Required

Sandbox Portal Jurisdiction

The geographical area you would like your Sandbox RapidSOS Portal account set to e.g. Pittsburgh, PA. You’ll use this Sandbox account during development and testing.

#N/A Required

FAQ

Q: Can the ‘Base URL’ of a Partner App Launcher solution (i.e. the URL opened after the Partner solution is launched from RapidSOS Portal) change depending on the launching ECC?

A: No. The App Launcher only supports opening one pre-configured ‘Base URL’ regardless of the particular launching ECC. For Partners looking to tailor their web app experience to individual ECC’s, we recommend utilizing the unique ECC Account ID to identify the launching ECC. The ECC Account ID can be embedded within the secure token as detailed above. If you have more questions or are interested in pursuing a custom solution with RapidSOS, please contact PARTNERNETWORK@RAPIDSOS.COM.

 

Q. Can the ‘Base URL’ of a Partner App Launcher solution (i.e. the URL opened after the Partner solution is launched from RapidSOS Portal) change depending on whether the RapidSOS Portal user is in an ‘All Events View’, ‘911 Event View’, or ‘Alert Event View’?

A: No. The App Launcher only supports opening one pre-configured ‘Base URL’ regardless of the particular ‘View’ of the individual Portal user launching. For ‘Global’ App Launcher Partners looking to tailor their web app experience based on the context of the individual launching, we recommend utilizing the presence or absence of ‘query’ data field to help infer if the Portal user making the launch was in a ‘911 Event View’ or not as the ‘query’ will only be present if the Portal user is in a ‘911 Event View’. The ‘query’ data field can be embedded within the secure token as detailed above. If you have more questions or are interested in pursuing a custom solution with RapidSOS, please contact PARTNERNETWORK@RAPIDSOS.COM.

 

About us

We build APIs that share data with first responders to help protect lives.

RapidSOS logo

Contact