Embedding CTDL: Step By Step
The following draft instructions are for your credentialing organization's webmaster or other technical staff who have access to update the website's html. For more information visit the Embedding CTDL page.
Follow these instructions to embed your published credential information published to the Credential Registry as structure data for search engine discovery into your websites html. Note:
- Embedding the CTDL metadata will not change the presentation of any content to users.
- This data is only visible to search engines that need structured metadata to populate their product interfaces.
An example of structured data in use is how Google uses hotel information to populate a hotel search that uses structured data to show comparable information and links directly to make a reservation. The goal is for Google and other search engines to begin using structured metadata about credentials to provide similar interfaces that improve search and discovery as well as comparability and directly linking to the web pages about credentials.
Important Tip: As credentials are published to the Registry, an automatic notification and email goes to the contacts identified with the Account System at the end of the day. Be sure everyone who needs to know about updates to your information in the Registry has an account is setup to receive the account notification and email.
If your website is data-driven (i.e., templates filled in with data from a database), skip to the Embeddding Step below.
Otherwise, please complete through step Steps 1 through 7. At any point, please contact the Credential Engine technical team for answers to your questions and/or troubleshooting. We'll reply by email and offer to meet in a live webinar if necessary.
Step 1: Log in to Your Credential Engine Account
- Click "Login".
- If you forgot your password, click "Forgot Password"
Step 2: Navigate to the Download Data Page
After logging into the Accounts System, from "My Dashboard", select "Download Data." Optionally, after logging in, the same page for downloading data that is described below is also available from the Credential Registry Publisher's Summary Page.
The Download Data page shows counts of the information you have saved in the Credential Engine Publisher. The Credentials counted in the "Published" column will be included with the spreadsheet that is downloaded to embed CTDL on your website. The example below shows a credentialing organization has published 94 credentials to the Credential Registry. The downloaded information will therefore include these 94 credentials.
Multiple download options are available on this page. Scroll down the page to option for Embeddable Data and click Download Credential Embeddable Data.
Step 3: Download the Credential Embeddable Data Spreadsheet
Your downloaded spreadsheet includes the columns listed below. All by one of these columns are informationation to help you identify each credential and see/understand the metadata to be embedded in your website. The last column is a script tag to copy/paste into your website's html.
- The unique identifier assigned to each credential in the Credential Registry. This identifier is important; it is used by the script tag to keep the information you'll embed on your website synced up to the metadata about the credential in the Registry.
- The name of each credential published to the Credential Registry.
- Credential Type
- The type of credential. This will be one of the CTDL credential types.
- Credential URL
- The webpage for the credential. This will come from the data that was published for that credential.
- Credential Finder Link
- Direct link to the detail page about each credential published to the Registry. The Credential Finder is a website for showing all of the information in the Credential Registry. To see the information the metadata includes follow the link to the detail page. The metadata you embed on your webpage will not display to users on your site. It will include the information you see on this page but formatted for search engines.
- Credential Registry Direct CTDL Link
- URI for the metadata about the credential in the Registry. A URI can be pasted into a browser to see the machine actionable data rather than a web page. The data in the Registry is Linked Open Data. This means it's stored to be human and machine readable using JSON LD encoding. The metadata is based on the Credential Transparency Description Language (CTDL) and available for applications to consume as machine actionable data. Learn more about the CTDL.
- Hybrid CTDL-EOCred Direct Link
- URI to the metadata stored in the Registry about the credential. The data in the Registry about your credential is also automatically output into the format preferred by search engines. This format requires using CTDL terms mapped to the Educational and Occupational Credential class that is encoded as JSON LD.
- Pre-Formatted CTDL-EOCred Script Tag
- A script tag to copy/paste into the websites html to embed the Hybrid CTDL-EOCred metadata web pages. Follow the directions below to use this script tag to generate the hybrid CTDL-EOCred metadata preferred by search engines.
Step 4: Preview the Generated Data
To see what all of the metadata generated by the script tag looks like, you use our Embedding Tester. When the data loads, the page will display helpful information and the data itself.
Copy and paste a CTID, found in the CTID column of the downloaded spreadsheet, into the entry box and click "Load Data." This will generate the same metadata you'll embed on your website as shown with the sample below.
Step 5: Embed the Script Tags
Embed the script tags in the html of the credential information web site.
If your website's pages are generated dynamically (e.g., database/template-driven), follow the directions below:
- Add the following template to your page:
- Add code to replace [CTID] in the template above with the CTID for that page's credential.
If your website uses static web pages that are manually created and edited, follow the directions below:
- Copy and paste the value from the Pre-Formatted CTDL-EOCred Script Tag column of the spreadsheet you downloaded exactly as it appears into the HTML for the page for that spreadsheet row's credential.
Below is an example of what the script tag should look like:
Note that this script tag uses the "defer" and "async" attributes to prevent it from delaying any other scripts on your page from loading:
Once the script tag is on the page, it will:
- Automatically retrieve the EOCred data live from the Registry, meaning it will always pull the most recent version of the data.
- Automatically embed the EOCred JSON-LD into the web page's
<head>tag (the data is invisible to users).
- To do this, append
?onload=nameOfYourFunctionto the end of the script's src attribute.
- The function will be passed the CTID, the EOCred JSON-LD data, and a reference to the JSON-LD script tag that was embedded into the page.
Step 6: Use the Google Structured Data Testing Tool
Validate the metadata on your web page using the Google Structured Data Testing Tool.
- Copy and paste the URL to the web page where you embedded the script and click "RUN TEST"
- This tool will do an analysis of the metadata as structured data. You will see "1 ERROR". This is an expected error that we do not believe prevents the search engine from accessing and utilizing the CTDL metadata.
Step 7: Contact the Credential Engine Team
The team will answer your questions and troubleshoot issues via email and, if desired, live webinar.
When contacting the team, please include the URL(s) to the page(s) where the CTDL script was embedded on your site. The technical team will test this data to ensure it was correctly embedded.