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:

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

 

A user can select an App Launcher solution either in the Tools drop-down menu or in the Toolbar that appears adjacent to the Tools drop-down menu. Note that the Toolbar only appears when a user is in a ‘911 Event View’. Once a user selects an App Launcher solution, the corresponding Partner Web App opens in a new browser tab.

Figure 2: App Launcher Solutions in theToolbar in RapidS OS Portal

 

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

Note that:

• The Toolbar only appears when a user is in a ‘911 Event View’
• Not all App Launcher solutions are applicable to appear in the Toolbar

 

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 4: SP initiated SSO with OIDC Overview

Figure 5: 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 6: 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.

* Note: RapidSOS does not support SSO implementations where the prompt paramter is set to 'none'. *

 

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 7: 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:

Please note the following:

• Both the LEI and RAD-E API will not return any information after 10 minutes of the end of the selected 911 phone call.
• The RAD-E API will only return additional data from data source partners that are enabled and activated at the ECC launching the web app.
• The RAD-E API is not configured to return any additional data provided by Apple (e.g. Medical ID
• Only applicable partners that serve public safety are eligible to receive call location and additional data information. Please contact PARTNERENABLEMENT@RAPIDSOS.COM to learn whether your organization is eligible.

 

Please see the Deeplink OpenAPI Specification here. Note 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”)
•  
• Incident location (i.e. lat/long) of selected 911 call (“incident_location”)
• RAD-E / LEI API token for accessing additional data and/or the latest location of selected 911 call (“access_token”)
• 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",

“incident_location”: {

  "latitude": 40.746523,

  "longitude": -73.980876,

  "location_accuracy": 25.0

},

“access_token”: "abc123",

“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:

• Only applicable partners are eligible to receive call location information i.e. "query", “incident_location”, and “access_token”. Please contact PARTNERENABLEMENT@RAPIDSOS.COM to learn whether your organization is eligible. 
• The "query" value should match the "device_number" of any provisioned test call (see Provisioning a Test Call)

 

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",
     “incident_location”: {
          "latitude": 40.746523,
          "longitude": -73.980876,
          "location_accuracy": 25.0
      },
      “access_token”: "abc123",
      “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

 

Helpful Resource Links

• Integrated RapidSOS Portal (IRP V.2) API which uses Deep Link retrieval to integrate into partner solutions. 
• LEI (Latest Emergency Information) API - This interface is for use by authorized public-safety entities to access location data for an emergency call.
• RAD-E (RapidSOS Additional Data) ENHANCED API - This interface is for use by authorized public-safety entities to access additional data associated with an emergency call. The additional data can potentially come from various RapidSOS data source partners (e.g. Uber, MedicAlert, etc…)
• Deeplink OpenAPI Specification - This Open API specification provides a REST API for retrieving Deep Links.
• OpenID Connect allows clients to launch sign-in flows and receive verifiable assertions about the identity of signed-in users.
• RapidSOS Partner Tool Guide - Instructions on how to use the RapidSOS Partner Tool for simulating emergency calls inside the RapidSOS Sandbox environment for testing and demonstration purposes. 

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.

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’ and/or ‘incident_location’ data fields to help infer if the Portal user making the launch was in a ‘911 Event View’ or not as both ‘query’ and ‘incident_location’ will only be present if the Portal user is in a ‘911 Event View’. The ‘query’ and ‘incident_location’ data fields 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.