Linking to AdButler from External Sites
This guide will teach you how to add links on your own website or application that open AdButler pages without asking the user to sign in again. You will learn:
- Why direct links to AdButler can land on the sign-in screen.
- How to format a link that preserves the user's AdButler session.
- What happens when the user is not signed in.
Why direct links lose the sign-in
AdButler's sign-in cookie is marked strict by the browser to protect against cross-site request forgery. When a user clicks a plain link such as https://admin.adbutler.com/campaigns from another website, the browser does not send the sign-in cookie on that first request. AdButler treats the visitor as
signed-out and shows the sign-in screen, even when the user is still signed in on another tab.
The handoff URL format
To carry the user's session into AdButler from an external site, point your link at the handoff page and include the AdButler destination as a to query parameter.
https://admin.adbutler.com/handoff.spark?to=
The <path> is everything that appears after admin.adbutler.com in the AdButler URL, starting with a forward slash.
When the link is clicked, a brief Opening AdButler page appears and then forwards the user to the destination with their AdButler session intact.
Finding the destination path
To find the path for any AdButler page, sign in to AdButler, navigate to the page you want to link to, and copy the URL from your browser's address bar. Keep the forward slash and everything after it. For example:
- AdButler URL: https://admin.adbutler.com/campaigns/overview
- Destination path: /campaigns/overview
Examples
Linking to a specific AdButler page with a path of /campaigns/overview:
https://admin.adbutler.com/handoff.spark?to=/campaigns/overview
Linking to a page whose path contains a query string or special characters. URL-encode the to value so it is read correctly. For a path of /reports?productID=123:
https://admin.adbutler.com/handoff.spark?to=%2Freports%3FproductID%3D123
Most programming languages include a helper to handle the encoding. In JavaScript:
javascript
const destination = '/reports?productID=123';
const link = 'https://admin.adbutler.com/handoff.spark?to=' + encodeURIComponent(destination);
When the user is not signed in
If the user does not have an active AdButler session when they click the handoff link, the handoff page forwards them to the AdButler sign-in screen. After they sign in, they are returned to the page that was originally requested.
Supported destinations
The to parameter must be a path on admin.adbutler.com. Absolute URLs, protocol-relative URLs, and malformed paths are ignored for security reasons. When AdButler cannot use the value in to, the user is sent to the AdButler home page instead. This protects your users from open-redirect attacks carried by manipulated links.
