Sending parameters in a query string to external domains
Learn how to securely send a user token through a query string.
Written by Jean Kemp
Updated at January 15th, 2025
Table of Contents
Introduction
Pugpig Bolt provides the ability to pass items on the query string to your site to help improve these experiences and allow you to vary elements on your site based on whether or not a user is coming from the app. We also pass this information through to iframes.
Persisting the query params
Note that the query string is only injected when the app initially loads your configured external website or your site page in a webview. You are responsible for persisting any values (e.g. via a cookie) if the user navigates onwards.
Trusted Domains
In order not to pass sensitive information to the wrong place, we will configure this on our side to only send the information to trusted domains. In most cases, this will be domain of your website, but we can include others if desired.
The information will be added to the query string in the following cases:
- Any external links out from the app content
- Any embedded URLs in the settings pages
- Any embedded URLs in the tab bar
Standard Values
We provide a default set of values on the query string. These are described below. However, if you wish us to send custom values, get in touch with our support team. Note that these values are sent on ALL links - we cannot provide different values on different URLs.
User Token
We usually send the user token as the token parameter - for example http://www.acme.com/?token=123412345
The token is the same token we receive from the login flow.
Development Needed
You will need to implement the logic on your site to look for this token, and log in the user accordingly if the token is valid. Note that the user needs to be properly logged into your site so that if they follow any internal links within the webview, they remain logged in.
If you are a Piano user, we can provide sample code to assist with this. Please ask our support team.
User Information
We can send any other information we receive from the user if needed (for example, the company they are from)
Indication that we are from the app
It is often useful for your site to know that that link or embed is coming from the app. For this, we pass a parameter by default called from_app - for example http://www.acme.com/?token=123412345&from_app=1
Many of our clients will use this parameter to hide any header, footer or navigation and only show the content from the web site when embedded in the app.
Dark mode
It can be quite an uncomfortable experience if a user taps on a link that takes them from the app to the website, if the app is in dark mode and the website flashes a bright white screen. Our recommended approach for respecting dark mode when your website is accessed via the app (e.g. in webviews) is to detect it via CSS media queries. However we do also support sending this via a query parameter if you are unable to implement the media queries on your site.
This will come through as one of:
https://www.acme.com/?darkmode=Dark
https://www.acme.com/?darkmode=Light
https://www.acme.com/?darkmode=SystemFor an example of implementation, please refer to this link. By appending the appropriate dark mode query string, as demonstrated above, you can observe the desired behaviour when the application implements the query string.
To enable auto-login for their Bolt Web Reader or Slim Storefront when users are already logged into their site, they should follow the instructions in this document: Auto-Login Specification for Pugpig Bolt Web Reader.