@isartech/chat
Version:
A reusable native webcomponent that can be initiated with parameters such as an endpoint url and styles in any environment based on web technologies.
320 lines (242 loc) • 8.41 kB
Markdown
In the following sections we descirbe different methods of installing the Isartech Chat library. The chat frontend is deployed as a [web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) and can be integrated into most frontend frameworks such as react, angular, vue.js etc. Isartech Chat is primarily delivered as a Javascript Module Library available at: [@isartech/chat](https://www.npmjs.com/package/@isartech/chat). This library delivers a single web component as an entry point to configuring your assistant.
The Isartech Chat library can be configured using HTML attributes. Events can be subscribed/listened too through HTML event listeners and finally component state can be updated through a set of public methods provided by the Isartech Chat class.
When importing the `<isartech-chat>` component via the @isartech/chat library a new custom element gets automatically registered to the [CustomElementRegistry](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry). Once the component is registered you can use the isartech-chat HTML element anywhere in your document.
Install the component via npm:
```bash
npm install @isartech/chat
```
Acces via a CDN:
```
https://esm.sh/@isartech/chat
```
We recommend this method to include `isartech-chat` in your application.
To install Isatech Chat as an ESM module you can add a module script to your project. Below is an example html page that imports the `isartech-chat` component.
```html
<!-- Imported via the esm.sh CDN -->
<body>
<isartech-chat id="it-chat" isartechId="gCf8B6BB" isartechKey="8PcQcnGPfsKhvs75255ymtUu"> </isartech-chat>
<script type="module" src="https://esm.sh/@isartech/chat"></script>
</body>
```
```html
<!-- Imported via the esm.sh CDN -->
<body>
<isartech-chat id="it-chat" isartechId="gCf8B6BB" isartechKey="8PcQcnGPfsKhvs75255ymtUu" districtId="273"> </isartech-chat>
<script type="module">
import IsartechChat from "https://esm.sh/@isartech/chat";
</script>
</body>
```
```jsx
// If react is not already imported it needs to be added separately
// Installed via npm install @isartech/chat
import 'react' from 'React';
import { IsartechChatReact as IsartechChat } from "@isartech/chat/react";
<IsartechChat
id="it-chat"
isartechId="gCf8B6BB"
isartechKey="8PcQcnGPfsKhvs75255ymtUu"
districtId="273"
></IsartechChat>
```
```jsx
import React from "react";
import { IsartechChatReact } from "@isartech/chat/react";
export const IsarTechChatReact = () => {
return (
<IsarTechChat
style={{ width: "400px", height: "800px" }}
id="it-chat"
districtId="273"
url="https://grocery.isartech.io"
enableHeader
></IsarTechChat>
);
};
```
Additionally to any properties of a `HTMLElement` The isartech component exposes the following attributes that can be configured.
| Name | Type | Example |
| ------------ | ------- | -------------------------- |
| isartechId | string | 'danube' |
| isartechKey | string | '8PcQcnGPfsKhvs75255ymtUu' |
| language | string | 'en' (or 'ar') |
| districtId | string | "273" for Al Qutbiyyah |
| enableHeader | boolean | true or false |
To interact with the Isartech Chat component there are a few public methods available. These can be used by getting a reference to the `isartech-chat` component and calling the methods on the reference variable.
Sets items in the shopping chart.
**Example:**
```typescript
const itChat = document.queryselector('isartech-chat#it-chat');
const orangeJuice: IsarTechProduct.Product = {
itemId: "35"
name: "Orange Juice",
price: 35,
quantity: 2,
};
const products = [orangeJuice];
// setProducts(products: IsartechChatProduct.Product[]): void
itChat.setProducts(products);
```
Sets items in the shopping chart.
Example:
```typescript
const itChat = document.queryselector("isartech-chat#it-chat");
// getCart(): IsarTechProduct.Product[]
const products = itChat.getCart(products);
```
Clears the shopping cart and removes all items.
Example:
```typescript
const itChat = document.queryselector("isartech-chat#it-chat");
// clearCart(): void
itChat.clearCart();
```
updates the quantity of an individual item in the cart
Example:
```typescript
const itChat = document.queryselector('isartech-chat#it-chat');
const orangeJuice: IsarTechProduct.Product = {
itemId: "35"
name: "Orange Juice",
price: 35,
quantity: 5,
};
// clearCart(): void
itChat.updateQuantity(orangeJuice);
```
Clears all messages and starts a new conversation.
Example:
```typescript
const itChat = document.queryselector("isartech-chat#it-chat");
// clearChat(): void
itChat.clearChat();
```
Get the users store location.
Example:
```typescript
const itChat = document.queryselector("isartech-chat#it-chat");
// getStoreLocation(): {
// district: defaultStore.state.districtId,
// supermarket: defaultStore.state.supermarket,
// country: defaultStore.state.country,
// deliveryMethod: defaultStore.state.deliveryMethod,
// }
const location = itChat.getStoreLocation();
```
Every time a user changes the quantity of an item a event is dispatched, which can be consumed through the `isartech-chat` element.
Example:
```typescript
const itChat = document.queryselector('isartech-chat#it-chat');
const handleQuantityChange = (ev: IsarTechProduct.ProductEvent) => {
const {
itemId,
name,
price,
quantity,
...
} = ev.detail;
// do something with the product event:
};
itChat.addEventListener('change-quantity', handleQuantityChange);
```
```typescript
export namespace IsarTech {
export enum LanguageCode {
English = "en",
Arabic = "ar",
}
export interface DeliveryMethod {
name: string;
slug: string;
}
export interface District {
id: number;
state_id: number;
country_id: number;
name: string;
}
export interface State {
id: number;
country_id: number;
name: string;
visible_districts?: District[];
}
export interface Country {
id: number;
name: string;
states: State[];
}
export interface Supermarket {
id: number;
name: string;
state: State;
district: District;
}
export interface StoreSelector {
delivery_methods: DeliveryMethod[];
supermarkets: Supermarket[];
countries: Country[];
states: State[];
districts_to_supermarkets: Record<string, number>;
selected_district_id: number;
selected_supermarket_id: number;
selected_delivery_method: string;
}
export interface StoreState {
language: LanguageCode;
history: Array<any>;
cart: Map<string, any>;
countryId?: string;
districtId?: string;
supermarketId?: string;
deliveryMethod?: string;
supermarket?: Supermarket;
country?: Country;
}
}
export namespace IsarTechProduct {
export const EVENT_CHANGE_QUANTITY = "change-quantity" as const;
export const ELEMENT_TAG = "it-product" as const;
export type Product = Attributes & { name: string };
export interface Attributes {
itemId: string;
quantity: number;
id?: string;
brand?: string;
price?: string;
priceUnit?: string;
weight?: string;
weightUnit?: string;
origin?: string;
slug?: string;
img?: string;
}
export interface WeihtedAttributes extends Attributes {
weight_increment: number;
max_weight_per_order: number;
min_weight_per_order: number;
default_weight_count: number;
}
export interface ProductEvent extends Event {
detail: Attributes | WeihtedAttributes;
}
export interface ProductEventMap {
ADD_EVENT: ProductEvent;
REMOVE_EVENT: ProductEvent;
}
}
```