SDK khách hàng (iOS, Android, React Native)
Thêm chat, nội dung trong ứng dụng và push di động GetMyBot vào app của bạn; xác minh người dùng và hoạt động ngoại tuyến.
Trên trang này
SDK là thư viện cho người phát triển ứng dụng. Nó thêm chat hỗ trợ và tin hiển thị trong ứng dụng (in-app). Khách có thể viết từ app iOS, còn nhân viên trả lời trong cùng hộp thư GetMyBot với khách website.
Có SDK iOS, Android và React Native. Bên dưới là khả năng, cấu hình dự án, mã khởi tạo, xác minh người dùng và giao thức. Chat dùng kênh web của bot; in-app dùng tài liệu từ Studio nội dung.
SDK làm gì
- Đăng ký bản cài một lần, nhận token dài hạn và giữ trong Keychain hoặc Android Keystore.
- Nhận dạng người dùng: ban đầu ẩn danh; sau
identify, bản cài gắn với người đã xác minh và chia sẻ lịch sử với hồ sơ của họ. - Xếp hàng khi ngoại tuyến: sự kiện, thuộc tính hồ sơ, trạng thái đang gõ và thao tác push token được lưu tại máy rồi gửi theo lô đúng thứ tự khi có mạng.
- Chat: lịch sử, gửi tin, tệp, số chưa đọc và vị trí đã đọc trên cùng hội thoại của nhân viên.
- Cập nhật tức thời: tin mới/sửa/xóa qua WebSocket với ticket dùng một lần.
- In-app: nội dung Pop-up với biên nhận hiển thị, thao tác và chuyển đổi.
- Push di động: đăng ký token cho đợt gửi/chiến dịch; giao nhận cần máy chủ được cấu hình và token còn hiệu lực.
Hỗ trợ iOS (Swift, iOS 15+, có facade Objective-C và UI target tùy chọn), Android (Kotlin, minSdk 24, facade Java) và React Native (TypeScript trên hai SDK gốc). Cả ba theo một giao thức chung và bộ dữ liệu kiểm tra tham chiếu.
Bật dự án SDK
Mỗi bot có màn hình SDK riêng. Khi bật, bạn chỉ định ứng dụng được phép và nhận hai giá trị.
Danh sách ứng dụng: bundle ID iOS và package name Android. Cần ít nhất một mục để tạo dự án, tối đa 64 mục trong mỗi danh sách. App ngoài danh sách nhận cùng câu trả lời như khóa dự án không biết, để không suy ra khóa đúng hay sai.
Khóa dự án dạng sdk1_eu_<24 hex>_<32 hex> là công khai như khóa cài widget. Đặt trong bản build là bình thường; nó không cho đọc chat hay sửa bot. Vùng trong khóa giúp giao diện cho biết nơi triển khai, SDK gửi nguyên chuỗi và không tự phân tích nó.
Bí mật định danh hoàn toàn khác, không đưa vào app. Nó chỉ hiện một lần khi bật và sau mỗi lần xoay. Hãy lưu ngay vào kho bí mật của backend; giao diện/API không hiển thị lại.
Xoay bí mật định danh tạo khóa mới, giữ khóa cũ thêm một ngày cho bạn triển khai. Khóa dự án và thiết bị đã cài không đổi. Danh sách bản cài (tối đa 200 gần đây) hiển thị nền tảng, app ID, phiên bản SDK, ngôn ngữ, múi giờ, người đã nhận dạng hay chưa và lần hoạt động cuối. Thu hồi một bản cài sẽ ngắt quyền ngay.
Đăng ký bản cài mới tạo khách truy cập nên chịu giới hạn tăng đột ngột theo tài khoản giống widget: 429 với Retry-After: 60. Bản cài đã đăng ký dùng token riêng nên không chịu giới hạn đó; cài lại hoặc mất kho khóa được tính là mới. Xem Khách mới tăng đột ngột.
Bí mật triển khai CUSTOMER_SDK_KEY_SECRET
Đây là giá trị thứ ba, thuộc toàn bộ triển khai MyBot chứ không thuộc dự án của bạn. Khóa dự án được ký bằng bí mật này và kiểm tra chữ ký mỗi lần SDK khởi động.
Nếu CUSTOMER_SDK_KEY_SECRET trống, đăng ký bản cài trả 401 như khóa dự án không biết, bật dự án mới trả 503. Quản trị viên máy chủ riêng/test phải cấu hình nó.
Đổi bí mật triển khai làm mọi khóa dự án cũ mất hiệu lực. Không thể ký lại khóa đã phát vì nó được lưu kèm chữ ký. App dùng khóa cũ sẽ nhận 401; cách khắc phục là cấp khóa dự án mới và phát hành bản build mới lên store. Hãy xem đây là thay đổi không tương thích. Bí mật định danh không liên quan: xoay nó có một ngày dùng song song và không ảnh hưởng khóa dự án.
Cài đặt và khởi tạo client
Mã SDK ở customer-sdk/ trong repo di động: Swift package MyBotSDK (customer-sdk/ios), Gradle module mybot-sdk với namespace dev.gelfand.mybot.sdk (customer-sdk/android), npm package @mybot/customer-sdk-react-native (customer-sdk/react-native).
Client cần khóa dự án, base URL của triển khai và app ID. Mỗi build dùng một host; SDK không tự đổi vùng bằng cách đọc khóa.
let client = try await MyBotClient.start(
configuration: Configuration(
projectKey: "sdk1_eu_…",
baseURL: URL(string: "https://api.getmybot.dev")!,
appIdentifier: "dev.getmybot.example",
sdkVersion: "1.0.0"
)
)
val client = MyBotClient.start(
context,
MyBotConfiguration(
projectKey = "sdk1_eu_…",
baseUrl = "https://api.getmybot.dev",
),
)
const client = await MyBotClient.start({
projectKey: "sdk1_eu_…",
baseURL: "https://api.getmybot.dev",
appIdentifier: "dev.getmybot.example",
});
Lần đầu tạo bản cài và lưu token; các lần sau tiếp tục bản cài đó. Token chỉ được cấp một lần; nếu mất hoặc nghi lộ, SDK làm mới tại chỗ mà không đổi danh tính.
Danh tính do backend của bạn ký
Thiết bị không được tự tuyên bố người dùng là ai. Nhận dạng là khẳng định được backend của bạn ký bằng bí mật định danh; app chỉ chuyển chuỗi:
- App hỏi backend của bạn ai đang đăng nhập.
- Backend đã xác thực người đó tạo JWT ngắn hạn và ký.
- App gửi JWT cho
identify; SDK không giải mã nó.
Máy chủ xác thực nghiêm ngặt, sai một điều sẽ từ chối toàn bộ:
{
"alg": "HS256",
"project_key": "sdk1_eu_…",
"aud": "mybot-customer-sdk",
"jti": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"iat": 1730000000,
"exp": 1730000120,
"user_id": "acct_10293",
"properties": { "plan": "pro", "role": "admin" }
}
- Chỉ
HS256, audience đúngmybot-customer-sdk; không cóiss,sub,nbf. jtilà UUIDv4 chuẩn;iatkhông ở tương lai;exp - iattối đa 300 giây.user_idlà ID ổn định do bạn đặt, 1–256 byte, không phải email/điện thoại thô nhập trên thiết bị.propertiestùy chọn, tối đa 16 mục, chỉaccount_id,plan,role,locale, giá trị chuỗi tối đa 256 byte.
Gọi identify lặp cho cùng người không tạo trùng; gọi cho người khác chuyển bản cài sang người đó. API này không nhận liên hệ thô. Danh sách thuộc tính đóng cũng áp dụng cho endpoint hồ sơ và thuộc tính từ hàng đợi.
Đăng xuất tăng phiên danh tính
Khi nhiều người dùng chung điện thoại, tin của người trước không được gửi dưới người sau. Bản cài có phiên danh tính (identity epoch), bắt đầu từ 1, tăng mỗi lần đăng xuất. Máy chủ kiểm tra nó ở mọi yêu cầu và từ chối phiên cũ ngay:
- Thao tác hàng đợi phiên cũ bị bỏ; client xóa chúng, máy chủ cũng từ chối cả lô.
- Số thứ tự cục bộ bắt đầu lại từ 1.
- WebSocket đang mở đóng ngay; ticket trước đăng xuất không dùng được.
- Lần gửi còn dở của phiên cũ bị hủy.
- Máy chủ thu hồi push token phiên cũ trong cùng giao dịch tăng phiên; app không phải tự nhớ.
- Xóa cache gắn với người trước: phân bổ nội dung, số chưa đọc và thuộc tính hồ sơ.
WebSocket handshake không mang header phiên như HTTP thông thường. SDK lấy ticket một lần qua HTTPS; khi dùng ticket, máy chủ đọc lại phiên trong database và so với phiên lúc phát. Đăng xuất xảy ra giữa hai bước sẽ chặn kết nối, dù ticket chưa dùng. Làm mới token không phải đăng xuất: phiên và người dùng giữ nguyên, không chạy các bước xóa này.
Hàng đợi ngoại tuyến
Thao tác lưu khi mất mạng được gửi theo lô có thứ tự. Mỗi lô mang ID client, phiên và dãy số liên tục.
| Thao tác | Chức năng |
|---|---|
track_event | Ghi sự kiện sản phẩm; tên theo ^[a-z][a-z0-9_.]{0,63}$, quy tắc nghiêm hơn trong hai bước kiểm tra |
set_properties | Đặt thuộc tính trong account_id, plan, role, locale |
register_push_token | Lưu token APNs/FCM mã hóa, môi trường sandbox hoặc production |
revoke_push_token | Thu hồi; token không biết vẫn trả thành công để tránh dò tìm |
notification_opened | Ghi mở thông báo theo best effort |
in_app_impression, in_app_action | Biên nhận cho một lần gán nội dung |
typing | Trạng thái đang gõ trong chat |
Quy tắc máy chủ:
- Mỗi lô 1–100 thao tác, số thứ tự nối chính xác với lô được nhận cuối; thiếu hoặc chồng làm cả lô bị từ chối.
- Lô có ID đã nhận cho cùng bản cài và phiên trả «trùng», không chạy lại; có thể gửi lại an toàn khi mất câu trả lời.
- Phiên sai từ chối cả lô; lỗi khác trả theo từng thao tác bằng mã từ danh sách đóng, nên một thuộc tính sai không hủy các sự kiện tốt.
Giới hạn cục bộ giống nhau trên ba nền tảng; mục chờ cũ nhất bị bỏ trước:
- 2.000 thao tác mỗi bản cài.
- 2 MiB dữ liệu hàng đợi đã tuần tự hóa.
- Tối đa 7 ngày tuổi, độc lập với hai giới hạn trên.
Mục đang gửi không bao giờ bị bỏ. Mỗi lần bỏ gọi callback chẩn đoán gồm ID cục bộ và lý do (số lượng, kích thước, tuổi), không có nội dung. Gửi lỗi được thử lại từ 30 giây, nhân đôi đến 240 giây với độ trễ ngẫu nhiên; lỗi xác thực không thử lại.
Chat
Khi lịch sử liên kết giữa trang web và ứng dụng khả dụng và được bật, SDK iOS và Android có thể đọc từng trang lịch sử web cùng siêu dữ liệu tệp đính kèm thông thường và tải tệp tối đa 32 MiB. Tải xuống yêu cầu phiên đã xác thực còn hiệu lực; không cung cấp URL tệp công khai. Chuyển tiếp riêng tư chưa được hỗ trợ. Lịch sử được đọc theo trang; cách này không cung cấp cập nhật thời gian thực chung hoặc tự đánh dấu cuộc trò chuyện là đã đọc.
Khi mục lịch sử liên kết đang mở, widget trên trang web định kỳ kiểm tra tin nhắn mới từ ứng dụng cũng như chỉnh sửa hoặc xóa các tin nhắn đã tải. Ứng dụng di động có thể kiểm tra cập nhật bằng các lệnh gọi SDK tường minh; SDK không tự thăm dò nền. Đây là kiểm tra định kỳ, không phải realtime chung đầy đủ. Trạng thái đã đọc và thông báo của từng kênh vẫn tách biệt.
Bắt đầu bằng linkedWebHistorySnapshot trên iOS hoặc getLinkedWebHistorySnapshot trên Android. Lưu mutationCursor tách biệt với page.nextAfter. Khi cần, gọi linkedWebHistoryUpdates / getLinkedWebHistoryUpdates với cả hai con trỏ và tối đa 500 ID tin nhắn đang hiển thị. Nếu hasMutations là true, tải lại phạm vi hiển thị bằng through, giữ ranh giới trang ban đầu và xử lý các mục đã xóa. Nếu trang đầu trống và không có nextAfter, truyền nil/null hoặc chuỗi rỗng cho after: SDK kiểm tra từ 0. Máy chủ cũ có thể không trả mutationCursor; xóa các con trỏ sau khi đăng xuất.
Để xác nhận đã hiển thị trong ứng dụng di động, hãy gọi tường minh markLinkedWebHistorySeen(messageIds:) trên iOS hoặc markLinkedWebHistorySeen(messageIds) trên Android. Chỉ truyền tối đa 500 ID của tin nhắn đến từ nhân viên (direction: "in") thực sự được hiển thị cho khách. Trong mục lịch sử liên kết đang mở và hiển thị, widget trên web tự đánh dấu các tin nhắn nhìn thấy. Việc này có thể hủy email dự phòng cho câu trả lời chưa đọc nếu email chưa được gửi, nhưng không thu hồi email đã gửi và không đồng bộ bộ đếm chưa đọc của chat SDK.
Để lấy bộ đếm riêng cho tin nhắn trong lịch sử web liên kết chưa có xác nhận đã xem, ứng dụng gọi linkedWebUnreadCount() trên iOS hoặc getLinkedWebUnreadCount() trên Android. Bộ đếm tính tin nhắn của nhân viên được tạo sau khi xác nhận liên kết và chưa được đánh dấu đã xem. Việc đánh dấu tin nhắn thực sự hiển thị ảnh hưởng đến kết quả lần sau. Việc đọc trong chat SDK chính có thể không được phản ánh, nên đây không phải bộ đếm chưa đọc chính xác. nil/null nghĩa là máy chủ không hỗ trợ bộ đếm, không phải bằng không. Bộ đếm này tách biệt với bộ đếm chưa đọc chính của chat SDK, không tự cập nhật trong nền hoặc qua push; ứng dụng tự quyết định khi nào yêu cầu.
Nếu liên kết trang web–SDK khả dụng và được bật trên máy chủ (WEB_SDK_LINK_ENABLED, mặc định tắt), có thể xem ảnh chụp chung của hai lịch sử. Chat thông thường vẫn khả dụng và nhân viên vẫn thấy các cuộc hội thoại riêng. Ảnh chụp trả về tin mới nhất trước, phân trang bằng nextCursor không trong suốt và chứa các khối an toàn cùng siêu dữ liệu tệp đính kèm thông thường. unsupportedBlocks: true nghĩa là một phần nội dung đã bị bỏ qua; chuyển tiếp riêng tư không được hỗ trợ. Tải tệp có xác thực bằng downloadMergedHistoryAttachment.
Để lưu ảnh chụp chung, dùng versionedMergedWebHistory trên iOS hoặc getVersionedMergedWebHistory trên Android. So sánh linkVersion giữa các trang và kiểm tra tường minh bằng mergedHistoryLinkVersion / getMergedHistoryLinkVersion trước khi hiển thị lại lịch sử đã lưu và sau khi quay lại ứng dụng. Nếu phiên bản thay đổi hoặc không xác minh được quyền truy cập, hãy xóa các trang, con trỏ và tệp đã lưu; đăng xuất cũng làm chúng mất hiệu lực. Chế độ xem chung không cung cấp realtime chung, không đánh dấu đã xem và không tự thăm dò nền.
Khi ảnh chụp chung đang mở và hiển thị, widget định kỳ kiểm tra thay đổi và đề nghị làm mới lịch sử thủ công. Đây là tín hiệu nỗ lực tối đa, không phải hàng đợi sự kiện được bảo đảm hay realtime; các cuộc hội thoại của nhân viên vẫn tách biệt.
Trong ứng dụng di động, gọi observableMergedWebHistory trên iOS hoặc getObservableMergedWebHistory trên Android để lấy trang đầu và lưu updatesBaseline không trong suốt của trang đó. Nếu thiếu giá trị này, máy chủ không hỗ trợ kiểm tra. Khi cần, gọi mergedWebHistoryChanges / getMergedWebHistoryChanges với baseline đó và tối đa 500 ID tin nhắn đang hiển thị. hasNew báo tin nhắn mới và hasChanged báo chỉnh sửa hoặc xóa trong các ID được gửi; phản hồi không chứa nội dung tin nhắn. Việc kiểm tra này chỉ mang tính nỗ lực tối đa và có thể bỏ sót các thay đổi được ghi đồng thời; giá trị false không đảm bảo ảnh chụp đã cập nhật. Hãy làm mới lịch sử khi cần dữ liệu hiện tại. So sánh linkVersion với ảnh chụp và xóa trang, con trỏ cùng tệp đính kèm nếu khác hoặc không thể xác minh quyền truy cập. Sau khi làm mới, lấy trang đầu với baseline mới. SDK không tự thăm dò nền.
Chat là kênh web của bot trên điện thoại, cùng tin nhắn, hộp thư nhân viên và kích hoạt tự động.
- Lịch sử phân trang theo cursor, tối đa 50 tin một trang.
directionnhìn từ phía client:inlà tin từ nhân viên hoặc bot. - Gửi có ID tin do client đặt và trả «đã đưa vào hàng đợi», nghĩa là được nhận để giao, chưa phải đã giao. Trạng thái thật đến qua realtime hoặc lần đọc lịch sử sau. Gọi lại cùng ID và văn bản không tạo trùng; cùng ID nhưng văn bản khác là xung đột ứng dụng.
- Tệp tải từng tệp tối đa 10 MiB, loại trùng theo hash trong cùng bot và trả URL sẵn dùng.
- Chưa đọc tính riêng theo cursor của từng bản cài, tách khỏi lượt đọc của nhân viên; cursor chỉ tiến tới.
- Realtime truyền tin mới/sửa/xóa và trạng thái đang gõ. Khi nối lại, máy chủ gửi tối đa 50 khung đã lỡ rồi phát trực tiếp; client không có cursor reconnect.
Nếu bot chưa có kênh web, mọi endpoint chat trả chat không khả dụng. Hãy trình bày như tính năng tắt, không phải lỗi tạm thời.
Nội dung trong ứng dụng
GET /sdk/v1/content trả các mục đã gán: loại, ưu tiên, độ trễ, quy tắc lượt ghé/tần suất, khối và giao diện. Danh sách rỗng là bình thường.
Nhắm mục tiêu quyết định ai nhận. Pop-up loại thiết bị di động không bao giờ vào SDK; không cấu hình loại thiết bị nghĩa là mọi thiết bị. Phương án được gán xác định theo người, nên khách ẩn danh thấy cùng phương án cho đến khi identify hoặc đăng xuất khiến phân bổ tính lại.
Biên nhận gồm impression, action, conversion. Khách vuốt bỏ tin tạo trạng thái kết thúc chỉ ở client, không có sự kiện máy chủ, như pop-up bị đóng trên website.
Push di động
register_push_token lưu token APNs/FCM cho bản cài và phiên hiện tại dưới dạng mã hóa; revoke_push_token thu hồi. Thu hồi token không biết cũng thành công để không thể dò token của người khác. Dữ liệu bản cài tham gia xuất/xóa dữ liệu khách, nhưng token thô không có trong bản xuất.
Cấu hình SDK có pushEnabled: true nghĩa là nền tảng hỗ trợ giao push. Để gửi thật, quản trị viên phải cấu hình FCM; nếu có APNs, iOS có thể được gửi trực tiếp. Tài liệu Push đã xuất bản gửi qua kênh mobile_push trong gửi hàng loạt hoặc chiến dịch. Thông báo cho nhân viên trong GetMyBot có đối tượng và kho thiết bị khác.
Khi đăng xuất, máy chủ thu hồi push token của phiên cũ. Sau đăng nhập mới, app đăng ký token lại. Chỉ bản cài hoạt động với token còn hiệu lực mới nhận.
Lỗi
Mỗi lỗi /sdk/v1 là JSON envelope một trường; SDK phân loại theo HTTP:
| Trạng thái | Ý nghĩa | SDK xử lý |
|---|---|---|
400 | Đầu vào cục bộ sai | Không thử lại, hiện lỗi client |
401 | Chặn xác thực: phiên cũ, token bị thu hồi, dự án lạ, ticket đã dùng | Không thử lại với cùng thông tin xác thực |
404 | Nội dung được gán không có hoặc thuộc người khác | Bỏ như không còn hợp lệ |
409 | Chat không khả dụng hoặc xung đột chống trùng | Hiện, không thử lại |
413 | Tệp lớn hơn 10 MiB | Hiện trước khi thử lại |
500, 503 | Lỗi tạm | Thử lại với khoảng nghỉ cho thao tác chống trùng |
Riêng tư và chẩn đoán
Endpoint SDK không trả liên hệ thô, từ điển thuộc tính đóng. Chẩn đoán mặc định tắt; khi bật, nó chỉ chứa mã sự kiện từ danh sách đóng, thời gian và metadata số đã lọc, không bao giờ có token, JWT danh tính, push token, URL hoặc nội dung tin/thuộc tính. Bản cài SDK thuộc nhóm lưu giữ sdk_diagnostics mặc định 180 ngày, tham gia hợp nhất hồ sơ, xuất và xóa dữ liệu.
Giao thức
Giao thức SDK tách khỏi REST API của chủ bot. PAT không dùng cho /sdk/v1, token bản cài không dùng cho /api. OpenAPI của SDK công khai:
GET https://your-deployment/sdk/openapi.yaml
Quy tắc client nằm trong customer-sdk/contract/behavior.md của repo di động: trạng thái, thứ tự thao tác, giới hạn hàng đợi, độ trễ thử lại và lỗi. Bên cạnh có mô tả tự lấy từ server về cấu trúc, enum, giới hạn, mẫu cùng 75 fixture tham chiếu.
Script lấy lại mô tả từ backend checkout và báo thay đổi chưa cập nhật hợp đồng. Kiểm tra iOS, Android và React Native dùng cùng fixture để xác nhận hành vi giống nhau.
API và MCP
Các endpoint quản lý dự án dùng PAT ở REST API. Đọc cần scope customer_sdk:read và quyền customer_sdk.read của bot. Ghi cần customer_sdk:write và customer_sdk.write; bật dự án và xoay bí mật còn cần integrations.secrets. MCP có hai công cụ chỉ đọc; xem MCP.
Bước tiếp theo
- Widget trên website: cùng hội thoại trên site.
- Web Push: thông báo cho khách website.
- Studio nội dung: tài liệu in-app.