Web 2mee

The Website SDK
The SDK consists of a javascript file. You are recommended to link to the version on the 2mee CDN. This will allow you you remain up to date without having to check for updates. The SDK itself uses the [email protected] dialog package that to display the popup messages. 
The SDK itself is very simple. After loading the javascript, the SDK is initialised using in the 
Appear2mee.initWithID function using the Web ID that is generated in the settings section of an App in the 2mee platform.
Installation - Simple Site
For a single page website the full install is shown below. The script is loaded asynchronously to avoid delaying page loaded. SDK commands are then pushed onto a command layer and processed once the script has loaded.  The Appear2mee SDK is initialised with a  initWithID command which  requires an ID to associate the website with the messages that your organisation will post. Optionally you can add a setPosition  call to define where on the page a dialog will appear. The default is bottom-right. This code should be place in the <head></head>  section of the webpage. 
1
   <script src="https://exchange.cdnedge.bluemix.net/web/appear2mee-latest.js" async></script>
2
   <script>
3
    window.Appear2meeLayer = window.Appear2meeLayer || [];
4
    function appear2mee() { Appear2meeLayer.push(arguments);}
5
    
6
    appear2mee("initWithID","<Web ID From Exchange Or App>");
7
​
8
    /* 'top' | 'top-start' | 'top-end' | 'top-left' | 'top-right' | 'center' | 'center-start' | 'center-end' | 'center-left' | 'center-right' | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-left' | 'bottom-right' */
9
    appear2mee("setPosition","bottom-right");
10
    </script>
Copied!
For multiple page sites the same install is required on each page. Of course you should not include the SDK on pages that you do not want the messages to appear. 
Topics
The are two types of exchange scheduled popup messages, global messages and topic messages. Global messages are displayed by the SDK unless specifically requested not to. Topic messages are only displayed if that particularly topic has been requested using the receiveTopic command. A topic is just a string. For example, appear2mee("receiveTopics","homepage") would allow messages for the topic homepage to be received and played.  Multiple topics can be set using an array, appear2mee("receiveTopics", ["homepage", "contacts"])
However, rather than specify topics individually it is better to have them defined automatically using for example the page name.   Note for http://site.com/hierarchy/page/  page locations a different filter is needed  see the WordPress version below.
Topics can also be set on the exchange, and the exchange can also be used to decline topics generated by  by the webpage should be set once 
1
 <script>
2
  var learnQuickly = true;
3
  //  works for http://site.com/hierarchy/page.html --> gives topic page 
4
  var topic = window.location.pathname.split("/").pop().split(".")[0];
5
  appear2mee("receiveTopics",topic,learnQuickly);
6
 </script>
Copied!
The receiveTopics command not only registers the topic to be received by also communicates the topic request to the platform, so that the topic is added to the available topics. An optional Boolean learnQuickly can be added as a second argument to speed up the transmission of topic information to the platform. Without the learnQuickly option as true communication of topics is done lazily (within maybe 30 seconds of loading the page), which maybe too slow for the eager developer. 
Some pages or sections of your site might require no messages at all to be displayed, or only topic messages. The receiveOnlyTopics command will allow only topic messages to be displayed, eg.,  appear2mee("receiveOnlyTopics", "checkout"). To receive no messages at all the appear2mee("receiveOnlyTopics",null) can be used.
Inline Messages
Normally messages popup and block other activity. Inline messages are effectively a named videos place in an iframe . To use an inline message a HoloCapsule must be used. A HoloCapsule is a named message on the 2mee Platform. It has the advantage that the video can be replaced without changing the name. For example a "welcome" message can be replaced without changing the web site as the inline message displays the contents of the HoloCapsule. An inline message is placed in html using the code below. The Appear2mee SDK must also be include in the <head> section of the page. 
This code defines an iframe in which the message will be displayed. The this argument refers to the iframe (it is this iframe) and the last argument is the name of the HoloCapsule defined in the 2mee Platform. 
1
<iframe src="about:blank"
2
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange");'>
3
</iframe>
Copied!
An inline message can also be configured to have a background image, your logo perhaps. 
1
<iframe src="about:blank" 
2
style="background-image:url(Logo.png);background-repeat:no-repeat;background-size:contain;background-position:center center;"
3
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange");'>
4
</iframe>
Copied!
Event Messages
An event message is a blocking message that is normally in response to an event. For example to provide information with a button press. Again this type of message uses a HoloCapsule name to define which message is displayed.  Event messages can include an optional link to direct the users to a new page. 
1
<button onclick='appear2mee("eventMessage","myMessageNameFrom2meeExchange");'>
2
My Button
3
</button>
4
​
5
<button onclick='appear2mee("eventMessage","myMessageNameFrom2meeExchange","https://2mee.com);'>
6
My Button for message with link
7
</button>
Copied!
Page Messages
A  page message is a non blocking message that displays a HoloCapsule.  The message is displayed in fixed position (does not change position with scrolling) in the corner of the webpage.  These can be used as an alternative to event messages where the blocking of the page with a popup is not desirable. This type of message uses a HoloCapsule name to define which message is displayed.  Page messages can include an optional link to direct the users to a new page. 
1
// optional position "appearBottomRight" (default), "appearTopLeft", 
2
//                   "appearTopRight", "appearBottomLeft"
3
appear2mee("pageMessage", pageMessageName, "appearBottomLeft");
Copied!
Pausing Messages
There may be user actions that you do not wish to interrupt with a message. The SDK provides a method appear2mee setPause method, e.g., appear2mee("setPause",true), which will cause message delivery to be paused when true, and resume when false. This will require some customisation of your site to detect the activities you want to protect and detect when messages can restart. 
Web page message control
 In a simple site with a few messages control of message display can be left to the exchange. However in a more complex site it may be required to be more selective in the display of messages. 
Query Capsule keyValues
In the exchange a capsule message can be assigned a set of key value pairs. These can be queried using the appear2mee("messageKeyValues", pageMessageName, callback) function. This returns the keyValues (as an object) of the named capsule in a callback and the name of the message. If the message name does not exist the messageName will be null. Based on the keyValues further action can be taken. 
Note: The call is asynchronous, so multiple calls can come back in a different order than they are sent. Check the message name if you are using the same callback in each call to the function.  
1
var loginData = {
2
  "status": "pro"
3
}
4
var pageMessageName = window.location.pathname.split("/").pop().split(".")[0];
5
​
6
function callback(keyValues,messageName) {
7
  if(messageName == null) return; // did not exist
8
  console.log("message keyValues for " + messageName + ":", keyValues);
9
  var matchValue = keyValues[loginData.status]
10
  if (matchValue != null) {
11
    // optional position "appearBottomRight" (default), "appearTopLeft", "appearTopRight", "appearBottomLeft"
12
    appear2mee("pageMessage", messageName, "appearBottomLeft");
13
  }
14
}
15
appear2mee("messageKeyValues", pageMessageName, callback);
Copied!
Control popup messages
Normally popup messages just appear, based on exchange setting and controls. However if web page based fine control is required a function appear2mee("setShouldDisplayMessageFn", callback) can be used to screen messages before they are presented. The shouldDisplayMessageFn is called just before a new popup will be presented. 
The shouldDisplayMessageFn provides a set of KeyValue pairs associated with the message, if any and a list of topics associated with the message and a message identifier. The return value this function controls the display of the message. A negative value will stop the display of the message, and it will not be presented again. A value of zero will allow presentation as normal (immediately). A positive value will delay the message by the the positive value number of seconds. Normally that should be a reasonably large number of seconds as the shouldDisplayMessageFn will be called again to screen the display of the message.
1
var msgCount = 0
2
    
3
function callback2(keyValues, topics, msgId) {
4
  console.log("pull keyValues for:", keyValues);
5
  console.log("pull topics for :", topics);
6
  msgCount++;
7
  if (msgCount > 1) {
8
    if (keyValues["important"] != null) {
9
      return 60 * 60; // try in 1 hour
10
    } else {
11
      return -1; // refuse message (do not see again)
12
    }
13
  }
14
  return 0; // display message
15
}
16
​
17
appear2mee("setShouldDisplayMessageFn", callback2);
Copied!
Customise Backdrop
When a message appears in a "dialog" there is a backdrop which dims the container page. The default backdrop setting is rgba(0,0,0,0.2). That is black backdrop with an alpha of 0.2. Colors are defined 0-255 but alpha is 0 to 1.0.  This setting would normally defined after the initWithID in the header. 
1
appear2mee("setBackdrop","rgba(128,0,0,0.8)"); // dark red -- not recommended!   
Copied!
Customise Dismiss on Backdrop
When the message dialog, the dialog can be dismissing using the X button to the right of the dialog or by clicking on the page outside the dialog. The default is that clicking outside the dialog area will dismiss the dialog. However, especially if the backdrop is not visible it, it is possible to disable this method of dismissing the dialog be using the javascript command setClickOutsideDismiss with the argument false. Using the same command with argument true will restore the default behaviour. 
1
appear2mee("setClickOutsideDismiss",false); // now clicks outside dialog are ignored  
Copied!
WordPress Integration
2mee have a Beta WordPress Plugin available to add to your website using the WordPress store. You can find the plugin using this link https://wordpress.org/plugins/appear2me/​
The SDK can also be installed on WordPress as custom header javascript. There are a few methods of achieving this but the best simplest method is to use a plugin. The Insert Headers and Footers plugin can be used. If not already installed use the Plugins Add New button. 
Once installed you will find it has added an entry "Insert Headers and Footers" to Setting. 
In the "Scripts in Header" section add the code,
1
   <script src="https://exchange.cdnedge.bluemix.net/web/appear2mee-latest.js" async></script>
2
   <script>
3
    window.Appear2meeLayer = window.Appear2meeLayer || [];
4
    function appear2mee() { Appear2meeLayer.push(arguments);}
5
    
6
    appear2mee("initWithID","<Web ID From Exchange Or App>");
7
​
8
    /* 'top' | 'top-start' | 'top-end' | 'top-left' | 'top-right' | 'center' | 'center-start' | 'center-end' | 'center-left' | 'center-right' | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-left' | 'bottom-right' */
9
    appear2mee("setPosition","bottom-right");
10
   </script>
Copied!
Topics
See the Topics section above for more general topic information. For WordPress, topics can be automatically generated using the folder structure of the document. The "homepage" can be found using the class home. Again using the Insert Header and Footers plugin, script code can be added.
1
<script>
2
window.onload = function () {
3
  var learnQuickly = true;
4
  //  works for http://site.com/hierarchy/page/ --> gives topic page 
5
  var topic = window.location.pathname.split("/").slice(-2).shift();
6
  if(document.body.classList.contains('home')) {
7
   topic = "home";
8
  }
9
  appear2mee("receiveTopics",topic,learnQuickly);
10
}
11
</script>
Copied!
Customisation
In a simple install that is all that is required. If you need to have only some pages in your site show messages then you will need to activate a filter that the "Insert Headers and Footers" plugin uses.  There are a number of ways to do this but the easiest is to use another plugin, Code Snippets.  
Using the same install procedure as before install the "Code Snippets" plugin. Once installed the Snippets item with appear in the side menu. Use the Add New button to create a new snippet. 
To understand what this new snippet will do have a look at the documentation for the Insert Headers and Footers plugin. Basically, the plugin uses the result of the disable_ihaf_header filter to determine if it should add the header scripts to a page. The page is identified by its id. See below how to identify the id of a page. In the script below the page id 14 will not have headers so will not display any messages. 
To understand what this new snippet will do have a look at the documentation for the Insert Headers and Footers plugin. Basically, the plugin uses the result of the disable_ihaf_header filter to determine if it should add the header scripts to a page. The page is identified by its id. See below how to identify the id of a page! In the script below the page id 14 will NOT have headers so will not display any messages. 
1
add_filter( 'disable_ihaf_header', 'hide_header_on_page_id' );
2
function hide_header_on_page_id() {
3
  if( is_page( 14 ) ) {
4
    return true;
5
  }
6
  return false;
7
}
Copied!
A script similar to this with different page id and possible multiple pages should be added using the Snippets plugin. 
Be sure to select the "only run on site front end" option, as it is not required everywhere. 
Finding page IDs
There are a number of ways to find the id of a WordPress page. But by now you will not be surprised that the basic way is to use a plugin. The Show IDs plugin is one of a number that can be used, it adds an id column to the pages entries. 
There are a number of ways to find the id of a WordPress page id. But by now you will not be surprised that the best way is to use a plugin. The Show IDs plugin is one of a number that can be used, it adds an ID column to the pages entries. 
Iframe Integration
Many web page build systems, particularly WYSIWUG system, make it hard or expensive to include third party custom code. Many of these systems will allow you to insert an iframe. It is possible to make an iframe that with display a 2mee holocapsule message. Holocapsule messages are named messages than can created in the 2mee Exchange.  To include such a message in an iframe you need to set the src of the iframe to a url with some parameters. 
The url is https://exchange.cdnedge.bluemix.net/web/holoMsgIframe.html. Two parameters are needed, the first is the web ID that is used to setup the SDK and the second is the name of the holocapsule. Parameters are added at the end of the url using a ? as a separator and then a list of key=value pairs. The parameter list required  is ?key= <WebID>&msg=<MessageName>. Each key value pair is separated by &. 
An example url might look something like https://exchange.cdnedge.bluemix.net/web/holoMsgIframe.html?key=bacb37d6-a51f-491b-bd68-489c245b8c166c445393-bac9-4ab0-a0b6-cc6838902abd&msg=Welcome%20Page
Note that if your holocapsule name contains spaces of other "usual" characters they will need to be url encoded. The encoding for a space character is %20. 
An example in WiX would be to Add->Embedded->Custom Embeds
Unfortunately in WiX there is no access to the scrolling option in the iframe so you will need to resize it until the scrollbars are disappear. 
To manually include an iframein html you are recommended  to use something like the iframe below.
1
<iframe style="border-style:none;width:254px; height:320px;" scrolling=no src="https://exchange.cdnedge.bluemix.net/web/holoMsgIframe.html?key=bacb37d6-a51f-491b-bd68-489c245b8c166c445393-bac9-4ab0-a0b6-cc6838902abd&msg=Welcome%20Page"></iframe>
Copied!