Web Customization
Once properly installed and configured, the ASAPP Chat SDK embeds two snippets of HTML markup into your host web page:
This section details how these elements function. In addition, it describes how to Customize the Chat UI, Dynamic Styling Configuration, Custom Icons, and Advanced Configuration Options.
Badge
The ASAPP Chat SDK Badge is the default interface element your customers can use to open or close the ASAPP Chat iframe.
When a user clicks on this element, it will trigger the ASAPP(‘Show’) or ASAPP(‘Hide’) APIs.
This toggles the display of the ASAPP Chat SDK iframe.
Badge Markup
By default. the ASAPP Chat SDK Badge is inserted into your markup as a lightweight button
element, with a click behavior that toggles the display of the iframe element. ASAPP recommends that you use the default badge element so you can take advantage of our latest features as they become available.
However, if you wish to customize the badge, you can do so by either manipulating the CSS associated with the badge, or by hiding/removing the element from your DOM and toggling the display of the iframe using your own custom element. See the Badge Styling section below for more details on customizing the appearance of the ASAPP Chat SDK Badge.
ASAPP Badge Styling
You can customize the ASAPP Chat SDK Badge with CSS using the ID #asapp-chat-sdk-badge
or classname .asappChatSDKBadge
selectors. ASAPP recommends that you use BadgeColor.
The following snippet is an example of how you might use these selectors to customize the element to meet your brand needs:
Custom Badge
You can hide the ASAPP Chat SDK Badge and provide your own interface for opening the ASAPP Chat SDK iframe.
- Set BadgeType to none.
- Call
ASAPP('show')
and/orASAPP('hide')
when your custom badge is clicked to open/close the iframe. - In order to ensure that the Chat SDK is ready, ASAPP recommends to display your custom badge disabled/loading state at first and then utilize onLoadComplete to enable it.
Example:
In the code example below, the ‘Chat with us’ button is not clickable until you enable it using onLoadComplete.
Once enabled, a user can click the button to open the ASAPP SDK iframe.
Custom Button:
Load config example:
iframe
The ASAPP Chat SDK iframe contains the interface that your customers will use to interact with the ASAPP platform.
The element is populated with ASAPP-provided functionality and styled elements, but the iframe itself is customizable to your brand’s needs.
iframe Markup
The SDK iframe is instantiated as a lightweight <iframe>
element whose contents are delivered by the ASAPP platform.
ASAPP recommends using the default iframe sizing, positioning, and functionality so you can take advantage of our latest features as they become available.
However, if you wish to customize this element you can do so by applying functionality and styling to the frame itself. See the iframe Styling section below for details on available customizations.
The following code snippet is an example of the ASAPP Chat SDK iframe markup.
iframe Styling
You can customize the ASAPP Chat SDK iframe by using the ID #asapp-chat-sdk-iframe
or classname .asappChatSDKIFrame
selectors.
The following snippet is an example of how you may want to use these selectors to customize the element to your brand.
Modifying the sizing or positioning of the iframe is currently not supported. Change those properties at your own risk; a moved or resized iframe is not guaranteed to work with upcoming releases of the ASAPP platform
Customize the Chat UI
ASAPP will customize the Chat SDK iframe User Interface (UI) in close collaboration with design and business stakeholders. ASAPP will work within your branding guidelines to apply an appropriate color palette, logo, and typeface. There are two particularly technical requirements that we can assess early on to provide a more seamless delivery of requirements:
1. Chat Header Logo
The ASAPP SDK Team will embed your logo into the Chat SDK Header. Please provide your logo in the following format:
- SVG format
- Does not exceed 22 pixels in height
- Does not exceed 170 pixels in width
- Should not contain animations
- Should not contain filter effects
If you follow the above guidelines your logo will:
- display at the most optimal size for responsive devices
- sit well within the overall design
- display properly
2. Custom Typefaces
Using a custom typeface within the ASAPP Chat SDK requires detailed technical requirements to ensure that the client is performant, caching properly, and displaying the expected fonts. For the best experience, you should provide ASAPP with the following:
- The font should be available in any of the following formats: WOFF2, WOFF, OTF, TTF, and EOT.
- The font should be hosted in the same place that your own site’s custom typeface is hosted.
- The same hosted font files should have an
Access-Control-Allow-Origin
that allowssdk.asapp.com
or*
. - The files should have proper cache-control headers as well as GZIP compression. For more information on web font performance enhancements, ASAPP recommends the article: Web Font Optimization, published by Google and Ilya Grigorik.
- You acknowledge that you will provide ASAPP with the URLs for each of the hosted font formats for use in a CSS @font-face declaration, hosted on sdk.asapp.com.
- If your font becomes unavailable for display, ASAPP will default to using Lato, then Arial, Helvetica, or a default sans-serif font.
Dynamic Styling Configuration
The ASAPP Chat SDK supports dynamic styling through configuration. This allows you to customize the appearance of various chat components without requiring CSS modifications.
Incorporating Styling in the SDK
To dynamically apply styles based on the provided configuration, the SDK implements the following approach:
- Extract Styling Configurations: The SDK parses the
Chat.Styling
section of the configuration and identifies the defined styles for various elements. - Apply Styles Dynamically: The SDK targets elements based on their class names and applies inline styles dynamically, ensuring that the defined styles are reflected in real-time.
- Handle State-Based Styling: Elements that support different states (e.g., button with default and focus styles) have event listeners added dynamically to switch styles when users interact with them.
Configuration Schema
The enhanced configuration schema includes a Chat
section that supports styling, icons, and features:
Styling Configuration
The Chat.Styling
object allows you to customize the appearance of various chat elements:
Available Styling Options
QuickReplies: Customize quick reply buttons and their container
Container
: Scrollable container holding all quick reply buttonsButton
: Individual quick reply action buttons
ChatInput: Style chat input components
AttachmentButton.Icon
: Icon within the attachment buttonSendButton.Icon.Disabled
: Send button icon in disabled stateSendButton.Icon.Enabled
: Send button icon in enabled state
EwtSheet: Estimated Wait Time display styling
ProgressBar.Container
: Background container for progress barProgressBar.Line
: Active progress indicator lineContent
: Main content area stylingSecondaryText
: Secondary description textPrimaryText
: Primary time display textTextContainer
: Wrapper for text elementsButton
: Action buttons in EWT sheet
ActionSheet: Full screen modal action buttons
Buttons.Container
: Wrapper for all action buttonsButtons.Primary
: Primary action button stylingButtons.Secondary
: Secondary action button styling
NewQuestion: New question prompt styling
Container
: Container for new question UIContent.Text
: Text elements in promptContent.Icon
: Icon in new question UI
ChatBanner: Chat banner notifications
Container
: Banner containerText
: Main banner textWarning
: Warning variant stylingError
: Error variant stylingSuccess
: Success variant stylingIcon
: Icon variant styling
ChatMessagesView: Chat messages display
ScrollView
: Chat view for chat messages
Styling Example
Here is a comprehensive example that combines multiple styling options:
Custom Icons
The Chat.Icons
section allows you to specify custom SVG path data for key icons used within the chat interface.
Icon Configuration
The SDK supports using SVG d
path data to create customizable icons. You only need to provide the d
attribute value from your SVG:
Available Icons
- Minimize: Icon for minimizing the chat window
- Send: Icon for the send button
- NewQuestion: Icon for starting a new question
- ChatBanner: Icon for chat banner notifications
Make sure to size your icons correctly. You may use an online SVG editor to resize your icons to meet the chat interface specifications.
Advanced Configuration Options
Chat Features
The Chat.Features
section controls the availability of specific chat features:
Estimated Wait Time (EWT)
Control whether the EWT feature is displayed:
Focus Trap
Enable focus trap within the chat instance for better accessibility: