Difficulty: expert
Content
Learning Objectives
After reading this article, you’ll be able to:
Set up deep links from 3rd party app to Workplace app
In a 3rd party application, create deep links to launch specific features/screens in the Workplace app.
The linking mechanism is supported on the standard Workplace app, both on iOS and Android platforms.
What are deep links?
Deep links are predefined custom URLs, which can be used to invoke an app from an external app or environment. For example, selecting the “navigate” button on a website launches the default “maps” application on the device where navigation is started automatically.
Both iOS and Android platforms support such a linking mechanism.
Prerequisites
To activate an application which supports deep links, the following conditions must be ensured:
The destination app (in this case: The Workplace App) must be installed on the device
The source app must invoke the custom URL to trigger navigation
The deep link URL must be well formatted and pass all required parameters, as expected by the destination app.
Deep links in Workplace app
The Workplace app supports deep links to the below screens or features:
Book a room
View live floorplan
Deep-link construction format
The deep link is constructed out of 3 sections:
Scheme – The URL which is registered by an app. It informs the system that the app can handle links starting with this scheme.
Host – A unique identifier for the app/feature that you want to invoke. This is usable if multiple pages in an app handle the same Scheme.
Parameters – A list of key-value pairs, which can be captured by the application. Both keys and values should be of string type.
The format in which these are structured is:
PA://spacewell?targetview={0}&extraparam={1}&username={2}
Where,
Scheme = PA://
Host = spacewell
Parameters = targetview, extraparam and username
Host and Scheme
For now, both host and scheme should remain constant while creating deep links for integration with the Workplace app. The expected values are described above.
The Workplace app is designed in such a way that it can handle Scheme in both upper and lower case, as it is case sensitive.
Make sure not to mix upper and lower case in the Scheme.
Allowed
PA://…. OR pa://….
Not allowed
Pa://…. OR pA://….
Parameters
The following parameters are expected by Workplace app for enabling the use cases above.
Key | Purpose | Required | Details |
targetview | The target screen to be launched via the deep link. | Yes | Should be one of the predefined 5 values, as described in the next chapter. |
extraparam | For passing additional ID/value based on targetview | Optional | The allowed combinations of targetview and extraparam are described in the next chapter. |
username | Workplace username or email ID of the user.
For an unauthenticated user, user identification is required in Workplace app: trigger the login flow.
For a logged in user, to ensure that the same user is authenticated across Workplace app and source app.
If email ID is used, the same email ID must be configured for the Workplace user. | No | When username is passed as a parameter: For an unauthenticated user, Workplace app will capture the value and fill it on the username screen. It will automatically detect whether SSO is enabled for the user or not and trigger the relevant authentication flow. It’s not possible to login with a different user in this case.
For a logged in user, Workplace app will capture the username and ensure that the same user is logged in. If not, the current user session will be terminated and login flow will be triggered for the user captured in the link.
When username is not passed as a parameter: If no value is passed from the source app, the user comparisons are skipped in Workplace app.
For an unauthenticated user, the Workplace username should be entered manually in Workplace app as the first step. Any Workplace user is allowed to login.
On the other hand, an authenticated user with an active Workplace session in Workplace app can continue using the app when navigating from a deep link too. No user comparisons are made. |
targetview and extraparam combinations
The below combinations of targetview and extraparam combinations are supported by Workplace app. If an incorrect value is passed for targetview, the Workplace app will show a relevant error message and navigate back to the launcher app. Back navigation is supported out of the box on Android only.
targetview | extraparam | Description |
BOOK_ROOM | Not required | Navigates to “Book a room” screen where user can start searching for a room. |
FLOORPLAN | Optional | To navigate to a live floorplan view.
With extraparam: The floor ID (as per data received from Workplace APIs, see Rest API) should be passed as a parameter to launch the desired live floorplan without any explicit floor selection. The floor should be inside the current building selected in Workplace app.
Without extraparam: When using this link for the first time, the user will be asked to select a floor from the available floors inside the current building. On subsequent launches, the previously selected floor will be remembered, and the live floorplan will be shown by default. The user still has a possibility to switch between the floors in the same building.
The previous selection will be cleared in the below scenarios:
|
Examples
Launch “Book a room” screen
structure: "PA://spacewell?targetview={0}&extraparam={1}&username={2}"
{0} - “BOOK_ROOM”
{1} – “”
{2} - “” OR Workplace username/ email address
→ example: “PA://spacewell?targetview=BOOK_ROOM”
Try it yourself:
Launch “Floorplan” screen
structure "PA://spacewell?targetview={0}&extraparam={1}&username={2}"
{0} - “FLOORPLAN”
{1} – “” OR location ID of the floor you want to open in floorplan view
{2} - “” OR Workplace username/ email address
→ general example, opening “All Floors” view if multiple floor plans are available in a building: “PA://spacewell?targetview=FLOORPLAN”
→ concrete example, using floor ID to open 1 particular floor in our own Spacewell tenant: “PA://spacewell?targetview=FLOORPLAN&extraparam=910000000004545”
Try it yourself:
How to activate Workplace app (destination app) from a link in a source app?
A deep link can be considered the same as a web URL, which means that it can be launched like any other web URL. It can be involved on click of a button, pasted in the device’s web browser (Chrome/Safari) or involved from a native iOS or Android app.
Shared below are some examples, which might help in implementing the logic in the source apps.
Xamarin iOS example
string url = string.Format("PA://spacewell?targetview={0}&extraparam={1}&username={2}", viewName, extraParamValue, userName);
UIApplication.SharedApplication.OpenUrl(new NSUrl(url));
Xamarin Android example
string url = string.Format("PA://spacewell?targetview={0}&extraparam={1}&username={2}", viewName, extraParamValue, userName);
Android.Net.Uri uri = Android.Net.Uri.Parse(url);
Intent intent = new Intent(Intent.ActionView, uri);
StartActivity(intent);
Web/JavaScript
Using page redirects
window.location.replace("PA://spacewell?targetview=FLOORPLAN&extraparam=0000012345&username=aaa");
Using a link
<a href="PA://spacewell?targetview=FLOORPLAN&extraparam=0000012345&username=aaa">Floorplan</a>
How to navigate back to the source app?
Android
Back navigation in Android is supported out-of-the-box. When a user navigates back from the Workplace app and the app was invoked from a deep link, Workplace app is dismissed, and the user can continue working on the previous app.
This offers a seamless navigation experience to the user.
iOS
On iOS platform, when an app is launched (Workplace app in this case), the launcher app is automatically dismissed to the background. Subsequently, back navigation to the previous app is not available out of the box.
If back navigation is required, the same deep linking mechanism can be used, but in the opposite direction. To enable this, the Workplace app will launch the source app (iOS app) via a deep link defined in the source app.
To enable this feature, most likely a development is required in the source iOS app; where Workplace app can trigger back navigation using the below URL scheme.
“pabacknavigation”
This can be achieved by implementing the below changes in the source iOS app:
In the AppDelegate, implement OpenURL method and return true.
In info.plist, add a custom URL scheme. It must be called “pabacknavigation”
If back navigation is not needed, the user will have to manually switch back to the source app after performing an operation in the Workplace iOS app.
Search