GetMyBot 知識庫

客戶端 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 不解析。

  1. 應用程式向你的後端取得已登入使用者身分。
  2. 後端建立短效簽章 JWT。
  3. 應用程式將 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。

下一步