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.

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.

The non-embedded version of the Compass Customer Portal is found at app.guidecx.com/auth/customer-login/sso

To embed that experience, we merely need to wrap that in an iframe tag like this:

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.

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, you can optionally provide a page parameter if you want the embedded portal to deep link to a specific tab like notes or attachments. If left off, it will assume the default of the today page.

You will know the user email address by virtue of that user logging in to your host system. They you dynamically inject that simple part as the first param.
​
Then input that same email as the primarily property in the API request to GUIDEcx. The system will respond with all possible project IDs (there will just be one most of the time) and the token. Finally you can build the full source URL for the iframe.

​
​https://app.guidecx.com/auth/customer-login/sso?token=TOKEN&projectId=PROJECTID&page=today&email=CUSTOMEREMAIL

For a more detailed technical explanation, check out this example.

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.

We have already applied this whitelist to our CSP, but only for the Compass pages.

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:

​

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.