sorun-js

Javascripts APIs to communicate with Sorunapp APIs and support developers with some utilities to develop either web chats or mobile chats components using React native.

Install

npm install --save sorun-js

Services

We implemented main services in this library that supports a layer to communicate with the Sorun back-end point, and which manage the life-cycle of the application. These services are implemented for both web browsers or React native apps on mobile platforms. These services can be access through a factory class that will initialize them and choose the right implementation according to the target platfrom. The factory can be used as next:

import React, { Component } from 'react'
import {SorunJsFactory,SORUNJS_BROWSER_TYPES,SORUNJS_NATIVE_TYPES} from 'sorun-js'

class Example extends Component {

 constructor(){
   SorunJsFactory.getInstance().initFactory(SORUNJS_BROWSER_TYPES);
   //SorunJsFactory.getInstance().initFactory(SORUNJS_NATIVE_TYPES,this); in case of React native

   var authManager=SorunJsFactory.getInstance().getAuthManager();// To access authentication service
   var messManager=SorunJsFactory.getInstance().getMessagesManager();// To access messages service
   var chaeManager=SorunJsFactory.getInstance().getCacheManager();// To access cache service
   var compManager=SorunJsFactory.getInstance().getCompaniesDataProvider();// To access companies service
   var fileManager=SorunJsFactory.getInstance().getFilesDataProvider();// To access files service
   var parmManager=SorunJsFactory.getInstance().getParamsManager();// To access parameters service
   var langManager=SorunJsFactory.getInstance().getLanguagesService();// To access languages service
 }

 render () {
   return (
     <MyComponent />
   )
 }
}

The factory initFactory method should be called one time in application boot code or in the constructor of the main component. Next are more details about services and their supported APIs: 1- Parameters service: is used to store the app life cycle parameters, the factory will initialize this service that will automatically fetch them from querystring in case of a browser version or from component props in case of React Native. Next table describe the service APIs:

| API | Description | | :------------------------ |:----------------------------------------------------------------------| | setToken(value) | The auth service uses this call internally and can be used to force a specific token to be used in the app.| | setCompany(value) | A call to set the company object (The authentication serivce need this variable in order to work).|

Next table describe the used parameters and the job of each one of them:

| Parameter name | Description | | :------------------ |:--------------------------------------------------------------------------------------------------| | server | Can take three values (test-prod-local) in order to define the back-end api path for test, production and local environment in order. The default value is prod. This parameter is used internally in the class and is not open to be accessed publically.| | platform | Can take four values (WEBCHAT,ANDROID,IOS,CLIENTWEB) which used to define the platform the webchat are working on. The parameter is send also with the server side calls to support filteration of requests using the platfrom. And the default value is WEBCHAT. Can be accessed with 'platfrom' property.| | sourceURL | It's used in communication with server side so that the calls can be filtered by their source. | | urlPhone | This parameter can be used to force the system using specific phone number in authentication. | | chatColor1 | Can be used to customize chat skin, it will specify the background color of the agent messages. Can be accessed with 'chatColor1' property. | | chatColor2 | Can be used to customize chat skin, it will specify the font color of the agent messages | | chatColor3 | Can be used to customize chat skin, it will specify the card objects color| | chatColor | Can be used to customize chat skin, it will specify the font color of the client messages| | headerColor | Can be used to customize chat skin, it will specify the top header background color| | companyFilter | An array of integers (Companies ids) to filter out companies list according to them| | urlCompany | This parameter can be used to force the system using specific company in authentication, its an integer which is the id of the company.| | urlToken / token | This parameter can be used to force the system using specific token in authentication. Can be accessed with 'token' property. | | variable / var | To pass any kind of string type parameters to chatbots. If more than one variable needs to be passed stringified json can be added to this field | | poolFilter | List comma seperated message category ids can be entered here. If this parameter used only given message categories will be asked to client. If one pool id given, the client will directly start the conversation with this conversation category. Any existing open conversation will not be affected with this parameter but it should be ended. This parameter also can be used with inactive conversation categories which is helpful to start some client with hidden conversation categories. | | showHeader | Its a boolean parameter that is used to either show or hide the header section. | | clearAskPushCookie | | | lang | This parameter is used to determine the target language or the controllers. | | hideLocation | Its a boolean parameter that is used to hide or show the location share button in message input box.| | hideFile | Its a boolean parameter that is used to hide or show the upload file button in message input box.| | api | This parameter is used to force a specific back-end path.| | onlyActive | This parameter is used to force only the active companies to appear inside companies list.|

