Deeplinks can be used for launching catalogs, scenarios, the contact list, or a call to a specific user. The Deeplink URL can be retrieved from CMS and then used to launch the app with the appropriate action.
In addition to performing the action for that deeplink, users can add additional data from a third-party system by adding extra parameters to the URL.
In this article
Deeplink Anatomy
Deeplinks are essentially special URLs that can be used to launch the Worklink App from a device:
worklink://resource?action=fetch_catalog&catalog=123456
This is an example of a catalog deeplink. Other types of deeplinks would have different action parameters and supporting parameters for that action.
Lets break it down:
worklink://
- The first part of the Deeplink is the scheme. Thisworklink
scheme refers to the Worklink App. Devices with the Worklink App installed recognize that URLs with this scheme will mean that the device should launch the Worklink App when this URL is clicked on, instead of going to a new web page.resource
- This is thedomain
and is required for all URLs. In this case, it used to ensure that the URL is structured correctly and recognizable to the Worklink App.?
- Everything after the?
question mark are called query parameters and will be used by the Worklink App to do different things.action=fetch_catalog
- The Worklink App will need anaction
query parameter present to perform actions. The values of this parameter can be changed to perform that action. In this example, it will be fetching a catalog to display in the Worklink App. There are other actions that can be taken and will explained in the next section.&
- The&
ampersand symbol is used to delineate different query parameters. This could also appear as%3D
when it is URL encoded.catalog=123456
- Each defined action would require additional query parameters in order for the Worklink App to correctly perform the action. In the case offetch_catalog
, the Worklink App needs the id of the catalog to retrieve. In this example, the catalog id is set to123456
.
Deeplink Actions
Fetch Catalog
Will open a catalog in the Worklink App. Any additional query parameters added to this Deeplink will be treated as external data and attached to any scenario sessions that are created from the opened catalog.
Query Parameter Values
Action:
fetch_catalog
Resource Key:
catalog
Resource Value: The ID of the catalog.
Example: worklink://resource?action=fetch_catalog&catalog=123456
Fetch Company Contact
Used to display the company contacts in the Worklink App. Any additional query parameters added to this Deeplink will be treated as external data and attached to any call sessions created from this contact list.
Query Parameter Values
Action:
fetch_company_contacts
Resource Key:
company_contacts
Resource Value: The permalink of the company.
Example: worklink://resource?action=fetch_company_contacts&company_contacts=jedi_order
Fetch User
Used to initiate a call session in the Worklink App. Additional query parameters will be added as external data to the call session that is created.
Query Parameter Values
Action:
fetch_user
Resource Key:
user
Resource Value: The username of the user to be contacted
Example: worklink://resource?action=fetch_user&user=lukeskywalker
Fetch Scenario
Used to create a new scenario session in the Worklink App. Additional query parameters will be added as external data to the scenario session that is created.
If the Deeplink’s targeted Scenario is a Persisted Session type, it will open the active session if the user has already created a session for that Scenario, rather than create a new session.
Query Parameter Values
Action:
fetch_scenario
Resource Key:
scenario
Resource ID: The ID of the scenario.
Example: worklink://resource?action=fetch_scenario&scenario=123456
Adding External Data
Deeplinks accept an arbitrary number of extra query parameters which can be used to link data in customer (or 3rd party) systems with ScopeAR data.
The ScopeAR platform stores extra parameters received as key-value pairs in a JSON Hash attribute on Scenario Sessions or Call Sessions created by the Worklink app.
We call these parameters “external data”, as it is data supplied by the external customers.
Example #1
All properly encoded query parameters are accepted, e.g.:
worklink://resource?action=fetch_catalog&asset=42&hello=world&anything=you_want
becomes ScenarioSession.externalData
= { “hello”: “world”, “anything”: “you_want” }
Example #2
Even nested query parameters are accepted, e.g.:
worklink://resource?action=fetch_catalog&asset=42&anything=you_want&even%5Bdeeply2%5D%5Bnested%5D=arguments
becomes ScenarioSession.externalData
=
{ "anything": "you_want", "even": { "deeply2": { "nested": "arguments" } } }
Querying Records
To query for records that have external data populated by a Deeplink, refer to this article on how to do GraphQL queries with external data: Queries using External Data
Deferred Deeplinks
Deeplinks are typically shortened when they are displayed within the ScopeAR CMS for easy sharing. These shortened Deeplinks are called Deferred Deeplinks. A Deferred Deeplink will look like the following:
http://getworklink.com/abc
Or take the form of a QR Code:
A Defered Deeplink will bring the User to the getworklink service and prompt the user to install the Worklink app (if not already installed) before redirecting to a standard Deeplink:
These Deferred Deeplinks can be found in the ScopeAR CMS web interface in various places:
Fetch Catalog
The Fetch Catalog Deferred Deeplink can be found on a catalog page:
Fetch User
The Fetch User Deferred Deeplink can be found on a user profile page:
Fetch Scenario
The Fetch Scenario Deferred Deeplink is found on a scenario page:
Fetch Contact List
The Fetch Contact List Deferred Deeplink is found on the company page under the settings tab: