Upgrading from Pre-XDK Versions

The following upgrade instructions should help for developers upgrading from SDKs and UI Libraries Layer has shipped prior to the Layer XDK.

Uninstall older versions from our project

npm uninstall layer-websdk layer-ui-web --save

Initialization has Changed

Previously, you initialized a project using:

var client = new layer.Client({ appId });
layerUI.init({ appId });

Now initialization is done using Layer.init():

import Layer from '@layerhq/web-xdk';
var client = Layer.init({ appId });

Alternatively, if using only APIs, but no UI components, you may use:

import Layer from '@layerhq/web-xdk/index-core';
var client = Layer.init({ appId });

Challenge Event Handler is Required

Applications must provide a challenge event handler to the Layer Client. This is needed not just to enable authentication, but also to enable reauthentication when a Session Token expires.

import Layer from '@layerhq/web-xdk';
var client = Layer.init({ appId });
client.on('challenge', function(evt) {
    // standard challenge handling

If there are paths through your code that bypass creating the Challenge Event handler, errors will be thrown.

Component Paths have Changed

The following WebSDK component paths have changed to the following Web XDK paths:

  • layer.Conversation is now Layer.Core.Conversation
  • layer.Query is now Layer.Core.Query
  • layer.Identity is now Layer.Core.Identity
  • layer.Message is now Layer.Core.Message
  • layer.Client is now Layer.Core.Client

All Layer UI paths have been changed from layerUI to Layer.UI

UI Component Names have Changed

  • <layer-conversation-panel /> is now <layer-conversation-view />
    • Using the React Adaptor its changed from ConversationPanel to ConversationView
  • <layer-conversations-list /> is now <layer-conversation-list />
    • Using the React Adaptor its changed from ConversationsList to ConversationList
  • <layer-identities-list /> is now <layer-identity-list />
    • Using the React Adaptor its changed from IdentitiesList to IdentityList
  • <layer-messages-list /> is now <layer-message-list />
  • <layer-composer /> is now <layer-compose-bar />
  • The Text Handler that identifies Image URLs within the message and fetches the associated image has been removed as it is not a necessary part of a richer Text Card
  • The YouTube Handler which identifies YouTube URLs in a Message and fetches the YouTube viewer has been removed; a YouTube Message Type may eventually replace this.

Note that in addition to updating your code to reference the correct component, any custom CSS that targets the above DOM Nodes will need to be updated with the new names.

Optional components are no longer built in (NPM Only)

For NPM builds you must explicitly import optional components. The ConversationView is not an optional component, but a ConversationList and an IdentityList are both optional, as is the FileUploadButton.

See the API Reference for instructions on how to import these into your project.


Replaceable Content is a concept provided by the Web XDK UI Components to provide customizable areas of widgets for which you can provide DOM Nodes (or React Components, etc…) that will populate that area. This is discussed in more detail with respect to UI Components. This removes the need for replacing UI Component templates with custom templates any time you want to add something to a Component.

UI Components have been removed

  • <layer-compose-button-panel /> has been removed; button content is now managed via replaceableContent
  • <layer-conversation-last-message /> has been removed; each Message Type now exposes a method `getOneLineSummary
  • <layer-delete /> has been removed; deletion when available is provided via the <layer-menu /> widget or by custom widgets provided by you. Similarlly, the onMessageDeleted / layer-message-deleted event is now removed as well. A custom delete can be added next to each Message Item / Conversation Item using Replaceable Content.

Property Name Changes

  • ComposeBar.buttons, ComposeBar.buttonsLeft, ConversationView.composeButtons and ConversationView.composeButtonsLeft are all removed and managed via replaceableContent
  • emptyMessageListNode is managed via replaceableContent
  • emptyNode is managed via replaceableContent
  • dataLoadingNode is managed via replaceableContent
  • endOfResultsNode is managed via replaceableContent

MIME Type Changes

All MIME Types will change; the only exception to this will be Message Handlers that are being supported for backwards compatability (i.e. Message Handlers built by customers). This means that:

  • any custom code that you have that tests the MIME Type to decide what actions to take must be updated
  • any code that generates a message with specific MIME Types should be updated to generate Message Type Models, and then call the Model’s send() method.
  • any webhooks that filter on specific MIME Types must not only filter on new MIME Types, but must also filter out MIME Type Attributes; note that the Javascript client moves all MIME Type Attributes out of the part.mimeType property and into the part.mimeAttributes property; but your server probably does not do that.
  • Any Server API code for sending or analyzing messages must be updated to use new MIME Types and generate appropriate MIME Type Attributes (or ignore Attributes when parsing messages looking for specific MIME Types)

Code such as:

    parts: [{
        mimeType: "text/plain",
        body: "hello world I am text"

should be replaced with:

const TextModel = Layer.Core.Client.getMessageTypeModelClass('TextModel')
const model = new TextModel({
    text: "hello world I am text"
model.send({ conversation: conversation });

Updating Custom Messages

Your existing Custom Messages that were built in Layer UI for Web should work. However:

  1. You will need to validate that your customizations work within the XDK
  2. Your messages will not be consistent with how the framework now works
  3. Your messages will not be able to take advantage of the latest features

Much of the code that goes into creating a Custom Message for Layer UI for Web can be copied and pasted into the templates illustrated in Custom Messages.

React Native

This repository has not been tested with React Native; React Native is not currently supported. Customers who were successful in getting React Native working with the WebSDK could do so knowing that Layer had at least built one sample app to validate that worked… The Web XDK has not had any internal sample applications built yet.

API Reference Changelog