Skip to content

StraaS Web Messaging

Jump to bottom
terence223 edited this page Feb 14, 2022 · 69 revisions

To start using StraaS Messaging Service, you need to assure you have registered an account in cms.straas.io, and register your member data to StraaS by this tutorial.

Two kinds of Messaging SDKs

There are 2 kinds of Messaging SDK, first is Iframe sdk and second is MessageManager sdk. Iframe SDK provides an UI template for you to quickly integrate StraaS Messaging Service into your webpage, and the MessageManager sdk provides you the largest flexibility to utilize our messageing service to make your own customize UI.

Before initiate a iframe messaging sdk

Before initiate a messaging iframe sdk you need to provides both roomId and the memberToken. Please refer to this link for the detail of how to get a member token.

Iframe SDK

StraaS iframe sdk provides an UI-included sdk, to help you seamlessly integrate StraaS's chatroom into your web application.

Iframe SDK Getting Started

The sample HTML page below creates an iframe embedded chatroom into your webpage.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and chatroom) will replace this <div> tag. -->
    <div id="chatroom"></div>

    <script>
      // 2. This code loads the iframe chatroom API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://mgk.straas.net/sdk/1.7.7/iframe-sdk.js";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and StraaS Chatroom)
      //    after the API code downloads.
      var chatroom;
      function onStraaSChatroomIframeReady() {
        chatroom = new StraaSChatroom.Chatroom('chatroom', {
          accountId: <account_id provided from StraaS>,
          showOnlineUserThreshold: <threshold to determine if show online user number>,
          showMessageSource: <bool, to show message source icon or not>,
          chatroomName: <chatroomName provided by StraaS>,
          memberToken: <member jwt by StraaS CMS of your memeber, use null for guest>,
          straasSupport: <bool, to decide whether enable straas log support>,
          language: <i18n support, now support 'en', 'jp', 'zh'>,
          height: '390',
          width: '640',
          events: {
            'onReady': onChatroomReady,
          },          
          styleURL: <URL of custom css file, please refer section CSS file example>,
          secureMode: <when this value === false, iframe sdk will load chatroom page with insecure http protocol> 
        })
      }

      // 4. The API will call this function when the chatroom is ready.
      function onChatroomReady() {
         console.log('chatroom is ready')
      }

    </script>
  </body>
</html>

Events

The API fires events to notify your application of changes to the chatroom. As noted in the previous section, you can subscribe to specific event when you creating the iframe sdk.

  • onReady This event fires when chatrooms sdk is loaded and the user is connected to the pre assigned room.

Message Source Icon

If the flag showMessageSource is set with true, clients send messages from our mobile sdk would have a mobile icon on UI.
Mobile web clients(e.g. use iframe-sdk on mobile chrome) are not regarded as mobile clients, whose messages won't have the mobile icon.

Custom Domain

We provide three parameters to make custom domain work in both of iframe sdk and MessageManager sdk. They are customSocketServerHost, customRestServerHost and customSdkHost. Please contact us to get more details if you need this function.

How to Customize Your Chatroom in Iframe SDK

To customize your own look and feel in our iframe sdk, you need provide your own css file url to sdk when initialization. The config is called styleCSS.

The correspondent css template is provided in the following

CSS File Template
@charset "utf-8";
/*調整聊天背景顏色*/
/*Modify chatroom background color*/
body,
.nickname,
.input-message,
.list,
.list-ctn,
.dropdown-menu,
.sticker-ctn {
  background: #000;
}
/*調整滑鼠移到訊息區塊上的背景顏色*/
/*Modify mouse hover background color*/
.nav>li>a:focus,
.nav>li>a:hover,
.block:hover,
.sticker-tab a:hover,
.sticker-img:hover {
  background-color: rgba(255,255,255,.2);
}
/*調整表情符號區塊背景嚴色*/
/*Modify sticker block background color*/
.sticker-panel {
  background: #333;
}
/*調整訊息區塊底色樣式*/
/*Modify message background color*/
.message-ctn {
  border-top: rgba(255,255,255,.2) solid 1px;
  border-bottom: rgba(255,255,255,.2) solid 1px;
  background: transparent;
}
/*調整狀態訊息文字顏色*/
/*Modify status message text color*/
.status-message,
.status-message a,
.status-message a:hover {
  color: #f5e384;
}
/*調整 input 框的顏色*/
/*Modify input element background color*/
.form-control {
  background: rgba(255,255,255,.2);
  border: 1px solid rgba(255,255,255,0);
}
/*調整 input 區塊提示文字樣式*/
/*Modify input element placeholder text color*/
.form-control::-moz-placeholder {
  color: #999;
}
.form-control::-webkit-input-placeholder {
  color:#999;
}
.form-control:-ms-input-placeholder {
  color:#999;
}
/*調整表情符號樣式*/
/*Modify sticker button style*/
.sticker-btn {
  background: url('../images/emotion-w.svg') no-repeat top left;
  opacity: 1;
}
/*調整設定選單的邊框顏色*/
/*Modify setting dropdown menu border color*/
.dropdown-menu {
  border: 1px solid rgba(255,255,255,.2);
}
.dropdown-menu .divider {
  background-color: rgba(255,255,255,.2);
}
/*調整設定按鈕的顏色*/
/*Modify setting button color*/
.btn-default,
.btn-default:hover,
.btn-default:focus,
.btn-default.active.focus,
.btn-default.active:focus,
.btn-default.active:hover,
.btn-default:active.focus,
.btn-default:active:focus,
.btn-default:active:hover,
.open>.dropdown-toggle.btn-default.focus,
.open>.dropdown-toggle.btn-default:focus,
.open>.dropdown-toggle.btn-default:hover,
.btn-default.active,
.btn-default:active,
.open>.dropdown-toggle.btn-default {
  background: rgba(255,255,255,.2);
  background-image: none;
  border: 1px solid rgba(255,255,255,0);
  color: #fff;
}
/*調整設定選單滑鼠移過去的背景顏色*/
/*Modify setting dropdown menu mouse hover background color*/
.dropdown-menu>li>a:focus,
.dropdown-menu>li>a:hover {
  background: rgba(255,255,255,.2);
}
/*調整文字顏色*/
/*Modify text color*/
body,
.close,
.close:focus,
.close:hover,
.form-control,
.dropdown-menu>li>a,
.dropdown-menu>li>a:focus,
.dropdown-menu>li>a:hover,
.btn-default,
.btn-pin,
.btn-unpin {
  color: #fff;
  opacity: 1;
  text-shadow: none;
}
/*調整次要文字顏色，包含 Tab 、訊息時間文字和聊天室設定標題*/
/*Modify secondary text color, include tab text color and message date text color and setting title color.*/
.nav>li>a,
.time,
.dropdown-header {
  color: #999;
}
/*調整在線名單 Tab 底線樣式*/
/*Modify tab bottom border color*/
.list-tab {
  border-color: rgba(255,255,255,.2);
}
/*修改這裡調整訊息文字字級*
/*Modify tab bottom border color*/
.message-ctn .block {
  font-size: 18px;
  opacity: 1;
  text-shadow: none;
  line-height: 1.4;
}
/*修改這裡調整文字訊息的間距*
/*Modify message margin*/
.block {
  margin-bottom: 5px;
}
/*文字特別強調的顏色*/
/*Modify primary color*/
a,
a:hover,
.chatroom-num span {
  color: #51C0C2;
  text-decoration: none;
}
/*Tab 特別強調的顏色*/
/*Modify active tab color*/
.nav-pills>li.active>a,
.nav-pills>li.active>a:focus,
.nav-pills>li.active>a:hover {
  color: #51C0C2;
  background-color: transparent;
  border-bottom: 3px solid #51C0C2;
  -webkit-border-radius: 0;
  -moz-border-radius: 0;
  border-radius: 0;
}
/*按鈕特別強調的顏色*/
/*Modify primary button background color*/
.btn-primary {
  background-color: #51C0C2;
  border-color: #51C0C2;
  background-image: none;
}
/*按鈕滑鼠移過去的顏色*/
/*Modify primary button hover background color*/
.btn-primary:hover,
.btn-primary.focus,
.btn-primary:focus,
.btn-primary.active,
.btn-primary:active,
.btn-primary:active:hover,
.btn-primary.active:hover,
.btn-primary:active.focus,
.btn-primary.active.focus,
.btn-primary:active:focus,
.btn-primary.active:focus,
.open > .dropdown-toggle.btn-primary,
.open > .dropdown-toggle.btn-primary:hover,
.open > .dropdown-toggle.btn-primary:focus,
.open > .dropdown-toggle.btn-primary.focus {
  background-color: #2D8787;
  border-color: #2D8787;
}
/*設定選單特別強調的背景顏色*/
/*Modify setting dropdown menu active background color*/
.dropdown-menu>.active>a,
.dropdown-menu>.active>a:focus,
.dropdown-menu>.active>a:hover {
  background-color: #51C0C2;
}
/*卷軸顏色樣式*/
/*Modify scrollbar color*/
::-webkit-scrollbar {
  width: 10px;
  background: transparent;
}
::-webkit-scrollbar-track {
  background: transparent;
}
::-webkit-scrollbar-thumb {
  background: rgba(255, 255, 255, 0);
}
:hover::-webkit-scrollbar-thumb {
  background: rgba(255, 255, 255, .2);
  border-radius: 5px;
}
/*錯誤提示顏色樣式*/
/*error note color*/
.submit-note {
  background: #51c0c2;
}
.submit-note:before {
  border: 5px solid #51c0c2;
  border-color: transparent transparent #51c0c2 transparent;
}
/*置頂推廣文案樣式*/
/*Promo message style*/
.block.pin-message,
.block.pin-message:hover {
  background-color: #2db1b3;
  margin-bottom: 0;
  border: 1px solid #2db1b3;
  border-color: #000 #2db1b3 #2db1b3 #2db1b3;
  color: #fff;
  max-height: 60px;
}
.block.pin-message .face {
  top: 6px;
}
/*隱藏頭圖樣式*/
/*Hide face image*/
.face,
.face-img {
  display: none;
}
.block,
.block.pin-message,
.block.pin-message:hover{
  padding: 7px 5px 2px 7px;
}
/*歡迎詞顏色樣式*/
/*Welcome message style*/
.block.welcome-message,
.block.welcome-message:hover {
  background-color: #333333;
  border: 1px solid #3e3d3d;
  color: #f5e384;
  padding: 7px 5px 2px 7px;
}
.welcome-message a,
.welcome-message a:hover {
  color: #f5e384;
}

