Embedded Components

Overview

CredibleMind embedded components can be used to present CredibleMind features and content within a client’s existing site. Generally, embedded components can be installed on a variety of platforms.

The way this works, as described in detail below, is that you will need to add some Javascript into your page both in the header section and at the end of the body tag. You then place a <div> element in the page where you want the component to appear. The actual component to be loaded is identified either by a URL parameter appended to the parent page, or as a Javascript property. For example, if you have set up all the code and want to load a specific component, you add the component name to the URL of the calling page as a URL parameter.

To illustrate, if your site is called www.example.com and the page to embed the component on your site is https://www.example.com/company-demo/emotional-wellness, to load the CredibleMind topics component you add ?cm_page=topics to the URL to embed that component:

https://www.example.com/company-demo/emotional-wellness?cm_page=topics

This will then load the topics browser within the www.example.com site.

The Javascript uses the cm_page=[component] URL parameter to identify which component to load. The benefit of loading the component via a URL parameter is that it allows the page to be bookmarked and/or “deep linked,” so that if a user goes to the page it will load the correct component. Here is an example (opens in a new tab) of embedding our Topics component via a URL parameter, but please see the other examples later in this document.

Alternatively, the embedded component can be set as a property in the Javascript function as described in below. (A list of frequently used components is at the end of this document, but nearly any page on the CredibleMind site can be embedded.)

Step 1: Add the Javascript in the header

First, you need to add a reference to the script that's required for your application. For this, you'll need to insert a <script> element in the <head> section of your HTML document. The script URL is: https://widget.crediblemind.com/embed-dev.js.

Here's how you would add this to your HTML:

<head>
  ...
  <script src="https://widget.crediblemind.com/embed-dev.js"></script>
  ...
</head>

Remember to replace the ... with any other content that might be in your HTML head.

Step 2: Create a `<div>` element with id = 'cm-embed-container'

This <div> element is where the embedded component will be displayed on your web page. To create it, you'll add the following code in the <body> section of your HTML:

<body>
  ...
  <div id="cm-embed-container"></div>
  ...
</body>

The ... is again a placeholder for any other content that might be in your HTML body

Step 3: Insert a Javascript block with specific configuration

Now, you need to insert the JavaScript snippet below that serves to configure and then render your embedded component. You would typically place this script right before the closing </body> tag.

<script>
 	const containerId = 'cm-embed-container';
	CMEmbed.PageComponent({
		client: '{client identifier}',
		env: 'demo',
		parent: window.location,
		onRouteChange: route => {
			let page = window.location.pathname;
			if (route.length > 1) {
				page = '?cm_page=' + route;
			}
			history.replaceState(null, null, page);
			if (!route) window.location.reload();
			const embedContainer = document.getElementById(containerId);
 
            if (embedContainer) {
              const embedContainerPosition = embedContainer.getBoundingClientRect()
                .top;
              const scrollPosition =
                window.pageYOffset + embedContainerPosition;
              // Scroll to the target position
              window.scrollTo({
                top: scrollPosition,
                behavior: 'smooth',
              });
            }
		},
		setIframeHeight: height => {
			const min_height = 200;
			const final_height = height || min_height;
			const element = document.getElementById(containerId);
			if (element) {
				element.firstElementChild.setAttribute('style', 'height:' +  final_height + 'px');
			}
		},
        onModalOpen: () => {
          const topOffset = window.top.scrollY;
          const leftOffset = window.top.scrollX;
          return { top: topOffset, left: leftOffset };
        },
         onScrollTo: position => {
          window.scrollTo({
            top: position,
            behavior: 'smooth',
          });
        },
		// optional properties
		type: 'bare',
		components: ['topics'],
		styles: {
          backgroundColor: '#f7f7f7', // must be hexcode
        },
		controls: {
          hideHeader: true,
        },
 
  	}).render('#' + containerId);
</script>

Please see Properties Glossary of this document for more information on the above parameters. Normally all you need to change in the Javascript is the client identifier. For testing purposes you can use our demo client, 'benovo' as the client identifier. Remember you will need to change this before go-live. The component to embed is passed either in the URL, or you can set it in the Javascript. The Javascript above is standard for most implementations. Make sure to set the proper client identifier which you can obtain from your customer success manager or from a shared google sheet with all customer brands.

Step 4: Load the component you want

As mentioned above, there are two ways to set the component to load.

Set the “cm_page=[component]” URL parameter to control what CredibleMind content will be embedded on the page. Typically you have one container page (e.g. www.example.com/crediblemind) which contains the javascript and uses the cm_page= to allow the user to navigate the component and change to other components.
Alternatively, set the component to be loaded as a property in the Javascript. For example, to load the topics component you can change the components property in the script as follows:
```
components: ['topics'],
```
A quick test to see if the components are working correctly is to load https://yourdomain.com/yourcontainerpage?cm_page=topics — this should show a page like this (opens in a new tab).

Note: The URL parameter (cm_page=[component]) takes priority over the components property in the Javascript, so if both are set the component defined in the URL parameter has priority and will be displayed.

Here is a list of suggested components that can be embedded on your site using either of the two methods above, once the parent page has all of the Javascript and the HTML set up properly.

Note: At this time, it is not possible to load more than one component on a page; it is on our roadmap to enable this functionality in the future. If you want to allow a user to change which component is displayed, for example with a control on a page, you would need to reload the page with a new “cm_page=[component]” URL parameter.

Component	URL Parameter for parent page (?cm_page=...)	OR Javascript property
Full Topic List with Search	topics	components: ['topics']
All Assessments	assessments	components: ['assessments']
All Insights	blogs	components: ['blogs']
All News	news	components: ['news']
Any specific list	lists/[listName] — e.g. lists/picks-for-nature-and-the-outdoors. Note that lists have additional configuration options you can see in here	components: ['topics/[list name]'], e.g. ['lists/family-and-boundaries']
Any specific topic	topics/[topicName] — e.g. topics/anxiety, topics/depression	components: ['topics/[topicname]'], e.g. ['topics/anxiety']
Disaster Resources	landing/disaster-related-resources	components: ['landing/disaster-related-resources']

Step 5: Configure for production

Once you have embedded all the content you want and have everything working for the site there are some additional steps:

Notify your Customer Success person that you are ready to go live so they can help guide you through the process.
Change the javascript property "env" from "demo" to "production".
Change the javascript embed script name in the header from 'embed-dev.js' to 'embed.js'.
Provide your CredibleMind Customer Success person with the URL of your primary container page for CredibleMind content — we will then configure so if someone tries to go to a page on the crediblemind site directly, it will redirect to the container page with the proper cm_page= URL parameter so that users are not able to view the components non-embedded. (Note: this does not apply if you are using redirect="new_tab" which links to the standalone site rather than staying embedded).
Make sure you have the proper client identifiers setup. The “client identifier” in the javascript must be the client “brand” string (a unique identifier) as provided by CredibleMind. If you have multiple sites/clients you need to make sure the client identifier is set to the proper client. Your Customer Success manager can provide you with the correct brand for your site. If you have many sites your Customer Success manager will provide you with a document where you can find the correct client brand identifiers for all of your instances. The other properties do not need to be changed. If you are using the same code to dynamically serve a page to multiple clients, all you need to do is have the code insert the correct brand identifier into the Javascript before it is loaded by the browser.

React Example Lists