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 to display the popup messages. 
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/appear2meeV2_1.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. 
The appear2mee SDK will report its version number on the console e.g., Appear2mee V2.1.11. By using the appear2meeV2_*.js any bug fixes or improvements that are not breaking changes will be available as this version is updated with any changes. If you want to keep using a particular version then you should use the specific version name, e.g., appear2meeV2_1_11.js.
Message Types
There are a number of message types, but they broadly divide into to categories, pulled messages and capsule based messages. 
Pulled Messages
Pull messages are scheduled by the 2mee Exchange. They have a start and end time. The appear2mee SDK polls the 2mee Exchange and stores a reference to any scheduled messages. When the play time of that message arrives it will generate a popup with the message. 
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/  type  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
Dialog Auto Height
By default, the popup dialog sets html's and body's CSS height to auto !important. If this behaviour is not compatible with your project's layout, set the dialogHeightAuto to false using
1
<script>
2
appear2mee("dialogHeightAuto", false);
3
</script>
Copied!
Dialog Z-Index
By default, the popup dialog has z-index of 10000 (prior to V2_0_10 it was 1060). If this is not compatible with your project's layout, set the z-index using the setSwalZIndex method. This sets the swal2-container of the sweetAlert2 dialog z-index to the required value.
1
<script>
2
appear2mee("setSwalZIndex", 999);
3
</script>
Copied!
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 Capsule must be used. A Capsule 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 Capsule. 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 Capsule 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!
The inlineMessage can be made more interactive using some extra functions and callbacks messages from the player to use these the inline message call has an extra parameter a unique id that the developer defines. This is used to identify which (if you have more than one) inline message is returning state information.
1
<iframe src="about:blank"
2
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange","myunique_uuid");'>
3
</iframe>
Copied!
Controlling the iframe from the parent page is made more complex by the need to support different browsers. In particularly some browsers will not play a video in an iframe, at least the first play, unless the button click was in that iframe. To help solve those issues a 
Inline Message state callbacks
The state of inline messages can be received by registering a callback function using the 
appear2mee("setInlineMessageStateFn", callback) method. This will set your callback function to receive state information messages from all the inlineMessages that are active on your page. 
The callback function has three arguments, the unique id you assigned to the inline message, the state of that message, at present one of playButtonClick, playReady, playEnd, playStarted, and loading, and a value argument. The value argument is null except in the loading state, where it will give the percentage of the messages current loaded (0.0 -> 100.0). 
1
appear2mee("setInlineMessageStateFn", inlineMessageState);
2
​
3
function inlineMessageState(messageId, state, value) {
4
  if (state == "playButtonClick") { 
5
    console.log("msg:" + messageId + " with state:" + state);
6
    return;
7
  }
8
  if (state == "playReady") { 
9
    console.log("msg:" + messageId + " with state:" + state);
10
    return;
11
  }
12
  if (state == "playEnd") { 
13
    console.log("msg:" + messageId + " with state:" + state);
14
    return;
15
  }
16
  if (state == "playStarted") { 
17
    console.log("msg:" + messageId + " with state:" + state);
18
    return;
19
  }
20
  if (state == "loading") { // update loading indicator
21
    console.log("msg:" + messageId + " with state:" + state + " and value:" + value );
22
    return;
23
  } 
24
  console.log("msg:" + messageId + " with state:" + state);
25
}
Copied!
The state can be used to control how the message iframe is presented. 
The playButtonClick state is required to support browsers need the play event to be in the iframe itself to trigger the video play.  There is a further method that can be used to set a play button in the iframe, if the is not suitable.  
1
// some web browser need to have button in iframe pressed to start video first time
2
appear2mee("playerWithButton","https://exchange.cdnedge.bluemix.net/web/appear-play-egg-border80.png");
Copied!
Inline Message play/stop controls
An inline message play and stop play can be controlled using SDK methods. The methods require the unique id you assigned to the inline message to determine which inline message to start/stop. 
The appear2mee("inlineMessagePlay", "myunique_uuid") method will start play (only if the message is loaded and ready to play).
NOTE: A messages cannot play until the playReady state has been sent. The playReady state can be used to activate play/stop buttons. 
1
 appear2mee("inlineMessagePlay", "c51c618b-5765-4abf-99a5-de7e59283007");
Copied!
The appear2mee("inlineMessageStop", "myunique_uuid") method will stop play. A call to inlineMessageStart after a stop does not resume the play but starts the play from the beginning. This is because messages are short, and restarting is better than having a few seconds of remaining message played. It also has the benefit of simplifying the user controls. 
1
 appear2mee("inlineMessageStop", "c51c618b-5765-4abf-99a5-de7e59283007");
Copied!
NOTE: All modern browsers require user an event (button press) before videos are played. It is not normally possible to call inlineMessagePlay to start a video programatically without the call being attached to a click event listener.
Capsule Information
Information about a capsule can obtained using the appear2mee("capsuleMessageInfo", name, callback) SDK method. The callback function with receive an object and a the capsule name. If the capsule name is null, then a capsule with the  capsuleMessageInfo arg name does not exist. The data object contains a link field which has a string with the message action link address. Not all capsules have a "call to action" link, if not link has be set on the 2mee exchange then the link value will be null.
1
// callback from capsuleMessageInfo
2
function capsuleInfo(data,capsuleName) {
3
  if (capsuleName == null) { // there is no capsule. It does not exist!
4
    document.getElementById('framePosition').style.setProperty('display', 'none');
5
  } else {
6
    hasLink = data.link;
7
  }
8
}
9
​
10
window.onload = function() {
11
  // check capsule exist and if it has an associated link.
12
  appear2mee("capsuleMessageInfo",theCapsuleToDisplay,capsuleInfo); 
13
  ...
14
  ...
15
}
16
  
