Embedding of the Web Client

Notes

CORS Exception

The embedded chat probably runs on a different domain than Grape. By default, the same-origin policy forbids requests to different domains. To allow this, a server can set appropriate CORS headers.

A list of allowed hostnames can be configured on the Grape server. If a hostname is in the exceptions list, the server will answer with a Access-Control-Allow-Origin header containing this hostname.

The exceptions have to be configured on the server and a restart is required.

If you don’t want to wait for the Grape team or for your server admin to do this or if you don’t know which hostnames you will be using, you can use a plugin in Google Chrome to override the header to allow all Origins. This plugin should only be used for development and poses security risks. It is not maintained by Grape.

Branding

  • Grape client doesn’t offer any styling customizations yet. Please restrain from overriding any look and feel of the client and use it “as is”.
  • Do not integrate any custom functionality into the Grape UI directly. Use the space outside the container or use modals.

Browsers support

Grape supports only latest browsers: IE11+, latest Chrome, latest Firefox, latest Safari.

We also support IE10 document mode in IE11. To turn it on, you can use meta tag:

<meta http-equiv="X-UA-Compatible" content="IE=10" />

Usage

Container

In order to know where to render the client, you need to provide a div in the document. Also you need to make sure this div has a desired size. Client will adapt to the size of your container.

<body>
  <div id="grape-client"></div>
</body>

Initialize

All options are required:

  • container - selector string for insertion container, any valid CSS selector.
  • channelId - channel id, a number.
  • orgId - organization id, a number.
  • serviceUrl - your Grape server’s URL.
  • staticBaseUrl - URL to the web client files.

Use the code below in order to load the chat. Modify the options based on your setup.

<script>
(function(a){var b=document.createElement("script");b.async=1;b.src=a.staticBaseUrl+"app/embedded.js";b.onload=function(){grapeClient.embed(a);if(a.onReady)a.onReady()};document.head.appendChild(b)})({
  container: "#grape-client",
  channelId: 632,
  orgId: 1,
  serviceUrl: "https://chatgrape.com",
  staticBaseUrl: "https://ug-cdn.com/static/",
  onReady: function() {
    console.log("Grape Client initialized")
  }
});
</script>

For developing and testing, you can also try the latest (beta) web client version. Use this serviceUrl: https://unpkg.com/grape-web-client/dist/.

JavaScript API

Suspend

grapeClient.suspend()

This method will put the chat into a suspend mode, where no connection to the server will be maintained.

Resume

grapeClient.resume()

This method will reactivate the client after it was in a suspend mode.

Search messages

grapeClient.searchMessages(query, [options])

Opens a search UI for messages and displays results for a given query. Can be called multiple times while user is typing.

grapeClient.searchMessages('my search')

Options

{
  currentChannelOnly: {
    show: true,
    status: false
  },
  searchActivities: {
    show: true,
    status: false
  }
}

Change channel

grapeClient.setChannel(channelID, messageId)

This method will change channel for client.

grapeClient.setChannel(1, 'c96422a2e9a911e899060242ac190005')

Client version

grapeClient.version

This variable contain current client version.

grapeClient.version

Show and hide UI components

grapeClient.show(component) grapeClient.hide(component)

Possible component values: “mentions”, “labeledMessages”, “search”.

grapeClient.show('mentions') // Show mentions
grapeClient.hide('mentions') // Hide mentions

Mentions options

{
  showRoomMentions: {
    show: true,
    status: false
  }
}

Labeled messages options

{
  currentChannelOnly: {
    show: true,
    status: false
  }
}

Custom File Upload Dialog

grapeClient.setOpenFileDialogHandler(handler)

You can create your custom file upload functionality by defining a handler. Handler will be invoked if defined instead of the default upload UI, when upload button is clicked.

grapeClient.setOpenFileDialogHandler(() => {
  alert('Upload button was clicked')
})

Authorization status

grapeClient.authStatus

Current authorization status is always defined in grapeClient.authStatus property. Possible values are “authorized” and “unauthorized”.

If you want to react to auth status change, see in events section.

Events

Emitter API

Object grapeClient is an event emitter.

Subscribing any event: grapeClient.on(event, handler).

Subscribing any event once: grapeClient.once(event, handler).

Unsubscribing all events: grapeClient.off().

Unsubscribing specific event: grapeClient.off(event).

Unsubscribing specific event from a specific handler: grapeClient.off(event, handler).

Event hide

If a component was closed from inside, you may want to listen to hide event.

grapeClient.on('hide', () => {
  // Your reaction.
})

Event authChange

Use this event in order to react to auth status change for e.g. when user looses the session.

grapeClient.on('authChange', (authStatus) => {
  // Your reaction.
})