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 page (Requestor) 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 Requestor 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:

Requestor
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 Requestor 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 Requestor page, their browser calls Embed. Embed runs the test you specify and directs the user's browser to your Response page.

Requestor

The Requestor 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/perl/live/Embed.pl">
  <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="eMailAddress:ConfidenceFactor:/CheckTLS/MX/@exchange" />
  <input name="RETURN_URL" type="hidden" value="http://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, Score, 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 Requestor 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 Requestor 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.