...
| Excerpt |
|---|
This guide helps SMART App developers follow best practice guidelines to create marketable "about" pages, social media link previews, and interchangeable manifest files, and patient banners. |
All examples in this page come from the HSPC the Logica Patient Data Manager (PDM) and Bilirubin Risk Chart apps. The code can be found at https://bitbucket.org/hspconsortium/patient-data-manager and https://bitbucket.
...
org/hspconsortium/bilirubin-risk-chart.
Marketing Page
So, you have an app that launches great from within the HSPC the Logica sandbox or EHR system. But what happens when the your app is loaded outside of these authorization spaces? What does the user see? Usually, it's either a garbage page or your app with no loaded data. We suggest to you take advantage of these instances by advertising your app's capabilities by creating opportunities by instead showing a marketing page through your index.html file. Here's an example of the index.html rendering of the HSPC the Logica PDM app (https://patient-data-manager.hspconsortiumlogicahealth.org).
We As you create this page, we recommend including at least 3 different features:
- A description of what the app does and why the user should use/purchase it.
- A screenshot of the app
- Provide a A link where they can open the app in a test environment as a demo
...
On top of a nicely rendered marketing page, you'll want to be able to control what is rendered when someone shares your app url on social media. This is done by integrating metadata in into your index.html page within the header section.
...
Here's the metadata found in the Patient Data Manager PDM app:
And here's what the rendering looks like in Google+. Similar renderings are done in Facebook, Twitter, and Pinterest.
...
Important: If you've made any changes to your metadata since you or anyone else has posted on Facebook, you'll need to clear the cache through the Facebook debugger tool (https://developers.facebook.com/tools/debug). Plug in the app url, click "Debug", then click "Scrape Again" in the new page. Twitter has a similar process (https://cards-dev.twitter.com/validator).
...
Three manifest files are stored as json files called manifest.json, manifest.test.json, and manifest.prod.json for local, testing, and production environments, respectively. They are must be held stored in the path ".well-known/smart" within the app's source directory.
The standard across different SMART user systems it is to point to the manifest.json file so for launch information. Therefore, when you launch your apps boot the app on your server, change either the manifest.test or manifest.prod file name, depending on what environment you're deploying in, to manifest.json and delete the original manifest.json (which holds information for a local envrionment). The PDM app is deployed using a docker container that, when built, has the ability to make these changes.
This table defines the fields needed in your manifest files:
| Field | Description |
|---|---|
| software_id | Unique identifier for your app. The HSPC The Logica apps use the Maven Coordinates (https://maven.apache.org/pom.html#Maven_Coordinates) |
| client_name | Name of the application |
| client_uri | The marketing index.html address |
| logo_uri | Link to a screenshot of your app |
| launch_url | The html page that handles the Oauth process |
| redirect_uris | List of possible urls that the sandbox/EHR will redirect to after authorization |
| scope | A space-delimited list of scopes (http://docs.smarthealthit.org/authorization/scopes-and-launch-context) |
| token_endpoint_auth_method | String indicator of the requested authentication method for the token endpoint. Values are: "none", "client_secret_post", and "client_secret_basic" (https://tools.ietf.org/html/rfc7591) |
| grant_types | The type of Oauth grant model your app uses: authorization_code or client_credentials are the two choices Array of OAuth 2.0 grant types that the client may use (http://docs.smarthealthit.org/authorization/best-practices) |
| fhir_versions | List of FHIR versions that the app can handle |
Here's an example of the manifest.prod.json file from the Patient Data Manager app:
PDM app:
Patient Banner
When an app is viewed in an EHR system, a patient banner containing certain patient demographics may be displayed, keeping the app in the context of the patient being treated. When designing your app, you may want to include a patient banner just in case the system it is launched in does not have one. You are more than welcome to do so, but you don't want to have two patient banners show up in the user's view. That's why the SMART authorization standard has included a parameter that your app can accept indicating whether to show your app's banner or not. The variable is called "need_patient_banner". It is received in the final step of authorization when the access token and patient id are sent to your app. See http://docs.smarthealthit.org/authorization/scopes-and-launch-context/ for full documentation.
In Logica
The Logica sandbox may be used to test out this functionality. First, build a launch scenario for your app, click the Launch Embedded option, and launch.
Here's an example of the bilirubin app in embedded mode:
And one using its own patient banner:
