# Ứng dụng di động

Khách có thể chat với bạn ngay trong ứng dụng của bạn. SDK native mở màn hình chat trong ứng dụng, đồng bộ hội thoại và nhận thông báo đẩy. Tin nhắn của họ về cùng hộp thư với khách trên website. Trang này giải thích phần việc trong dashboard; các trang SDK hướng dẫn phần code.

## Ứng dụng kết nối thế nào

Mỗi ứng dụng di động gắn với một **website** (site) trong **Hỗ trợ → Kênh**. Ứng dụng dùng chung cài đặt của site đó, như giờ làm việc và trợ lý AI, và hội thoại của nó thuộc site đó trong báo cáo, quy tắc phân phối và tự động hoá.

Trình duyệt chứng minh mình đến từ đâu bằng `Origin`, và origin phải khớp tên miền hoặc danh sách origin được phép của site. Ứng dụng không có origin, nên nó gửi **khoá ứng dụng** thay thế:

- Mỗi ứng dụng có khoá riêng, bắt đầu bằng `hak_`. Bạn truyền khoá vào SDK cùng với site id.
- Khoá nằm trong bản build của ứng dụng, giống site id. Khoá chỉ dùng cho một site và thu hồi được, nên coi nó là thông tin công khai nhưng không nên phát tán.
- Khoá không mở được dữ liệu của bạn hay REST API. Lời gọi từ server dùng API key ([Xác thực](https://hatang.dev/vi/docs/guides/getting-started/authentication.md)).

## Tạo khoá ứng dụng

1. Vào **Hỗ trợ → Kênh → Thêm kênh → Ứng dụng di động**.
2. Nếu doanh nghiệp có nhiều site, chọn website mà ứng dụng thuộc về ở mục **Gắn kết nối mới vào site**.
3. Điền form:

   | Trường | Ghi chú |
   |---|---|
   | **Tên ứng dụng** | Để bạn phân biệt, ví dụ `Mộc Hương iOS` |
   | **Nền tảng** | iOS, Android, Flutter, React Native hoặc Khác |
   | **Bundle ID / package (tuỳ chọn)** | Mỗi dòng một giá trị, ví dụ `com.example.app`. Chỉ để ghi nhớ, hiện chưa dùng để kiểm tra |

4. Bấm **Tạo khoá ứng dụng**. Khoá chỉ hiện **một lần** ở trang tiếp theo, cạnh đoạn mã **Khởi tạo SDK**. Chép khoá vào cấu hình của ứng dụng.

Cũng có thể mở một website trong **Hỗ trợ → Kênh**, chuyển sang tab **Ứng dụng** và bấm **Thêm ứng dụng**.

## Cấu hình SDK

SDK nào cũng nhận hai giá trị: site id (`site_...`) và khoá ứng dụng (`hak_...`). Ví dụ với Flutter:

```dart
await HatangChat.configure(
  siteId: "site_...",
  appKey: "hak_...",
);
```

Làm theo hướng dẫn cho nền tảng của bạn: [Flutter](https://hatang.dev/vi/docs/guides/sdks/flutter.md), [iOS](https://hatang.dev/vi/docs/guides/sdks/ios.md), [Android](https://hatang.dev/vi/docs/guides/sdks/android.md) hoặc [React Native](https://hatang.dev/vi/docs/guides/sdks/react-native.md). Trang [Tổng quan SDK](https://hatang.dev/vi/docs/guides/sdks/overview.md) liệt kê mọi SDK và phiên bản được hỗ trợ.

Hai việc áp dụng cho mọi ứng dụng:

- **Nhận diện người dùng đã đăng nhập** để cùng một người thấy cùng lịch sử trên web và trong ứng dụng: [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md).
- **Thông báo đẩy** đi qua dự án Firebase của chính bạn. Tải tài khoản dịch vụ lên một lần cho mỗi website, ở tab **Ứng dụng** của website, mục **Thông báo đẩy (Firebase)**; khoá này dùng chung cho mọi ứng dụng của site. Xem [Thông báo đẩy](https://hatang.dev/vi/docs/guides/sdks/push-notifications.md).

## Trang của ứng dụng

Mỗi ứng dụng có trang riêng trong **Hỗ trợ → Kênh**: nền tảng, bundle ID, phần đầu của khoá, ngày tạo, lần kết nối gần nhất và số thiết bị đã đăng ký nhận thông báo đẩy. Trạng thái là **Chưa dùng** cho tới khi ứng dụng kết nối lần đầu, sau đó là **Hoạt động**, và **Đã tắt** khi khoá bị thu hồi.

## Thu hồi hoặc thay khoá

Bấm **Thu hồi** trên trang của ứng dụng khi khoá bị lộ hoặc khi một bản build không được kết nối nữa. Trong khoảng một phút, mọi bản cài dùng khoá đó bị từ chối với `app_key_revoked` (HTTP 403), và SDK không mở được phiên mới cho tới khi bạn phát hành bản build có khoá mới. Để đổi khoá:

1. Tạo khoá ứng dụng mới (thêm một ứng dụng nữa cho cùng website).
2. Phát hành bản build dùng khoá mới.
3. Thu hồi khoá cũ khi còn ít người dùng bản cũ, rồi bấm **Xoá**.

> **Caution**
>
> Thu hồi khoá sẽ chặn mọi bản cài còn dùng khoá đó, kể cả người chưa cập nhật ứng dụng. Hãy phát hành bản mới trước.

## Xử lý sự cố

| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| `invalid_app_key` (401) | Khoá gõ sai hoặc thuộc site khác | Lấy site id và khoá từ cùng một website |
| `app_key_revoked` (403) | Khoá đã bị thu hồi | Phát hành bản build có khoá mới |
| `product_disabled` (403) | Module Hỗ trợ đang tắt | Chủ sở hữu hoặc quản trị viên bật lại ([Bật/tắt module](https://hatang.dev/vi/help/getting-started/modules)) |
| Ứng dụng mãi ở trạng thái **Chưa dùng** | Ứng dụng chưa khởi tạo phiên với khoá này | Chạy ứng dụng và mở chat một lần; xem log của SDK |
| Không có thông báo đẩy | Website chưa có tài khoản dịch vụ Firebase, hoặc thiết bị chưa đăng ký | Tải tài khoản dịch vụ ở tab **Ứng dụng**; xem [Thông báo đẩy](https://hatang.dev/vi/docs/guides/sdks/push-notifications.md) |

## Bước tiếp theo

- [Tổng quan SDK](https://hatang.dev/vi/docs/guides/sdks/overview.md)
- [Cấu hình widget](https://hatang.dev/vi/docs/guides/support/web-widget/configuration.md): các cài đặt ứng dụng dùng chung với website
- [Realtime](https://hatang.dev/vi/docs/guides/support/realtime.md): SDK làm gì bên dưới

Source: https://hatang.dev/vi/docs/guides/support/mobile-apps