import React, { Component } from 'react'
import {SorunJsFactory,SORUNJS_BROWSER_TYPES,SORUNJS_NATIVE_TYPES} from 'sorun-js'

class Example extends Component {
 paramsManager;

 constructor(){
   this.parmManager=SorunJsFactory.getInstance().getParamsManager();
 }

 someFunction(){
   var token = this.paramsManager.token; // In order to access the token parameter
 }

 render () {
   return (
     <MyComponent />
   )
 }
}

2- Authentication service: is used to manage the authentication life cycle of the application with Sorun back-end point. This service supports subscribe-publish pattern in order to publish the current stage in authentication, and supports other types of calls to get user data. Next table describe its API usage:

| API | Description | | :------------------|:---------------------------------------------------------------------------------------| | subscribe | Subscribe to the events published by this service | | unsubscribe | Unsubscribe from pre-subscribed events | | auth | Run authentication process and publish the events according to the current status | | logout | Logout the user and clear its cookies session | | getClient | Get client info, should be called after authentication, a function can be passed to this function that will be called after fetching data from the server and pass these data to this function if the call succeeded. | | register | Register a phone number for getting a token, it takes four parameters (phone, company object, sucess function and fail function). This function will automatically re-call auth API call. | | activate | Activating a phone number after getting the code, it takes five parameters (phone, company object, code, sucess function and fail function). This function will automatically re-call auth API call. | | saveProfile | Save profile info, it takes five parameters (name, user name, email, success function, fail function).|

The authentication stages described in the next table:

| Stage name | Description | | :------------------------ |:--------------------------------------------------------------------------------------------------| | AUTH_NEED_PHONE | The app is requesting phone number to be provided through register call | | AUTH_NEED_PHONE_CODE | The app is requesting phone sent code to be provided through activate call | | AUTH_NEED_COMPANY | The app is requesting the company to pass the company id to parameters service | | AUTH_DONE | The authentication have been done successfully & the token stored in parameters service | | AUTH_WITHOUT_PHONE_FAILED | Authentication failed either it needs to review parameters again or connect to Sorun support team |

3- Messages Service: is used to manage messaging between client side and Sorun back-end, it supports communication both via socket connection or via normal periodic fetch method for old browsers. This service supports subscribe-publish pattern in order to publish the socket events to other subscribed components. Next table describe its API usage:

| API | Description | | :------------------|:---------------------------------------------------------------------------------------| | subscribe | Subscribe to the events published by this service | | unsubscribe | Unsubscribe from pre-subscribed events | | socketInit | It initializes the socket connection with the server, it takes a boolean parameter to reset the conversation timer when needed.| | closeSocket | It will close the socket connection with the server side. | | sendMessage | It's used to send a message to the server, it takes 6 parameters (message, message type, sunccess function, fail function, conversation Id, unique Id if needed). | | resetConversationTimer | Will reset the conversation timer to fetch the conversations again directly. | | setConversationTimer | Will set the conversation timer to a specific value. | | endConversation | Will ends a conversation. It takes two parameters, success function and fail function.|

Utilities

For now the library only offer some extentions for String prototype in JavaScript for a better use of that prototype, it supports startsWith in addition to convertToTime. All what you need to do is to call the static init funciton inside StringExtentions class in order to add these extentions to the prototype as next:

import React, { Component } from 'react'
import {StringExtentions} from 'sorun-js'

class Example extends Component {

 constructor(){
   StringExtentions.init();
 }

 render () {
   return (
     <MyComponent />
   )
 }
}

You should only call init one time in the application boot code or in the main component constructor.

Constants and Enums

You can access some static enums defined to be used directly in the web chat, these enums as next: 1- Countries enum: stores a list of countries names in English and its language in addition to its letters code and phone code. The countries enum can be used directly as static array of objects as next:

import React, { Component } from 'react'
import {Countries} from 'sorun-js'

class Example extends Component {
  render () {
    var test=Countries.allCountries;
    return (
      <MyComponent />
    )
  }
}

2- Emojis enum: as countries this enum stores the Emojis codes in a static array and can be used as next:

import React, { Component } from 'react'
import {Emojis} from 'sorun-js'

class Example extends Component {
  render () {
    var test=Emojis.emojiList;
    return (
      <MyComponent />
    )
  }
}

Important release notes

1.4.10: Adding company id to old conversations call 1.4.9: Encoding sourceUrl when sending it to BE 1.4.8: Moving register phone and activate parameters to POST body 1.4.6: Removing push token parameters 1.4.5: Escape custom colors parameters from having CSS code 1.4.4: Removing the token in querystring from phone activation call 1.4.3: Adding CSS and JS runtime loader to UI service and moving passwords to POST body in agent change password 1.4.1: Removing token usage in reporting services 1.4.0: Using token instead of clientToken in header with the new BE 1.3.2: Fixing send button coloring problem 1.3.1: Fixing the generated bundle with Javascript pure code for IE 7-9 1.3.0: Removing any dependecy to babel-polyfill (The new stable version) 1.2.11: Fixing an error in Browser UI service 1.2.10: Removing es6-shim because of using babel-polyfill 1.2.9: Removing babel-polyfill from the library 1.2.8: Adding Ui Service to the library 1.2.6: Seperating Capatcha call from login 1.2.5: Supporting both sourceUrl and sourceURL as parameters 1.2.4: Fix a problem in reseting conversation timer 1.2.3: Move the services initialization to instance level and make the library supports getting paremeters either from querystring or passed to initalization call in either web or native 1.2.2: Move the username and password to post body in agent login 1.2.1: Remove the socket auto connect from library 1.2.0: New version with more stable messages life cycle 1.1.36: Some fixes on messages provider socket connection 1.1.34: Fixing a problem when closing the socket 1.1.33: Updates in socket closing function to suits React Native 1.1.32: Removing writing to console socket errors 1.1.31: Fixing the token isn't passed to upload file call 1.1.30: Fixing setting the File server parameter 1.1.29: Adding a function to upload file to bucket through using a passed AWS instance 1.1.28: Encoding all passwords inside server calls 1.1.27: Fixing a problem in sending form data in agent forget password, and including Babel polyfill 1.1.26: Adding the new staging backend path 1.1.24: Adding native parameter to native calls 1.1.20: Adding captcah to agent auth call, sending user name and password in headers 1.1.18: Removing the recursive auth call from register without phone 1.1.17: Adding console logs to publishers 1.1.16: Removing converting from and to JSON when using AsyncStorage 1.1.15: Adding console logs to authentication calls errors 1.1.14: Fixing a problem with sourceUrl parameter 1.1.12: Using a suitable library for React Native storage to fix compiling problems 1.1.11: The new stable version that is using Axios 1.1.8: (Has a very big problem cause timers commented out by mistake) 1.1.6: Removing any dependency on window object on browser (Not stable) 1.1.4: The library now depends on Axios for server side communication instead of native fetch. (Not stable) 1.1.X: The new stable releases of the library, also it supports the React native implementation. 1.0.X: The initial version of the library (wasn't stable).

License

MIT © SORUN