Summary
Invite Customer Users to Compass View of Project
When you invite external customer users as external team members on a project, make sure to set the project view to "Compass View". Customer users will then default to the simplified portal. No other view is compatible with embedding at this time.
Link to the Portal from Your Navigation Menus
Your sites, systems, and software already include many navigation items like "Home", "User Profiles", and other settings. Now all you need to do is add a new link for a page like "Onboarding" or "Implementation" in that same navigation menu so people can find this new page easily.
Inject the Portal Code in Your Host Page
The non-embedded version of the Compass Customer Portal is found at https://app.guidecx.com/customer/today/[ProjectID].
To embed that experience, we merely need to wrap that in an iframe tag like this:
<iframe
src="https://app.guidecx.com/customer/today/YOUR PROJECT ID HERE"
width="100%"
height="800"
marginheight="0"
marginwidth="0"
frameborder="0"
title="Onboarding Portal">
</iframe>
The project ID will have many characters separated by 4 dashes. That project ID can be injected based on the API step you will make along with the customer access token in the next section below. Even though most customers are only invited to a single project, this ID is important to maintain context.
Non-embedded Compass views show the GUIDEcx navigation menus on the left with project selection in case a customer has been invited to multiple projects.
However, the embedded onboarding portal does not show any extra navigation on the left that might interfere or distract from the design and usability of your host page. That means project selection must be applied by you as part of the customer access token parameters appended to the iframe.
Append Access Token & Project ID as Parameters in Iframe
For each load of the embedded onboarding portal's iframe in your host page, you will need to make an API request to GUIDEcx in the customer token endpoint.
GUIDEcx will then reply with a token for that user and all the eligible project IDs that customer has been invited to.
You can then apply the project ID to the placeholder in the example iframe above. Then append the customer's access token as a parameter at the end. For example:
https://app.guidecx.com/customer/today/YOUR PROJECT ID?token=YOUR TOKEN
Whitelist GUIDEcx Domain as Eligible Embedded Content
CSP (Content security policies) protect users from click-jacking. This means you trust what GUIDEcx shows in the iframe and we trust your domain to embed our content. This trusted whitelisting is done through frame ancestor and source settings.
FRAME ANCESTORS
We have already applied this whitelist to our CSP, but only for the Compass pages.
FRAME SRC
You still need to apply a whitelist update to your CSP as clarified in this documentation. This process will depend on the technology used to build your site or software, but here is an example of where to change CSP headers if you use something like next.js.
Until then, this error message will block embedded access:
Point Email Links to Your Host Page
FAQ
Q. Which type of project view can be embedded?
A. The simplified Compass portal for customers
Q. Can the full project view also be embedded?
A. No. That is being considered for the distant future, but is a lower priority for now.
Q. I configured everything as stated in this help article, but why is my customer still blocked from accessing the embedded onboarding portal?
A. This is rare but can happen when they are a customer of multiple GUIDEcx providers, both a provider and a customer, or both a customer and a third party.
Q. Why don't I see any of these embed options?
A. This is included in the advanced tier but can be activated for any tier for an extra fee.