How do JavaScript-based modal/popup services like KissInsights and Hello Bar work?

You're right that usually it's simply a script that the customer embeds on their website. However, what comes after that is a bit more complicated matter.

1. Embed a script

The first step as said is to have a script on the target page.

Essentially this script is just a piece of JavaScript code. It's pretty similar to what you'd have on your own page.

This script should generate the content on the customer's page that you wish to display.

However, there are some things you need to take into account:

• You can't use any libraries (or if you do, be very careful what you use): These may conflict with what is already on the page, and break the customer's site. You don't want to do that.
• Never override anything, as overriding may break the customer's site: This includes event listeners, native object properties, whatever. For example, always use addEventListener or addEvent with events, because these allow you to have multiple listeners
• You can't trust any styles: All styles of HTML elements you create must be inlined, because the customer's website may have its own CSS styling for them.
• You can't add any CSS rules of your own: These may again break the customer's site.

These rules apply to any script or content you run directly on the customer site. If you create an iframe and display your content there, you can ignore these rules in any content that is inside the frame.

2. Process script on your server

Your embeddable script should usually be generated by a script on your server. This allows you to include logic such as choosing what to display based on parameters, or data from your application's database.

This can be written in any language you like.

Typically your script URL should include some kind of an identifier so that you know what to display. For example, you can use the ID to tell which customer's site it is or other things like that.

If your application requires users to log in, you can process this just like normal. The fact the server-side script is being called by the other website makes no difference.

Communication between the embedded script and your server or frames

There are a few tricks to this as well.

As you may know, XMLHttpRequest does not work across different domains, so you can't use that.

The simplest way to send data over from the other site would be to use an iframe and have the user submit a form inside the iframe (or run an XMLHttpRequest inside the frame, since the iframe's content resides on your own server so there is no cross domain communication)

If your embedded script displays content in an iframe dialog, you may need to be able to tell the script embedded on the customer site when to close the iframe. This can be achieved for example by using window.postMessage

For postMessage, see http://ejohn.org/blog/cross-window-messaging/

For cross-domain communication, see http://softwareas.com/cross-domain-communication-with-iframes

You could take a look here - it's an example of an API created using my JsApiToolkit, a framework for allowing service providers to easily create and distribute Facebook Connect-like tools to third-party sites.

The library is built on top of easyXDM for Cross Domain Messaging, and facilitates interaction via modal dialogs or via popups.

The code and the readme should be sufficient to explain how things fit together (it's really not too complicated once you abstract away things like the XDM).

About the embedding itself; you can do this directly, but most services use a 'bootstrapping' script that can easily be updated to point to the real files - this small file could be served with a cache pragma that would ensure that it was not cached for too long, while the injected files could be served as long living files.

This way you only incur the overhead of re-downloading the bootstrapper instead of the entire set of scripts.