Using Deeplinks

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

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. This worklink 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 the domain 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 an action 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 of fetch_catalog , the Worklink App needs the id of the catalog to retrieve. In this example, the catalog id is set to 123456.

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: https://scopearcloud.atlassian.net/wiki/spaces/API/pages/2325315585

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: