Embed API

Embed lets you put our tests on your own web pages. This is different than CheckTLS web service (API), which lets your data processing systems use our services. Embed lets your users interact with our tests on your web site or intranet. Web services lets your computers interact with our tests with no user involvement.

Embed requires a Corporate Subscription, however it is available for testing and proof-of-concept without a subscription. Without a subscription testing is limited to the single address "test@checkts.com".

Make CheckTLS Test To: (Receiver) Test Your Own

This document describes how to put our most popular test (Test To:) on your own web pages. In a similar manner, you can make any CheckTLS web service enabled test look like it is your own test, and put it on your own web pages: Click the image below to open an example in a new tab. Notice there are no headings, titles, or anything else that ties this back to CheckTLS. You can right click on that page to see the HTML source code used to create it.
picture of sample web page

What is Embed?

Embed is combination of a CheckTLS web service (API) and some HTML code that you add to your web page(s). It is not run by a person from their browser. Instead, as your users interact with your web page, your web page asks CheckTLS to run the test and send the results back. Your page takes the results and formats them as your own.

What Embed Does

Your user sees an input box on a Request page of your web site and a CheckTLS button. When they enter something and click the button, they get a new page (Response) on your web site with their answer. They never see a CheckTLS page.

Behind the scenes, when the user submits the form on your Request page, their browser calls our Embed web service front-end. Embed runs the test you specified with the input from the user. It parses the output and picks out the result fields you specified. Finally it instructs the user's browser to "submit" the selected results back to your Response page. Your Response page uses JavaScript to load the results into a new page for the user.

How To Use Embed

Embed has three parts:

Request
A web page on your site where your users fill in data they want you to test for them.
Embed
The front-end to our web services that your Request page calls to run the test and return the results to you.
Response
A web page on your site where you display our results to your users.

When your user submits the form on your Request page, their browser calls Embed. Embed runs the test you specify and directs the user's browser to your Response page.

Request

The Request is a web page on your site. You completely control the content and look and feel of this page. The page must have the HTML <form> element below:

<head></head>
<body>

<form method="post" action="https://www.checktls.com/Embed">
  <input name="AUTH" type="hidden" value="
lm3KVY+FI3TGdolb1mLkapuUohBNcI0A9Bxqu4/DY2xXMyoXFm5R1aEMhVtUAPpG6nXIOAknnARu
hdB6kbQuOEBGpMOS2seoobs8GQvnx9CATVo+EPpdUNVdnLobRPuxv5EPFXzRGgu7YywlHCUuzhnr
xpsylQ+GC572a8/2lpugmeiC5NCyzbh4Wev7+sRHXZ3R9HLelAQtk8gGQTdwl3FFwrTrV4tZh5us
GZjFOh+osUIh4KrB4Sv7P6/jNgUGEbNQ7NEBGPuisdEPtahgLKE1xJsuUzQjFdGl7F2H/KwdbAbX
0zPm9RHTSq0/G/4DTqhdAwtM29We36AnZ1fHKw==
" />
  <input name="CHECKTLS_URL" type="hidden" value="/TestReceiver" />
  <input name="a_EMAIL" type="text" value="test@checktls.com" />
  <input name="a_LEVEL" type="hidden" value="XML_DETAIL" />
  <input name="XF" type="hidden" value="/CheckTLS/eMailAddress:/CheckTLS/ConfidenceFactor:/CheckTLS/MX/@exchange" />
  <input name="RETURN_URL" type="hidden" value="https://www.checktls.com/embed_response.html" />
  <button name="ACTION" type="submit" value="CheckTLS">Check It</button>
</form>

</body>

Without your look and feel, the above form looks like:

You use the <input> lines to tell Embed what to do. The <form> and <button> lines have to be exactly as shown above. Most of the <input>s (in this example all but one) are hidden. You use them to specify the test on our site you want to run, some of the parameters for that test, and what parts of the test results you want us to send back to you.

The <input> lines are:

AUTH
A custom authorization code that we generate for you. Click here to get yours. It keeps someone from stealing your CUSTOMERCODE and CUSTOMERPASS by viewing your HTML source code. If you omit this input you can still test the one address "test@checktls.com" (i.e. <input name="a_EMAIL" type="text" value="test@checktls.com" />.
CHECKTLS_URL
The URL of our test you want to run for the user. It must be web service enabled and must return XML. See the documentation on the test you want to run for information on how to make it output XML.
a_XXXXXX
These are parameters for the test you want to run. Each "a_" input is a parameter from the specific web service test on our site. For example the above <form> runs Test To: with EMAIL=test@checktls.com and LEVEL=XML_DETAIL.
XF
XPath path expressions to select the XML nodes whose data you want to extract from the test output. Separate multiple expressions with a colon (":"). For example, the above <form> returns the Target, Confidence Factor℠, and MX Hosts (which could be an array if there is more than one DNS MX record).
RETURN_URL
The URL of your Response page, which is how we direct the user back to you.

Response

The web page on your site where you display our results to your users. Your Response page must have this JavaScript, and something like the HTML below it:

<head></head>
<body>

<script type="text/javascript">
function getQueryParams(qs) {
	qs = qs.split('+').join(' ');
	var params = {}, tokens, re = /[?&]?([^=]+)=([^&]*)/g;
	while (tokens = re.exec(qs)) {
		params[decodeURIComponent(tokens[1])] = decodeURIComponent(tokens[2]);
	}
	return params;
}
var query = getQueryParams(document.location.search);
window.history.replaceState( null, null, document.location.origin+document.location.pathname );
</script>

<p>
Address <script>document.write(query.eMailAddress);</script>:
<script>
	if( query.ConfidenceFactor >= 100 ) {
		document.write( '<b>Yes!</b>  This recipient uses TLS.' );
	} else {
		document.write( '<b>No!</b>  This recipient does not use TLS.' );
	}
</script>
(score:<script>document.write(query.ConfidenceFactor);</script>)
</p>

</body>

Without your look and feel, the above output looks like:

Address test@checktls.com: Yes! This recipient uses TLS (score:100)

When your user submits the form on your Request page, their browser calls Embed. Embed runs the CHECKTLS_URL using the a_XXXXXX parameters, parses the output, which must be XML, and picks out the nodes you specify in XF. Then it instructs the user's browser to "submit" the selected data back to your Response page where the JavaScript makes it available to you.

About the JavaScript

The JavaScript for your Response page reads the XF field names and values from Embed and makes them available as checktls.[fieldname]. You do have to access these from JavaScript as in the example above.

Embed Examples

Click HERE to open a working example of a Request page. If you click the button on that page to run the test, the result page is a working example of a Response page. This is the exact source code as displayed above.

Development and Debugging

You can build up to a fully functional Embed by following these steps:

  • call the webservice
  • show the return URL internally
  • show and run the test URL
  • show the return URL externally
  • try our return URL manually
  • try our return URL internally
  • try our return URL externally
  • try your return URL manually
  • try your return URL internally
  • try your return URL externally
  • add authentication

Call the WebService
Put this exact HTML on a Request webpage on your site:
<head></head>
<body>

<form method="post" action="https://www.checktls.com/Embed">
  <input name="AUTH" type="hidden" value="
lm3KVY+FI3TGdolb1mLkapuUohBNcI0A9Bxqu4/DY2xXMyoXFm5R1aEMhVtUAPpG6nXIOAknnARu
hdB6kbQuOEBGpMOS2seoobs8GQvnx9CATVo+EPpdUNVdnLobRPuxv5EPFXzRGgu7YywlHCUuzhnr
xpsylQ+GC572a8/2lpugmeiC5NCyzbh4Wev7+sRHXZ3R9HLelAQtk8gGQTdwl3FFwrTrV4tZh5us
GZjFOh+osUIh4KrB4Sv7P6/jNgUGEbNQ7NEBGPuisdEPtahgLKE1xJsuUzQjFdGl7F2H/KwdbAbX
0zPm9RHTSq0/G/4DTqhdAwtM29We36AnZ1fHKw==
" />
  <input name="CHECKTLS_URL" type="hidden" value="/TestReceiver" />
  <input name="a_EMAIL" type="text" value="test@checktls.com" readonly="readonly"/>
  <input name="a_LEVEL" type="hidden" value="XML_DETAIL" />
  <input name="XF" type="hidden" value="eMailAddress:ConfidenceFactor:/CheckTLS/MX/@exchange" />
  <input name="RETURN_URL" type="hidden" value="https://www.checktls.com/embed_response.html" />
  <button name="ACTION" type="submit" value="ShowEntries">Show Entries</button>
  <button name="ACTION" type="submit" value="ShowRedirect">Show Redirect</button>
  <button name="ACTION" type="submit" value="CheckTLS">Run It</button>
</form>

</body>
Browse to the Request page on your site and click on the Show Entries button. You should be taken to the Embed page with all the fields filled in like this: Embed screen

If you are not taken to the Embed page or the page does not look exactly as pictured above, then either your Request page HTML is wrong, your webserver is not "serving" the HTML correctly, or your browser will not allow a cross-domain post (which should give you an error message). You can use the Contact Us form to send us the URL of the page with the Request HTML and we may be able to help.

Show the Return URL Internally

From the Embed page you just got (not from the Request page on your site), click the Show Redirect button. Embed will run TestReceiver on "test@checktls.com", parse the results, and embed them into your Return_URL. This URL is visible at the bottom of the page, both in human and machine readable formats. If you do not get these URLs, then the HTML you entered on your Request webpage is not correct.

Show and Run the Test URL

Make sure you are running the test you think you are running with the parameters you think you are supplying. From the Embed page you just got (not from the Request page on your site), click the Show Test URL button. Embed will display the URL that your entries will execute. Examine the URL to be sure it is doing what you expect. Then use the Show Result button to run this URL. It will open a new window with the Result XML. If you do not get the currect XML then you have an error in the CheckTLS_URL or ARGS fields.

Show the Return URL Externally

Browse to the Request page on your site and click on the Show Redirect button. You should be taken to the same page as the Internal test above with the exact same fields and URLs.

Note the Referer IP given just above the URLs in the Test Results section. This IP must be in the range you provide when creating your AUTH.

Try Our Return URL Manually

From the Embed page you just got, Copy and paste the entire machine readable URL into a new window of your browser. You should be taken to the Response page on our web site: Embed runit

Try Our Return URL Internally

From the same Show the Return URL window you copied the URL from, click the Run It button. A new window should open with the same Response page on our site.

Try Our Return URL Externally

Browse to the Request page on your site and click the Run It button. You should be taken to the same Response page on our site.

Try Your Return URL Manually

Put this exact HTML on a new Response webpage on your site:

<head></head>
<body>

<script type="text/javascript">
function getQueryParams(qs) {
	qs = qs.split('+').join(' ');
	var params = {}, tokens, re = /[?&]?([^=]+)=([^&]*)/g;
	while (tokens = re.exec(qs)) {
		params[decodeURIComponent(tokens[1])] = decodeURIComponent(tokens[2]);
	}
	return params;
}
var query = getQueryParams(document.location.search);
window.history.replaceState( null, null, document.location.origin+document.location.pathname );
</script>

<p>
Address <script>document.write(query.eMailAddress);</script>:
<script>
	if( query.ConfidenceFactor >= 100 ) {
		document.write( '<b>Yes!</b>  This recipient uses TLS.' );
	} else {
		document.write( '<b>No!</b>  This recipient does not use TLS.' );
	}
</script>
(score:<script>document.write(query.ConfidenceFactor);</script>)
</p>

</body>
From the same Show the Return URL window, change the Return_URL field to be the URL of this Response page on your site. Click on the Show Redirect button. Embed will display the new redirect URL in human and machine readable formats.

Copy and paste the entire machine readable URL into a new window of your browser. You should be taken to the Response page on your web site that looks just like the image above from our site. If you do not get your Response page then your Response page has an error.

Try Your Return URL Internally

From the same Show the Return URL window you copied the URL from, click on the Run It button. A new window should open with the same Response page from your site. If it does not, contact us and let us know.

Try Your Return URL Externally

Browse to the Request page on your site and click the Run It button. You should be taken to the same Response page from your site.

Add Authentication

The most common problems when using Embed are with the AUTH parameter. All of the above steps target "test@checktls.com", which we allow with any AUTH, or even no AUTH. Once you have it working with the target "test@checktls.com", then generate a valid AUTH using your IP range and account.

Paste this AUTH in place of the AUTH lines in the HTML on your Request page. Remove the readonly="yes" element from the a_EMAIL field (third line after the end of the AUTH string).

Browse to the Request page on your site, leave the target as "test@checktls.com", and click the Run It button. You should be taken to the same Response page from your site.

Browse back to the Request page on your site, change the target to something else, and click the Run It button. You should be taken to your Response page with the results of the new target. If not, your AUTH parameter is either wrong or was pasted into the HML incorrectly.

Next Steps

The above simple Request/Response web pages run our TestReceiver on a target that your users enter. Your web designer(s) can embed (thus the name!) the HTML into real pages on your site, so our test has your look and feel. How to do that is not something we can help with.

The above simple Request/Response retrieves one bit of information (the Confidence Factor℠) about the target. You can retrieve any information from TestReceiver's output, not just the Confidence Factor℠. See the info on XF in Request above.

For example you could let your users know if an address supports TLS 1.3 by returning the TLS version of the first MX. Use XF=/CheckTLS/MX[1]/SSL/SSLVersion and compare it to "TLSv1_3".

You can embed other CheckTLS tests in your site.