Deep linking takes users to a sub-page or specific part of a webpage using a custom URL. Deep linking to a plugin allows you to link to a specific page in a custom plugin or to embedded content in an Embedded Pages plugin. To create a deep link, you need to append an additional path to the app URL of the plugin. The additional path in the URL allows the Staffbase platform to interpret the custom URL and redirect the user to the specific content.
Use cases
There are many business use cases for creating deep links to a custom plugin or embedded content. Two common use cases are:
- Link content: If you have an ideation plugin and want to link submissions from users on a page so that others can view the ideas submitted.
- Share content: If you want users to share a specific page in your custom plugin.
Create deep links to a plugin
Your custom plugin and the Embedded Pages plugin both have a main URL. You need to create a custom URL to direct users to a specific page using deep linking.
Main URL
The main URL opens the plugin. It has two parts:
- Base URL: The domain of your employee app or intranet.
For example,https://mycompany.com - Plugin path: The path to the menu item that opens the plugin.
For example,/content/{pluginID}/{menuItemID}
Together they form the main URL, for example https://mycompany.com/content/{pluginID}/{menuItemID}.
The {menuItemID} is the ID of the menu item that opens the plugin. It is not the plugin instance ID (instance_id) that your plugin receives in the SSO token. A link with the instance ID doesn’t open the plugin.
To find the main URL manually, open the plugin in the web app and copy the URL from the address bar.
Get the main URL in your plugin
Your plugin doesn’t receive its menu item ID in the SSO token or in the plugin URL. To build deep links in your plugin, request the plugin instance from the Staffbase API with the installation token. Use the instance_id from the SSO token as {instanceID}.
curl -u "installations/{instanceID}:{secret}" \ "https://mycompany.com/api/installations/{instanceID}"The installation token is installations/{instanceID}:{secret}, sent Base64-encoded as Authorization: Basic {Token}. To get your plugin secret, contact Staffbase Support.
The response contains the plugin path in links.preview.href:
{ "id": "{instanceID}", "pluginID": "{pluginID}", "links": { "preview": { "href": "/content/{pluginID}/{menuItemID}", "method": "GET" } }}The path points to the plugin’s default menu item. If the plugin isn’t in the menu, the response contains no preview link and you can’t create a deep link to it. As admins can change the menu, cache the path only for a short time.
Custom URL
To create the custom URL for deep linking, you need to append the main URL with the additional path to the content to which you want to direct users.
Use the following scheme to add the custom URL: https://mycompany.com/content/{pluginID}/{menuItemID}/{deeplinking}
For example, if the path is /custom/page, this path needs to be appended to the main URL. The resulting URL will look like this:
https://mycompany.com/content/{pluginID}/{menuItemID}/custom/page
Additionally, you can also add query parameters to the main URL. These parameters will be appended to already existing parameters in your custom plugin URL.
For example, https://mycompany.com/content/{pluginID}/{menuItemID}/content/page?utm_source=”app”
When users access the custom URL, the path is interpreted by the Staffbase platform and opens the specific page. What happens when users reload the page depends on the web client:
- In the new web client, the custom URL stays in the address bar. A reload opens the same page in the plugin again.
- In the classic web client, the appended part in the URL disappears once the page opens, leaving only the main URL visible. A reload displays the default plugin page.
Share deep links
Users often share a link outside of the app, for example in an email or a chat tool, and open it on their phone. A custom URL then opens the web app in the phone browser.
For links that users share, add /openlink in front of the path:
https://mycompany.com/openlink/content/{pluginID}/{menuItemID}/{deeplinking}
- In a phone browser, the link opens the native Staffbase app at the plugin page. If the app isn’t installed, users can download it or continue in the web version. After installing the app, users need to open the link again.
- In a desktop browser, the link redirects to the custom URL.
If users are signed in, the path and the query parameters reach your plugin in all cases.
For how /openlink works in general, what users see when they aren’t signed in, and the /openlink paths of other app content, see Linking to Content Within the App via Deeplink.
Only use /openlink for links that users share. For links within the app, for example in a widget or a news post, use the custom URL without /openlink. Otherwise, users in a phone browser see the page that asks them to open the app with every click.
In the native app, you can open the device’s share dialog with the link. Use openNativeShareDialog from the Plugins Client SDK.
To let users copy the link in a web browser, your plugin needs clipboard write access. It’s off by default. To enable it for your plugin, contact Staffbase Support. Reading from the clipboard isn’t available.