MessageManager SDK (Browser client side)

StraaS MessageManager sdk provides an non-UI sdk to help you get chat room information.

MessageManager SDK Getting Started

The sample HTML page below creates an MessageManager SDK into your webpage.

<!DOCTYPE html>
<html>
  <body>
    <script>
      // 1. This code loads the MessageManager SDK code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://mgk.straas.net/sdk/1.7.7/message-sdk.js";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
      
      var messageManager;

      // 2. This function triggers after message-sdk.js is downloaded.
      // It provides <createMessageManager> to help you get MessageManager SDK instance
      function onStraaSMessageManagerSdkReady(createMessageManager) {
        
        // 3. Please use <createMessageManager> to create MessageManager SDK instance
        // <createMessageManager> is also a exported function
        messageManager = createMessageManager({
          accountId: <account_id provided from StraaS>,
          memberToken: <member jwt by StraaS CMS of your memeber, use null for guest>,
          straasSupport: <bool, to decide whether enable straas log support>
        })

        // 4. Please use <init> function to initiative MessageManager SDK.
        messageManager.init()
          .then(function() {
            // 5. Connect to your chat room, after connected, you can enjoy APIs.
            messageManager.connect(<chatroomName provided by StraaS>, {
              events: {
                aggregated_data_add: (msg) => {},
                raw_data_add: (msg) => {},
                ...
              }
            })
          })
      }
    </script>
  </body>
</html>

MessageManager SDK APIs

For more details, please refer to API documents

MessageManager SDK (Node.js server side)

StraaS MessageManager sdk provides node.js server side npm lib.

MessageManager SDK Getting Started

npm install straas-message-sdk
import lib by ES6
import createMessageManager from 'straas-message-sdk'
import lib by ES5
var createMessageManager = require('straas-message-sdk').default

Call init first

Call messageManager.init() is required to generate instance before using MessageManager SDK

  • Before using APIs, you should connect to a chatroom by call messageManager.connect(<chatroomName provided by StraaS>

Cold down time

After a message is sent, it has 1 second cold down time for next message to send. So for iframe sdk, if user sends a message from UI, then soon send another message in 1 second, it throws 403 error code.

For MessageManager SDK is in the same case for API sendMessage

Data channel

Data channels are designed to send custom data, and to keep them separated from chat messages. There are two methods to send custom data:

You can send aggregated data with key by calling sendAggregatedDataTypeMessage. This method would aggregate your key into {"key": "key name", "n": "count of your key name"}

messageManager.sendAggregatedDataTypeMessage(chatroomName, 'key name')

You can send rawData by calling sendRawData. RawData should be a valid JSON object only

messageManager.sendRawData(chatroomName, RawData)

You can register events to listen added events when connect to chatroom.

messageManager.connect(<chatroomName provided by StraaS>, {
    events: {
        aggregated_data_add: (msg) => {},
        raw_data_add: (msg) => {},
    }
}

MessageManager SDK APIs

For more details, please refer to API documents

web messaging

Clone this wiki locally