客戶端 SDK(iOS、Android、React Native)
在自己的應用程式加入 GetMyBot 聊天、訊息與行動推播:連接、驗證使用者和離線運作。
本頁內容
SDK 是供應用程式開發者使用的函式庫,可加入客服聊天和應用程式內訊息(in-app 內容)。例如客戶從 iOS 應用程式提問,客服在同一個 GetMyBot 後台回覆,也能看到網站來的對話。
支援 iOS、Android 和 React Native。以下先介紹功能與專案設定,再說明程式碼、使用者驗證和技術契約。聊天使用機器人的網站頻道;應用程式內訊息使用內容工作室的文件。
SDK 提供什麼
- 註冊安裝:應用程式註冊一次,取得長期安裝權杖,保存在 Keychain 或 Android Keystore。
- 識別使用者:起初為匿名訪客;
identify後與已識別客戶資料合併,和其他 MyBot 介面共用對話歷史。 - 離線佇列:事件、客戶屬性、輸入狀態與推播權杖操作先存本機,恢復網路後按序批次送出。
- 聊天:與客服使用的同一對話提供歷史、發送、附件、未讀數與已讀游標。
- 即時更新:新訊息、編輯和刪除經 WebSocket 傳來,連接使用一次性 ticket。
- 應用程式內內容:展示內容工作室的彈出視窗,記錄展示、操作與轉換回執。
- 行動推播:註冊裝置權杖供群發和活動使用,實際送達依伺服器設定及有效權杖而定。
平台包括 iOS(Swift、iOS 15+、Objective-C facade 與可選 UI target)、Android(Kotlin、minSdk 24、Java facade)和React Native(TypeScript 包裝兩個原生 SDK)。三者使用同一規格和參考測試資料,見技術契約。
啟用專案
SDK 在後台對每個機器人單獨設定。啟用時指定允許的應用程式,並取得兩種資訊。
**應用程式清單。**填入 iOS bundle ID、Android package name,至少一項,兩種清單各最多 64 個。不在清單中的應用程式與未知專案金鑰得到完全相同的回應,無法藉此探測金鑰是否有效。
專案金鑰格式為 sdk1_eu_<24 hex>_<32 hex>。它像聊天小工具安裝金鑰一樣是公開的,可以放在應用程式內,但無法讀取對話或更改設定。金鑰中有區域供後台標示部署位置;SDK 原樣傳送,不自行解析。
身分密鑰完全不同,絕不可放進應用程式。啟用時只顯示一次,每次輪替也只顯示一次。請立即保存到自己後端的機密儲存空間;之後後台和 API 都不會再顯示。
輪替身分密鑰會建立新密鑰,並讓舊密鑰再有效一天,以供部署更新。專案金鑰不變,已安裝裝置仍可使用。
**撤銷裝置。**安裝清單最多顯示最近 200 筆,含平台、應用程式 ID、SDK 版本、語言、時區、是否已識別及最後活動時間。刪除一筆會立即撤銷該安裝的存取權。
**安裝暴增。**新安裝註冊會建立訪客,受與網站小工具相同的帳號限制;超出時回傳 429 和 Retry-After: 60。既有安裝以自己的權杖運作,不受新訪客限制。重新安裝或清除金鑰儲存空間會算新安裝,見網站小工具的新訪客限制。
部署密鑰 CUSTOMER_SDK_KEY_SECRET
這是第三種資訊,屬於整個 MyBot 部署,而非你的專案。專案金鑰由它簽署,SDK 每次啟動都會驗證。
若伺服器未設定 CUSTOMER_SDK_KEY_SECRET,安裝註冊會像未知金鑰一樣回傳 401,啟用新專案回傳 503。平台的正式部署必須設定,由自架或測試伺服器管理員確認。
**輪替部署密鑰會使所有先前發行的專案金鑰失效。**舊金鑰簽章不能用新密鑰驗證,也無法重新簽署已發行金鑰。應用程式將收到 401,只能發行含新專案金鑰的新版應用程式。因此應按不相容變更規劃,不能當一般例行密鑰輪替。身分密鑰不由部署密鑰簽署;它的一天重疊輪替不影響專案金鑰。
安裝與啟動客戶端
SDK 原始碼位於行動專案的 customer-sdk/:Swift package MyBotSDK(customer-sdk/ios)、命名空間 dev.gelfand.mybot.sdk 的 Gradle module mybot-sdk(customer-sdk/android)、npm package @mybot/customer-sdk-react-native(customer-sdk/react-native)。
啟動需專案金鑰、MyBot 部署的基底網址和應用程式 ID。每個 build 只使用一個主機,SDK 不會依金鑰中的區域另選網址。
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",
});
首次啟動註冊安裝並保存權杖,之後沿用。權杖只發一次;遺失或疑似洩漏時,SDK 可在原安裝更新權杖,保留其身分。
身分須由你的後端簽署
裝置不能自行宣稱使用者身分。你的後端先驗證使用者,再以身分密鑰簽署短效 JWT;應用程式只把這個不透明字串傳給 identify,SDK 不解析。
- 應用程式向你的後端取得已登入使用者身分。
- 後端建立短效簽章 JWT。
- 應用程式將 JWT 傳給
identify。
伺服器嚴格驗證,任何不符都會整份拒絕:
{
"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" }
}
- 演算法必須是
HS256、受眾必須是mybot-customer-sdk,不得含iss、sub、nbf。 jti為標準 UUIDv4;iat不可在未來;exp - iat不得超過 300 秒。user_id為你自己的穩定、不透明 ID(1–256 位元組),不是裝置表單輸入的原始 email 或電話。properties可省略,最多 16 項,只能使用封閉清單account_id、plan、role、locale,字串值最多 256 位元組。
對同一使用者重複 identify 是冪等操作;改識別另一使用者會轉移安裝。此 API 不接受原始聯絡資料,設定客戶資料和離線佇列屬性也使用同一封閉清單。
登出會提升身分版本
同一手機若先後由不同人登入,前一人的訊息不能以後一人身分發出。安裝會保存身分版本(epoch),從 1 開始,每次登出加 1;伺服器每次請求都驗證,立即拒絕舊版:
- 舊版離線操作被捨棄,客戶端刪除;伺服器也會整批拒絕。
- 本機序列號重新從 1 開始。
- 既有即時連線立即關閉;登出前發出的 ticket 不能再兌換。
- 舊版尚未完成的發送會取消。
- 伺服器在增加版本的同一交易內撤銷舊版推播權杖,應用程式不用自行記住。
- 清除與舊使用者相關的內容指派、未讀徽章和保存的客戶屬性快取。
WebSocket 握手不能帶一般請求所帶的身分版本標頭,所以 SDK 先透過 HTTPS 取得一次性 ticket;兌換時,伺服器重新從資料庫讀取安裝版本,與發出 ticket 時的版本比較。即使登出發生在兩者之間,連接也會被拒絕。更新權杖不等於登出,使用者與版本保留,上述清理不會執行。
離線佇列
離線操作在恢復網路後按序批次送出。每批帶客戶端 ID、身分版本與連續序號:
| 操作 | 用途 |
|---|---|
track_event | 記錄產品事件;實際名稱需符合較嚴格規則 ^[a-z][a-z0-9_.]{0,63}$ |
set_properties | 設定 account_id、plan、role、locale 中的客戶屬性 |
register_push_token | 加密保存 APNs 或 FCM 權杖,區分 sandbox / production |
revoke_push_token | 撤銷權杖;未知權杖也視為成功 |
notification_opened | 盡力記錄通知開啟 |
in_app_impression、in_app_action | 單一應用程式內內容指派的回執 |
typing | 聊天輸入中狀態 |
每批 1–100 項,序號必須接續上一批,缺口或重疊會整批拒絕。相同安裝與版本已接受的批次 ID 會回「重複」,不重做操作,遺失回應後可安全重試。錯誤版本整批拒絕;其他錯誤則以封閉代碼逐項回報,一個壞屬性不會丟掉其他有效事件。
三平台本機上限一致,最舊的待送操作先被移除:每安裝最多 2,000 項、佇列序列化大小 2 MiB、保存最多 7 天。正在發送的操作永不移除。每次移除會觸發診斷 callback,僅含本機 ID 和原因(項數、大小或年齡),不含操作內容。失敗發送從 30 秒開始指數退避,最多 240 秒,使用完整隨機偏移;驗證拒絕不重試。
聊天
當網站與應用程式的連結歷史功能可用且已啟用時,iOS 和 Android SDK 可以分頁讀取網站歷史及一般附件的中繼資料,並下載不超過 32 MiB 的檔案。下載需要有效的已驗證工作階段;不提供公開檔案連結。目前不支援私人轉傳。歷史以分頁讀取;此方式不提供共用即時更新,也不會自動將對話標記為已讀。
連結歷史區域開啟時,網站小工具會定期檢查應用程式的新訊息,以及已載入訊息的編輯和刪除。行動應用程式可以透過明確的 SDK 呼叫檢查更新;SDK 不會啟動背景輪詢。這是定期檢查,並非完整的共用即時功能。各管道的已讀狀態與通知仍然獨立。
在 iOS 使用 linkedWebHistorySnapshot,在 Android 使用 getLinkedWebHistorySnapshot 取得初始快照。將 mutationCursor 與 page.nextAfter 分開儲存。需要時使用兩個游標和最多 500 個已顯示訊息 ID 呼叫 linkedWebHistoryUpdates / getLinkedWebHistoryUpdates。如果 hasMutations 為 true,使用 through 重新讀取顯示範圍,保留原有頁面邊界並處理刪除。如果初始頁面為空且沒有 nextAfter,請將 nil/null 或空字串作為 after:SDK 會從 0 開始檢查。舊伺服器可能不回傳 mutationCursor;登出後應丟棄游標。
若要在行動應用程式中確認訊息已顯示,請在 iOS 明確呼叫 markLinkedWebHistorySeen(messageIds:),或在 Android 呼叫 markLinkedWebHistorySeen(messageIds)。最多傳入 500 個 ID,且僅限實際顯示給訪客的工作人員來信(direction: "in")。連結歷史區域開啟且可見時,網站小工具會自動標記可見訊息。這可能取消尚未寄出的未讀回覆備援郵件,但無法撤回已寄出的郵件,也不會同步 SDK 聊天的未讀計數。
若要取得連結網站歷史中沒有確認檢視標記的訊息獨立計數,應用程式可在 iOS 呼叫 linkedWebUnreadCount(),或在 Android 呼叫 getLinkedWebUnreadCount()。此計數包括確認連結後建立且未標記為已檢視的工作人員訊息。標記實際顯示的訊息後,下次結果會相應變更。主要 SDK 聊天中的閱讀可能不會反映在此計數中,因此它不是精確的未讀計數。nil/null 表示伺服器不支援此計數,並非零。此計數獨立於 SDK 聊天的主要未讀計數,不會在背景或透過 push 自動更新;應用程式自行決定何時要求。
當網站與 SDK 的連結在伺服器上可用且已啟用時(WEB_SDK_LINK_ENABLED,預設關閉),可以檢視兩份歷史的合併快照。一般聊天仍可使用,操作員看到的對話仍然獨立。快照依最新訊息優先回傳,透過不透明的 nextCursor 分頁,並包含安全內容區塊和一般附件中繼資料。unsupportedBlocks: true 表示部分內容被省略;不支援私人轉傳。使用 downloadMergedHistoryAttachment 經授權下載附件。
若要保留合併快照,請在 iOS 使用 versionedMergedWebHistory,在 Android 使用 getVersionedMergedWebHistory。比較各頁的 linkVersion,並在重新顯示已儲存歷史之前及返回應用程式後,透過 mergedHistoryLinkVersion / getMergedHistoryLinkVersion 明確檢查。如果版本變更或無法驗證存取權限,請清除已儲存的頁面、游標及附件;登出後它們也會失效。合併檢視不提供共用即時功能,不會將訊息標記為已檢視,也不會啟動背景輪詢。
合併快照開啟且可見時,小工具會定期檢查變化並提示手動重新整理歷史。此訊號是盡力而為的檢查,並非有保證的事件佇列或即時功能;操作員對話仍然獨立。
在行動應用程式中,使用 iOS 的 observableMergedWebHistory 或 Android 的 getObservableMergedWebHistory 取得第一頁,並儲存其中不透明的 updatesBaseline。若缺少此值,伺服器不支援此檢查。需要時,使用該 baseline 和最多 500 個已顯示訊息 ID 呼叫 mergedWebHistoryChanges / getMergedWebHistoryChanges。hasNew 表示有新訊息,hasChanged 表示所傳 ID 中有編輯或刪除;回應不包含訊息內容。這些檢查盡力而為,可能遺漏並行提交的變更;值為 false 不保證快照是最新的。需要最新資料時請重新整理歷史。將 linkVersion 與快照比較,若不同或無法驗證存取權限,則清除頁面、游標及附件。重新整理後再次取得第一頁及新的 baseline。SDK 不會啟動背景輪詢。
聊天是手機上的機器人網站頻道:與客服共用訊息、收件匣和發送時的自動化觸發器。
- 歷史:依游標向後取得,每頁最多 50 則。
direction以客戶端為準,in表示來自客服或機器人。 - 發送:帶客戶端訊息 ID,回覆「已排入佇列」,意為接受送達工作,不代表已送達。真實狀態由即時通道或下次歷史讀取取得。同 ID 同文字重試不重發,不同文字則衝突並標示應用程式錯誤。
- 附件:逐檔上傳,最多 10 MiB;在同一機器人內依內容雜湊去重,回傳可用連結。
- 未讀:每個安裝依自身已讀游標計算,與客服已讀分開;游標只往前移。
- 即時:傳新訊息、編輯、刪除和輸入狀態。連上時補送離線期間最多 50 個事件,再串流後續事件;客戶端沒有重連游標。
若機器人未連接網站頻道,所有聊天路由都會回覆功能不可用。應在介面視為關閉的功能,而非暫時性錯誤。
應用程式內內容
GET /sdk/v1/content 回傳已指派的內容:型別、優先序、延遲、造訪與頻率規則、區塊和外觀。空清單是正常結果。
顯示由目標規則決定。裝置規則未包含手機的彈出視窗絕不送給 SDK;完全沒有裝置規則者視為所有裝置。版本依使用者決定性指派,因此匿名使用者保持同一版本,直到 identify 或登出後重新計算。
回執有 impression、action、conversion 三種。被訪客滑掉的訊息只取得客戶端終止狀態,不會建立伺服器事件,與網站被關閉的彈出視窗相同。
行動推播權杖
register_push_token 將 APNs 或 FCM 權杖加密保存至目前安裝和身分版本,revoke_push_token 撤銷它。未知權杖的撤銷也算成功,避免藉回應探測他人的權杖。安裝資料參與使用者匯出和刪除,但權杖本身不匯出。
SDK 設定的 pushEnabled: true 表示平台支援行動推播。真正發送需部署管理員設定 FCM;若 APNs 已設定,iOS 可直接送達。已發佈 Push 文件可透過群發或活動的 mobile_push 頻道發送。後台客服通知的受眾和裝置儲存與此不同。
登出時,伺服器撤銷舊身分版本的有效推播權杖;重新登入後應重新註冊。只有仍有效的安裝與權杖可接收。
錯誤
所有 /sdk/v1 錯誤都是單欄位 JSON 封裝,SDK 依 HTTP 狀態分類:
| 狀態 | 意義 | SDK 行為 |
|---|---|---|
400 | 本機輸入錯誤 | 不重試,顯示客戶端錯誤 |
401 | 驗證阻擋,如舊版本、已撤銷權杖、未知專案、已用 ticket | 不用同一憑證重試 |
404 | 未知或其他人的內容指派 | 永久移除 |
409 | 機器人聊天不可用或冪等衝突 | 顯示,不重試 |
413 | 附件超過 10 MiB | 立即顯示 |
500、503 | 暫時性錯誤 | 冪等操作延後重試 |
隱私與診斷
SDK 路由不回傳原始聯絡資料,屬性從頭到尾使用封閉清單。診斷預設關閉;開啟後也只包含封閉清單中的事件代碼、時間戳記及經清理的數值中繼資料,絕不含權杖、身分宣告、推播權杖、連結,或訊息、屬性、內容本文。SDK 安裝資料屬 sdk_diagnostics 保存類別,預設 180 天,並參與訂閱者合併、匯出與刪除。
技術契約
SDK 協定與擁有者 REST API分開。個人權杖不能用於 /sdk/v1,安裝權杖不能用於 /api。OpenAPI 路由文件可免驗證取得:
GET https://你的部署/sdk/openapi.yaml
客戶端行為規則在行動專案的 customer-sdk/contract/behavior.md:狀態轉換、操作順序、佇列上限、重試延遲與錯誤處理。旁邊有自動取得的伺服器結構、列舉、限制和樣式,以及 75 個參考測試 fixture。腳本會從後端副本重新取得結構,指出契約未收錄的變更;iOS、Android、React Native 測試共用同一組範例。
API 與 MCP
個人權杖可呼叫專案管理路由,見 REST API。讀取需要 customer_sdk:read 範圍和機器人的 customer_sdk.read 權限;寫入需要 customer_sdk:write 和 customer_sdk.write,啟用專案和輪替密鑰還需要 integrations.secrets。MCP 提供兩個唯讀工具,見 MCP。