Copied!
Example
An example using these features is available here.
https://s3.eu-geo.objectstorage.softlayer.net/webwidget2mee/testCapsule.html
Example of inlineMessage controls.
The example uses a loading-bar and an SVG image as the loader. Once loading has completed the player is faded in and the loader is faded out.  Play starts with tap on play button/player, after two seconds of play, a tap on player will open a new browser tab. After play ends the play button (image) will return after a five second wait, allowing another play to start. 
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 Capsule 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 Capsule.  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 Capsule 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!
SMS Messages
An SMS message is a special message that uses link parameters to select the message to play. See the Exchange documentation for how to sent SMSs.  An SMS sends a text  short link to a landing page where the Appear2mee SDK  interperpates the extra parameters that the 2mee Exchange adds to the link to enable reporting of the SMS usage. 
The simplest SMS landing page has only the SDK added in the header. The SDK itself will check the parameters of the href contents of the browser and if it finds the correct parameters it will show the required Capsule 
1
<script src="https://exchange.cdnedge.bluemix.net/web/appear2mee-beta.js" async></script>
2
<script>
3
window.Appear2meeLayer = window.Appear2meeLayer || [];function appear2mee() {Appear2meeLayer.push(arguments);}
4
  
5
let pullMessages = false;
6
appear2mee('initWithID', "bacb37d0-a51f-491b-bd68-489c245b8c166c445333-bac9-4ab0-a0b6-cc6838902abb", pullMessages);
7
</script>
Copied!
Example
A simple example is given below. The short link encodes the parameters required to display the selected capsule, and allows for reporting the activity. 
https://link.2mee.com/DODKv
A link to a web page plays a capsule based message.
User defined SMS Experience
A SMS landing page can be customised using the appear2mee SDK. 
The first step is to turn off the automated response of the SDK to the href parameters. This is done using the optional useInlineMessageAsSMS of the initWithID method. The default is false, that is use the in-build method to display a url with SMS parameters.
1
<script src="https://exchange.cdnedge.bluemix.net/web/appear2mee-beta.js" async></script>
2
<script>
3
window.Appear2meeLayer = window.Appear2meeLayer || [];function appear2mee() {Appear2meeLayer.push(arguments);}
4
let useInlineMessageAsSMS = true;
5
let pullMessages = false;
6
appear2mee('initWithID', "bacb37d0-a51f-491b-bd68-489c245b8c166c445333-bac9-4ab0-a0b6-cc6838902abb", 
7
                pullMessages,useInlineMessageAsSMS);
8
</script>
Copied!
Handling the SMS now become the responsibility of the developer!
There are a number of SDK methods to help. 
smsMessageInfo
The appear2mee("smsMessageInfo", callback) will call the callback function with a json data object that contains any sms information that was found using the url parameters. These include an data.sms, data.css, and data.link
If the data.sms is null then the page url contained not sms parameters. The .css member contains a css class defined by the sdk, and if the sms has a link associated with it, then the .link member will be set to the link string.
In the example below, if no sms is available a predefined capsule is played
1
appear2mee('smsMessageInfo', function(data) {
2
          if (data.sms == null) { // there is no sms
3
            appear2mee("capsuleMessageInfo", theCapsuleToDisplay, capsuleInfo); //sets up link
4
            appear2mee("inlineMessage", frame, theCapsuleToDisplay, "c51c618b-5765-4abf-99a5-de7e59283007");
5
          } else {
6
            var css = data.css;
7
            if (css == null) {
8
              css = "appearBottomRight"
9
            };
10
            document.getElementById('framePosition').classList.add(css);
11
            hasLink = data.link;
12
            appear2mee("smsInlineMessage", frame, "c51c618b-5765-4abf-99a5-de7e59283007");
13
          }
14
        });
Copied!
smsInlineMessage
In order to play the sms message the appear2mee('smsInlineMessage', frameObject, 'userDefinedUniqueId") command method is used. The first argument is an iframe object within the webpage where the message will be played. The second argument is a user defined unique id that is used to identify the state information that the SDK provides to the callback given in the setInlineMessageStateFn SDK method. 
The SMS message can then be controlled in the same way an inlineMessage can be. The testCapsule example is setup to also handle SMS parameters. These are usually in the form of a short link which at redirection and expands to give the url of a type shown below. 
https://s3.eu-geo.objectstorage.softlayer.net/webwidget2mee/testCapsule.html?2meeCSS=appearBottomRight&2meeId=TestId&2meeSMS=6967f44e-7b50-4b33-9f38-6c552cf8a1a9
Link which will display a message using 2mee exchange generate SMS parameters.
​
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 Capsule message. Capsule 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 Capsule. 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 Capsule 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 iframe in 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!
Python example
Next - Documentation
Wordpress
Last modified 1mo ago