I'm developing a modal/popup system for my users to embed in their sites, along the lines of what KissInsights and Hello Bar (example here and here) do.

What is the best practice for architecting services like this? It looks like users embed a bit of JS but that code then inserts additional script tag.

I'm wondering how it municates with the web service to get the user's content, etc.

TIA

I'm developing a modal/popup system for my users to embed in their sites, along the lines of what KissInsights and Hello Bar (example here and here) do.

What is the best practice for architecting services like this? It looks like users embed a bit of JS but that code then inserts additional script tag.

I'm wondering how it municates with the web service to get the user's content, etc.

TIA

• javascript
• jquery
• modal-dialog

4 Answers 4

You're right that usually it's simply a script that the customer embeds on their website. However, what es after that is a bit more plicated 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 munication)

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/blog/cross-window-messaging/

For cross-domain munication, see http://softwareas./cross-domain-munication-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 plicated 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.

Best practice is to put as little code as possible into your code snippet, so you don't ever have to ask the users to update their code. For instance:

<script type="text/javascript" src="http://your.site./somecode.js"></script>

Works fine if the author will embed it inside their page. Otherwise, if you need a bookmarklet, you can use this code to load your script on any page:

  javascript:(function(){
    var e=document.createElement('script');
    e.setAttribute('language','javascript');
    e.setAttribute('src','http://your.site./somecode.js');
    document.head.appendChild(e);
  })();

Now all your code will live at the above referenced URI, and whenever their page is loaded, a fresh copy of your code will be downloaded and executed. (not taking caching settings into account)

From that script, just make sure that you don't clobber namespaces, and check if a library exists before loading another. Use the safe jQuery object instead of $ if you are using that. And if you want to load more external content (like jQuery, UI stuff, etc.) use the onload handler to detect when they are fully loaded. For example:

function jsLoad(loc, callback){
  var e=document.createElement('script');
  e.setAttribute('language','javascript');
  e.setAttribute('src',loc);
  if (callback) e.onload = callback;
  document.head.appendChild(e);
}

Then you can simply call this function to load any js file, and execute a callback function.

jsLoad('http://link.to/some.js', function(){
  // do some stuff
});

Now, a tricky way to municate with your domain to retrieve data is to use javascript as the transport. For instance:

jsLoad('http://link.to/someother.js?data=xy&callback=getSome', function(){
  var yourData = getSome();
});

Your server will have to dynamically process that route, and return some javascript that has a "getSome" function that does what you want it to. For instance:

function getSome(){
  return {'some':'data','more':'data'};
}

That will pretty effectively allow you to municate with your server and process data from anywhere your server can get it.

You can serve a dynamically generated (use for example PHP or Ruby on Rails) to generate this file on each request) JS file from your server that is imported from the customers web site like this:

<script type="text/javascript" src="//www.yourserver./dynamic.js"></script>

Then you need to provide a way for your customer to decide what they want the modal/popup to contain (e.g. text, graphics, links etc.). Either you create a simple CMS or you do it manually for each customer.

Your server can see where each request for the JS file is ing from and provide different JS code based on that. The JS code can for example insert HTML code into your customers web site that creates a bar at the top with some text and a link.

If you want to access your customers visitors info you probably need to either read it from the HTML code, make your customers provide the information you want in a specific way or figure out a different way to access it from each customers web server.