Web SDK
Sending messages to your website
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.
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.
<script src="https://cdn.2mee.com/web/appear2meeV2_4.js" async></script>
<script>
window.Appear2meeLayer = window.Appear2meeLayer || [];
function appear2mee() { Appear2meeLayer.push(arguments);}
appear2mee("initWithID","<Web ID From Exchange>");
</script>
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.3.21. By using the appear2meeV2_3.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_3_21.js.
If you are using the appear2mee only for inlineMessages/eventMessages or sms messages, then you do not need the pulled message feature and it is best to turn this off as it polls messages that you will never use. By default it is on. To turn off the polling you can do on init,
var getScheduledMessages = false;
appear2mee("initWithID","<Web ID From Exchange>", getScheduledMessages);
Note the javascript
window.Appear2meeLayer = window.Appear2meeLayer || []; sets up a command queue. Commands are pushed on to this queue using the appear2mee() function. Only when the SDK script is loaded will it start executing these commands. When the SDK is first loaded by a user a unique ID is generated and stored in the browser local storage. On subsequent loads if an existing ID is present it will be used. Note that the same user will have different IDs if the user a different browser or incognito mode, or clear their local storage.
It is also possible to set a userID using the SDK. This can be used where the user has logged into a site or where an alternative ID is available.
appear2mee("setUserID","myUniqueID");
There are a number of message types, but they broadly divide into to categories, pulled messages and capsule based 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.
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
<script>
var learnQuickly = true;
// works for http://site.com/hierarchy/page.html --> gives topic page
var topic = window.location.pathname.split("/").pop().split(".")[0];
appear2mee("receiveTopics",topic,learnQuickly);
</script>
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
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
<script>
appear2mee("dialogHeightAuto", false);
</script>
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.
<script>
appear2mee("setSwalZIndex", 999);
</script>
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.
<iframe src="about:blank" width="0px" height="0px" frameborder="0"
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange");'>
</iframe>
An inline message can also be configured to have a background image, your logo perhaps.
<iframe src="about:blank" width="0px" height="0px" frameborder="0"
style="background-image:url(Logo.png);background-repeat:no-repeat;background-size:contain;background-position:center center;"
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange");'>
</iframe>
It is possible to configure inline messages to select a message at random from an array of messages.
<iframe src="about:blank" width="0px" height="0px" frameborder="0"
onload='appear2mee("inlineMessage",this,["MessageName","AnotherMessageName"]);'>
</iframe>
When the page is loaded on of these message will be displayed, the choice is random. If the chosen message does not exist then no message is displayed. That is why it is a good idea to set the width="0px" height="0px" frameborder="0" in the iframe, so that there is nothing rendered in the page. If you wish to weight the random selection you can supply weights to the array. In this case each element of the array must have a weight.
<iframe src="about:blank" width="0px" height="0px" frameborder="0"
onload='appear2mee("inlineMessage",this,["MessageName", 11,"AnotherMessageName",10]);'>
</iframe>
The setting above will give on average 11 MessageName and 10 AnotherMessageName for every 21 page loads. Note as this is an average, it will take quite a few samples to detect this weighting.
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 message id that the developer defines. This is used to identify which (if you have more than one) inline message is returning state information.
<iframe src="about:blank" width="0px" height="0px" frameborder="0"
onload='appear2mee("inlineMessage",this, "myMessageNameFrom2meeExchange","myunique_uuid");'>
</iframe>
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).
appear2mee("setInlineMessageStateFn", inlineMessageState);
function inlineMessageState(messageId, state, value) {
if (state == "playButtonClick") {
console.log("msg:" + messageId + " with state:" + state);
return;
}
if (state == "playReady") {
console.log("msg:" + messageId + " with state:" + state);
return;
}
if (state == "playEnd") {
console.log("msg:" + messageId + " with state:" + state);
return;
}
if (state == "playStarted") {
console.log("msg:" + messageId + " with state:" + state);
return;
}
if (state == "loading") { // update loading indicator
console.log("msg:" + messageId + " with state:" + state + " and value:" + value );
return;
}
console.log("msg:" + messageId + " with state:" + state);
}
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.
// some web browser need to have button in iframe pressed to start video first time
appear2mee("playerWithButton","https://cdn.2mee.com/web/appear-play-egg-border80.png");
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.
appear2mee("inlineMessagePlay", "c51c618b-5765-4abf-99a5-de7e59283007");
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.
appear2mee("inlineMessageStop", "c51c618b-5765-4abf-99a5-de7e59283007");
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.
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.
// callback from capsuleMessageInfo
function capsuleInfo(data,capsuleName) {
if (capsuleName == null) { // there is no capsule. It does not exist!
document.getElementById('framePosition').style.setProperty('display', 'none');
} else {
hasLink = data.link;
}
}
window.onload = function() {
// check capsule exist and if it has an associated link.
appear2mee("capsuleMessageInfo",theCapsuleToDisplay,capsuleInfo);
...
...
}
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.
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.
<button onclick='appear2mee("eventMessage","myMessageNameFrom2meeExchange");'>
My Button
</button>
It is also possible to call an event message with a "time event".
setTimeout(function() {
appear2mee("eventMessage","myMessageNameFrom2meeExchange");
},
3000); // 3 secs
However you might be better to use an offer message.
An offer message will present an event message based on some conditions that are set on the 2mee exchange. The start/end date, frequency, and whether the user has already accepted the offer can be used determine whether to show the message or show the offer again. The command is shown below, and can be used in your script so long as it it is after the command queue (window.Appear2meeLayer) has been generated.
<script>
appear2mee("offer", "offerName");
</script>
The offer command gives the capsule name to use. The offer conditions are all set on the 2mee exchange capsules page.
Note, the record of user responses is only stored in their browsers localStorage, so if a user uses more that one browser, or incognito mode the number of times and frequency an offer is displayed will depend on the browser not any userid.
When an offer has expired and you wish to start another offer, you can rename the current offer's capsule name eg, from offerName to OfferNameJanuarySale, then create a new capsule with the original name. This will change the offerId associated with the offer and as a result the browser's record of the offer, stored in localStorage, will be reset.
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.
// optional position "appearBottomRight" (default), "appearTopLeft",
// "appearTopRight", "appearBottomLeft"
appear2mee("pageMessage", pageMessageName, "appearBottomLeft");
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
<script src="https://cdn.2mee.com/web/appear2meeV2_4.js" async></script>
<script>
window.Appear2meeLayer = window.Appear2meeLayer || [];function appear2mee() {Appear2meeLayer.push(arguments);}
let pullMessages = false;
appear2mee('initWithID', "bacb37d0-a51f-491b-bd68-489c245b8c166c445333-bac9-4ab0-a0b6-cc6838902abb", pullMessages);
</script>
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/RxMYf
A link to a web page plays a capsule based message.
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.
<script src="https://cdn.2mee.com/web/appear2meeV2_4.js" async></script>
<script>
window.Appear2meeLayer = window.Appear2meeLayer || [];function appear2mee() {Appear2meeLayer.push(arguments);}
let useInlineMessageAsSMS = true;
let pullMessages = false;
appear2mee('initWithID', "bacb37d0-a51f-491b-bd68-489c245b8c166c445333-bac9-4ab0-a0b6-cc6838902abb",
pullMessages,useInlineMessageAsSMS);
</script>
Handling the SMS now become the responsibility of the developer!
There are a number of SDK methods to help.
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
appear2mee('smsMessageInfo', function(data) {
if (data.sms == null) { // there is no sms
appear2mee("capsuleMessageInfo", theCapsuleToDisplay, capsuleInfo); //sets up link
appear2mee("inlineMessage", frame, theCapsuleToDisplay, "c51c618b-5765-4abf-99a5-de7e59283007");
} else {
var css = data.css;
if (css == null) {
css = "appearBottomRight"
};
document.getElementById('framePosition').classList.add(css);
hasLink = data.link;
appear2mee("smsInlineMessage", frame, "c51c618b-5765-4abf-99a5-de7e59283007");
}
});
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.
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.
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.
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.
var loginData = {
"status": "pro"
}
var pageMessageName = window.location.pathname.split("/").pop().split(".")[0];
function callback(keyValues,messageName) {
if(messageName == null) return; // did not exist
console.log("message keyValues for " + messageName + ":", keyValues);
var matchValue = keyValues[loginData.status]
if (matchValue != null) {
// optional position "appearBottomRight" (default), "appearTopLeft", "appearTopRight", "appearBottomLeft"
appear2mee("pageMessage", messageName, "appearBottomLeft");
}
}
appear2mee("messageKeyValues", pageMessageName, callback);
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.
var msgCount = 0
function callback2(keyValues, topics, msgId) {
console.log("pull keyValues for:", keyValues);
console.log("pull topics for :", topics);
msgCount++;
if (msgCount > 1) {
if (keyValues["important"] != null) {
return 60 * 60; // try in 1 hour
} else {
return -1; // refuse message (do not see again)
}
}
return 0; // display message
}
appear2mee("setShouldDisplayMessageFn", callback2);
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.
appear2mee("setBackdrop","rgba(128,0,0,0.8)"); // dark red -- not recommended!
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.
appear2mee("setClickOutsideDismiss",false); // now clicks outside dialog are ignored
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://cdn.2mee.com/web/holoAdMsgIframe.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://cdn.2mee.com/web/holoAdMsgIframe.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.
There are a number of ways to edit Wordpress to add a custom block of HTML. These can be used to add the iframe code. This page used the editor from https://elementor.com/.
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.
<iframe style="border-style:none;width:254px; height:320px;" scrolling=no src="https://cdn.2mee.com/web/holoMsgIframe.html?key=bacb37d6-a51f-491b-bd68-489c245b8c166c445393-bac9-4ab0-a0b6-cc6838902abd&msg=Welcome%20Page"></iframe>
The webSDK can 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,
<script src="https://cdn.2mee.com/web/appear2meeV2_4.js" async></script>
<script>
window.Appear2meeLayer = window.Appear2meeLayer || [];
function appear2mee() { Appear2meeLayer.push(arguments);}
appear2mee("initWithID","<Web ID From Exchange Or App>");
/* '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' */
appear2mee("setPosition","bottom-right");
</script>
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.
<script>
window.onload = function () {
var learnQuickly = true;
// works for http://site.com/hierarchy/page/ --> gives topic page
var topic = window.location.pathname.split("/").slice(-2).shift();
if(document.body.classList.contains('home')) {
topic = "home";
}
appear2mee("receiveTopics",topic,learnQuickly);
}
</script>
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.
add_filter( 'disable_ihaf_header', 'hide_header_on_page_id' );
function hide_header_on_page_id() {
if( is_page( 14 ) ) {
return true;
}
return false;
}
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.
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.
Last modified 2mo ago