AiffJS 介面說明手冊

適用版本：AiffJS.version = "1.0.19"
依據檔案：aiff.js、aiff.min.js、README.md、原 AiffJs SDK 檔案說明.docx

1. 概述

AiffJS 是 Aiff 頁面與 Aile 宿主之間的 JavaScript 介面封裝。Aiff 頁面透過全域物件 AiffJS 呼叫宿主提供的 window.AileAPI 能力，例如初始化、取得目前使用者資料、取得開啟來源、開啟聊天室、傳送訊息、分享內容、取得位置、掃碼、修改標題等。

目前原始碼會在腳本載入後自動執行：

AiffJS._initEvent();

該初始化事件會註冊宿主側通知：

宿主事件	AiffJS 回呼	說明
`closeAiff`	`AiffJS.onCloseWindow(cancelFun)`	宿主要求關閉 Aiff 頁面時觸發
`aiffEvent`	`AiffJS.onAiffEvent(args)`	宿主主動傳送給 Aiff 頁面的事件

2. 快速開始

<script src="./aiff.min.js"></script>
<script>
  AiffJS.init("your-aiff-id").then(function (ok) {
    if (!ok) {
      return;
    }

    const profile = AiffJS.getProfile();
    const opener = AiffJS.getOpener();
    console.log(profile, opener);
  });
</script>

使用約定：

大多數介面需要先呼叫 AiffJS.init(aiffId) 且返回 true。
若宿主未提供 window.AileAPI，init 會返回 Promise<false>。
部分介面未初始化時返回 null，部分介面返回 { code: "Aiff.NotInit" }。具體以各介面說明為準。
返回內容最終由宿主端實現決定，本手冊中的欄位來自舊版說明書及當前原始碼封裝方式。

3. 版本記錄

版本	日期	說明
1.0.1	2021-08-30	整理 Aiff 說明，並加入通知事件描述
1.0.2	2021-11-23	調整 `getOpener` 返回內容，加入服務號聊天室欄位
1.0.3	2022-03-21	加入 `openContactChat` 等定義
1.0.4	2022-03-22	取消前端傳送聯絡人訊息介面
1.0.5	2022-04-21	根據 AiPower 討論調整介面，加入 `openBossContactChat`、`shareTargetPicker`
1.0.6	2022-06-25	新增 `openWindow`
1.0.7	2022-07	調整 `getClientType`，加入客戶端實現介面
1.0.8	2022-08-02	加入使用者資訊相關介面和 `getRoomStatus`
1.0.9	2022-08-16	`sendMessage` 加入 `type` 引數，支援 `text` 和 `template`
1.0.11	2022-09-22	加入 `getAiffItem`
1.0.12	2023-02-16	加入 `scanCode`、`getCurrentPosition`
1.0.13	-	加入 `shareMessage`、`sendCmd`、`openWindow`
1.0.14	-	加入分享相關介面
1.0.15	-	加入 `getNative`
1.0.16	-	調整 iframe 判斷，並加入 `sendData`
1.0.17	-	修正日誌判斷邏輯
1.0.18	-	新增 `subscribeCurrentPosition`、`startEvent`、`stopEvent`
1.0.19	2026-04-22	新增 `changeAiffTitle`，併相容歷史拼寫 `changeAiffTilte`

4. 介面總覽與應用支援狀態

支援狀態口徑：目前僅已完成 AileAPP（原 newaile）逐介面整理，依據 AileAPP 宿主橋接實作、模組文件與測試覆蓋標示為 已支援、有限制支援 或 暫不列入支援範圍。AileDesktop 目前可確認有 AIFF 槽位與上下文注入方向，但尚未完成逐介面驗證；AileProAPP、AileProDesktop 也尚未完成逐介面盤點，因此先標示為 待確認，避免把未知狀態誤判為不支援。

狀態說明：

狀態	說明
已支援	目前產品已有對應宿主能力或測試覆蓋，可作為對外使用口徑
有限制支援	目前產品支援，但受入口、聊天室上下文、權限或 payload 條件限制
暫不列入支援範圍	SDK 有介面或歷史相容入口，但目前產品支援矩陣不將其列為可用能力
待確認	尚未完成該產品逐介面驗證；不代表不支援

分類	介面	返回值	說明	AileAPP	AileDesktop	AileProAPP	AileProDesktop	備註
初始化	`init(aiffId)`	`Promise<boolean>`	初始化 Aiff	已支援	待確認	待確認	待確認
初始化	`getClientType()`	`string`	取得目前載具型別	已支援	待確認	待確認	待確認
初始化	`openDev()`	`void`	開啟宿主開發工具	已支援	待確認	待確認	待確認
基本資料	`getAuthToken()`	`string \| null`	取得目前鑑權 token	已支援	待確認	待確認	待確認
基本資料	`getAiffConfig()`	`Object \| null`	取得 Aiff 設定	已支援	待確認	待確認	待確認
基本資料	`getProfile()`	`Object \| null`	取得目前使用者資料	已支援	待確認	待確認	待確認
基本資料	`getOpener()`	`Object \| null`	取得目前開啟來源	已支援	待確認	待確認	待確認
基本資料	`getAiffItem(aiffKey)`	`Promise<Object>`	取得指定 Aiff 資料	已支援	待確認	待確認	待確認
聊天室	`openChat(roomId)`	`Promise<Object \| null>`	開啟指定聊天室	已支援	待確認	待確認	待確認
聊天室	`openUserChat(openId)`	`Promise<Object \| null>`	開啟指定同事聊天室	已支援	待確認	待確認	待確認	取決於宿主同事聊天室能力
聊天室	`getUserRooms(openId)`	`Promise<Object \| null>`	取得同事關聯聊天室	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
聊天室	`getAllRooms()`	`Promise<Object \| null>`	取得聊天室列表	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
聊天室	`openContactChat(serviceNumberId, openId)`	`Promise<Object \| null>`	開啟指定服務號下的客戶聊天室	已支援	待確認	待確認	待確認
聊天室	`openBossContactChat(openId)`	`Promise<Object \| null>`	開啟目前主管號下的客戶聊天室	已支援	待確認	待確認	待確認
聊天室狀態	`getRoomStatus(roomId = "")`	`Promise<Object>`	取得聊天室服務狀態	已支援	待確認	待確認	待確認
使用者資料	`getUser(openId, type = "")`	`Promise<Object>`	取得使用者資料	已支援	待確認	待確認	待確認
使用者資料	`getAvatar(openId, type = "")`	`Promise<Object>`	取得使用者頭像	已支援	待確認	待確認	待確認
訊息	`sendMessage(msgObj, type)`	宿主返回值或 `null`	傳送訊息到目前來源聊天室	已支援	待確認	待確認	待確認
訊息	`selectMessage(msgObj)`	宿主返回值或 `null`	將訊息放入輸入框等待傳送	已支援	待確認	待確認	待確認
訊息	`shareTargetPicker(templateObj, type)`	`Promise<Object>`	選擇聊天室或同事並分享模板訊息	有限制支援	待確認	待確認	待確認
訊息	`shareMessage(message)`	`Promise<Object>`	使用系統分享文字	已支援	待確認	待確認	待確認
訊息	`sendCmd(cmd)`	`Promise<Object>`	向宿主傳送命令	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
視窗	`openWindow(args)`	宿主返回值或 `null`	開啟 URL	已支援	待確認	待確認	待確認
視窗	`closeWindow()`	`true \| null`	關閉目前 Aiff	已支援	待確認	待確認	待確認
視窗	`changeAiffTitle(title)`	`Promise<Object>` 或宿主返回值	修改目前 Aiff 標題	已支援	待確認	待確認	待確認
視窗	`changeAiffTilte(title)`	`Promise<Object>` 或宿主返回值	歷史拼寫相容介面	已支援	待確認	待確認	待確認	建議新程式碼使用 `changeAiffTitle`
導航	`navigateToTab(mainAiffId, args = null)`	`void`	跳轉主框架內嵌 Aiff	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
裝置能力	`scanCode()`	`Promise<Object>`	啟動掃碼	已支援	待確認	待確認	待確認
裝置能力	`getCurrentPosition()`	`Promise<Object>`	取得目前位置	已支援	待確認	待確認	待確認
裝置能力	`subscribeCurrentPosition()`	`Observable`	訂閱位置變化	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
裝置能力	`startEvent(eventName)`	目前實作無穩定返回值	通知宿主啟動事件	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
裝置能力	`stopEvent(eventName)`	目前實作無穩定返回值	通知宿主停止事件	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
狀態	`sendAiffState(ibState)`	宿主返回值或 `null`	設定 Aiff 紅點狀態	已支援	待確認	待確認	待確認
狀態	`sendAiffStateNumber(iNumber)`	宿主返回值或 `null`	設定 Aiff 未讀數	已支援	待確認	待確認	待確認
原生資訊	`getNative()`	`Promise<Object \| null>`	取得宿主原生資訊	暫不列入支援範圍	待確認	待確認	待確認	目前不列入 AileAPP 對外支援能力
擴充	`sendData(data)`	`void`	向宿主傳送擴充資料	已支援	待確認	待確認	待確認
事件	`onCloseWindow(cancelFun)`	`void`	關閉前回呼	已支援	待確認	待確認	待確認
事件	`onAiffEvent(args)`	`void`	宿主通知回呼	已支援	待確認	待確認	待確認

5. 初始化與執行環境

5.1 `AiffJS.version`

當前版本號：

AiffJS.version // "1.0.19"

5.2 `init(aiffId)`

初始化當前 Aiff 頁面。

AiffJS.init(aiffId).then(function (ok) {
  if (ok) {
    // 初始化成功
  }
});

引數：

引數	型別	必填	說明
`aiffId`	`string`	否	建立 Aiff 設定時生成的唯一值，可為空

返回值：Promise<boolean>

返回	說明
`true`	宿主返回 `code === "Aiff.OK"`，初始化成功
`false`	無宿主環境，或宿主返回非成功狀態

初始化成功後，原始碼會儲存：

內部欄位	來源	說明
`_iniData.data`	宿主初始化結果	當前使用者資料
`_iniData.aiffItem`	宿主初始化結果	Aiff 設定
`_iniData.info`	宿主初始化結果	當前開啟來源

5.3 `getClientType()`

獲取當前載具型別。

const clientType = AiffJS.getClientType();

返回值：string

返回值	說明
`iframe`	當前頁面位於 iframe 中
`client`	未初始化，但存在 `window.AileAPI`
`other`	未初始化，且不存在 `window.AileAPI`
初始化結果中的 `data.clientType`	初始化成功後直接返回宿主給出的載具型別

舊文件中列出的常見載具型別：

值	說明
`aile`	Aile 客戶端
`aiwowo`	Aiwowo 客戶端
`uupon`	點數客戶端
`ios`	iOS Aile App
`android`	Android Aile App

5.4 `openDev()`

開啟宿主開發工具。

AiffJS.openDev();

返回值：無。若不存在 window.AileAPI，方法不執行宿主呼叫。

6. 當前使用者、Aiff 設定與開啟來源

6.1 `getAuthToken()`

獲取當前登入使用者的鑑權 token。

const token = AiffJS.getAuthToken();

返回值：

狀態	返回
已初始化	`_iniData.data.authToken`
未初始化	`null`

6.2 `getAiffConfig()`

獲取當前 Aiff 設定。

const config = AiffJS.getAiffConfig();

返回值：

狀態	返回
已初始化	`_iniData.aiffItem`
未初始化	`null`

常見欄位：

欄位	型別	說明
`id`	`string`	Aiff ID
`name`	`string`	Aiff 名稱
`title`	`string`	Aiff 顯示標題
`url`	`string`	Aiff Endpoint URL
`displayType`	`string`	顯示大小，`All` 全屏，`Half` 半屏
`userType`	`string`	應用客戶端，`employee` 員工端，`contact` 客戶端
`applyType`	`number`	應用方式，`1` 彈出應用，`2` 內嵌應用
`popupLocation`	`number`	彈出位置，`0` 訊息選單，`1` 聊天室 Menu，`2` 聊天室 Toolbar，`3` 主框架
`embedLocation`	`number`	內嵌位置，`0` 主框架，`1` 聊天室 title 下沉，`2` 物件下沉

6.3 `getProfile()`

獲取當前登入使用者資料。

const profile = AiffJS.getProfile();

返回值：

狀態	返回
已初始化	`_iniData.data`
未初始化	`null`

常見欄位：

欄位	型別	說明
`id`	`string`	當前使用者 ID
`nickName`	`string`	當前使用者暱稱
`imgSrc`	`string`	當前使用者頭像，Base64 圖片格式
`userType`	`string`	`employee` 員工，`contact` 客戶
`appType`	`string`	載具型別，例如 `client`、`ios`、`android`
`department`	`string`	當前使用者所屬部門
`authToken`	`string`	當前使用者鑑權 token
`openId`	`string`	當前使用者 openId
`tenantCode`	`string`	當前租戶編碼
`accountId`	`string`	CP 層級賬號；不可取時為空
`clientType`	`string`	客戶端型別，例如 `aile`、`aiwowo`、`uupon`

6.4 `getOpener()`

獲取當前觸發開啟 Aiff 的來源資訊。

const opener = AiffJS.getOpener();

返回值：

狀態	返回
已初始化	`_iniData.info`
未初始化	`null`

頂層欄位：

欄位	型別	說明
`openerType`	`string`	來源型別
`openerSource`	`string`	開啟位置
`id`	`string`	若來源為訊息，則為訊息 ID；否則通常為聊天室 ID；主框架觸發時為空
`roomId`	`string`	聊天室內觸發時為聊天室 ID，否則為空
`content`	`string`	訊息選單觸發時為訊息內容
`senderId`	`string`	訊息選單觸發時為傳送者 OpenID
`roomInfo`	`Object`	聊天室內觸發時存在
`objectInfo`	`Object`	物件 title 下沉觸發時存在
`userInfo`	`Object`	指定來源型別下存在

openerType 常見值：

值	說明
`mainFrame`	主框架開啟
`system`	系統聊天室
`self`	個人聊天室
`vistor`	訪客聊天室
`friend`	同事聊天室
`group`	社團聊天室
`discuss`	多人聊天室
`serviceMember`	服務號成員聊天室
`serviceSub`	服務號訂閱者聊天室
`serviceRoom`	服務號成員視角下的客戶聊天室
`unkonw`	未知，保留舊文件拼寫

openerSource 常見值：

值	說明
`roomToolbar`	聊天室 toolbar 觸發
`roomTitle`	聊天室 title 下沉觸發
`mainFrame`	主框架觸發
`objectTitle`	物件聊天室點選物件下沉觸發
`roomMenu`	聊天室選單觸發
`message`	訊息選單觸發

roomInfo 欄位：

欄位	型別	說明
`roomName`	`string`	聊天室顯示名稱
`roomAvatar`	`string`	聊天室頭像，Base64 格式；多人聊天室可能無效
`roomMembers`	`string[]`	聊天室成員 OpenId 陣列
`roomOwnerId`	`string`	服務號聊天室中代表客戶 OpenId，其他型別為空
`serviceId`	`string`	服務號聊天室對應服務號 ID

objectInfo 欄位：

欄位	型別	說明
`businessCode`	`string`	物件編碼
`businessId`	`string`	物件 ID
`name`	`string`	物件名稱
`description`	`string`	物件描述
`endTimestamp`	`string`	系統記錄的預計結束時間戳
`roomId`	`string`	對應多人聊天室 ID
`businessManagerId`	`string`	物件下達者 OpenId
`businessManagerImgSrc`	`string`	下達者頭像，Base64 圖片格式
`businessManagerName`	`string`	下達者名稱
`businessCustomerId`	`string`	物件客戶 OpenId
`businessCustomerImgSrc`	`string`	客戶頭像，Base64 圖片格式
`businessCustomerName`	`string`	客戶名稱
`businessExecutorId`	`string`	物件執行者 OpenId
`businessExecutorImgSrc`	`string`	執行者頭像，Base64 圖片格式
`businessExecutorName`	`string`	執行者名稱

userInfo 在 openerType 為 self、vistor、friend、serviceRoom 時可能存在：

欄位	型別	說明
`openId`	`string`	對應聊天室使用者 OpenId
`lastChannel`	`string`	最後進線渠道關鍵字
`userAvatar`	`string`	對應使用者頭像，Base64 格式
`alias`	`string`	備註名
`nickName`	`string`	暱稱
`tags`	`Object`	個人標籤資料，舊文件標註為暫不支援

6.5 `getAiffItem(aiffKey)`

獲取指定 aiffKey 對應的 Aiff 資料。

AiffJS.getAiffItem("some-aiff-key").then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`aiffKey`	`string`	是	Aiff key

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

欄位	型別	說明
`code`	`string`	`Aiff.OK` 獲取成功；`Aiff.NotExist` 未找到對應 Aiff
`data.id`	`string`	Aiff ID
`data.name`	`string`	應用名稱
`data.title`	`string`	應用 title
`data.aiffKey`	`string`	應用 key

7. 聊天室與使用者介面

7.1 `getRoomStatus(roomId = "")`

獲取聊天室服務狀態。舊文件說明該介面主要對客戶聊天室生效。

AiffJS.getRoomStatus().then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	預設值	說明
`roomId`	`string`	否	`""`	聊天室 ID；為空時由宿主按當前上下文處理

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

欄位	型別	說明
`code`	`string`	`Aiff.OK` 獲取成功；`Aiff.NotSupport` 當前聊天室型別不支援；`Aiff.NotInit` 未初始化
`data.status`	`string`	服務狀態，例如 `online`、`offline`、`timeout`
`data.channel`	`string`	當前進線渠道標識
`data.channelList`	`string[]`	當前進線客戶的渠道列表

7.2 `openChat(roomId)`

開啟指定聊天室。

AiffJS.openChat(roomId).then(function (res) {
  if (res && res.code === "Aiff.OK") {
    console.log("opened");
  }
});

引數：

引數	型別	必填	說明
`roomId`	`string`	是	聊天室 ID

返回值：Promise<Object | null>

狀態	返回
已初始化	宿主 `openRoom` 回撥資料
未初始化	`null`

常見 code：

code	說明
`Aiff.OK`	開啟成功
`Aiff.NotExistUser`	未找到對應使用者
`Aiff.NotInit`	未初始化

7.3 `openUserChat(openId)`（取決於宿主同事聊天室能力）

開啟指定同事的聊天室。

AiffJS.openUserChat(openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`openId`	`string`	是	同事 OpenId

返回值：Promise<Object | null>

狀態	返回
已初始化	宿主 `openUserRoom` 回撥資料
未初始化	`null`

7.4 `getUserRooms(openId)`

獲取指定同事的關聯聊天室列表。

AiffJS.getUserRooms(openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`openId`	`string`	是	同事 OpenId

返回值：Promise<Object | null>

狀態	返回
已初始化	宿主 `getUserRooms` 回撥資料
未初始化	`null`

7.5 `getAllRooms()`

獲取聊天室列表。

AiffJS.getAllRooms().then(function (res) {
  console.log(res);
});

返回值：Promise<Object | null>

狀態	返回
已初始化	宿主 `getAllRooms` 回撥資料
未初始化	`null`

7.6 `openContactChat(serviceNumberId, openId)`

開啟指定服務號下某個客戶的聊天室。

AiffJS.openContactChat(serviceNumberId, openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`serviceNumberId`	`string`	是	服務號 ID
`openId`	`string`	是	客戶 OpenId

返回值：Promise<Object | null>

當前原始碼行為：

狀態	返回
已初始化	呼叫宿主 `openContactChat(serviceNumberId, openId)` 後立即返回 `{ "code": "Aiff.OK" }`
未初始化	`null`

說明：當前封裝不會等待宿主回撥結果。

7.7 `openBossContactChat(openId)`

開啟當前使用者主管號下的客戶聊天室。舊文件說明：根據 openId 查詢當前主管號下的使用者並開啟對應聊天室；若該主管號不存在該客戶，則開啟該客戶主頁；若查無客戶則由宿主提示。

AiffJS.openBossContactChat(openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`openId`	`string`	是	客戶 OpenId

返回值：Promise<Object | null>

當前原始碼行為：

狀態	返回
已初始化	呼叫宿主 `openContactChat(openId)` 後立即返回 `{ "code": "Aiff.OK" }`
未初始化	`null`

7.8 `getUser(openId, type = "")`

獲取 OpenId 對應使用者資料。

AiffJS.getUser(openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	預設值	說明
`openId`	`string`	是	-	使用者 OpenId
`type`	`string`	否	`""`	傳給宿主的型別引數

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

欄位	型別	說明
`code`	`string`	`Aiff.OK` 獲取成功；`Aiff.NotExistUser` 未找到對應使用者；`Aiff.NotInit` 未初始化
`data.openId`	`string`	使用者 OpenId
`data.nickName`	`string`	使用者暱稱
`data.alias`	`string`	使用者別名
`data.userType`	`string`	`contact` 客戶，`employee` 員工
`data.image`	`string`	使用者頭像，Base64 格式

7.9 `getAvatar(openId, type = "")`

獲取 OpenId 對應使用者的頭像資料。舊文件說明：頭像資料通常來自客戶端快取。

AiffJS.getAvatar(openId).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	預設值	說明
`openId`	`string`	是	-	使用者 OpenId
`type`	`string`	否	`""`	傳給宿主的型別引數

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

欄位	型別	說明
`code`	`string`	`Aiff.OK` 獲取成功；`Aiff.NotExistUser` 未找到對應使用者；`Aiff.NotInit` 未初始化
`data.image`	`string`	頭像資料，Base64 格式

8. 訊息與分享介面

8.1 `sendMessage(msgObj, type)`

傳送訊息到當前來源聊天室。

AiffJS.sendMessage("hello", "text");

AiffJS.sendMessage(JSON.stringify(templateObj), "template");

引數：

引數	型別	必填	說明
`msgObj`	`string \| Object`	是	訊息內容
`type`	`string`	是	訊息型別，舊文件列出 `text` 與 `template`

返回值：

狀態	返回
已初始化	宿主 `sendMessage(msgObj, type)` 返回值
未初始化	`null`

8.2 `selectMessage(msgObj)`

將訊息內容傳遞到聊天室輸入框中，等待使用者傳送。

AiffJS.selectMessage("hello");

引數：

引數	型別	必填	說明
`msgObj`	`string`	是	訊息內容，舊文件說明僅支援文字

返回值：

狀態	返回
已初始化且不在 iframe	宿主 `selectMessage(msgObj)` 返回值
已初始化但在 iframe	`null`
未初始化	`null`

8.3 `shareTargetPicker(templateObj, type)`

開啟宿主選擇介面，選擇聊天室或同事後分享一則模板訊息。

AiffJS.shareTargetPicker(templateObj, "all").then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`templateObj`	`Object \| string`	是	模板訊息
`type`	`string`	否	選擇範圍。舊文件示例為 `all`

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見 code：

code	說明
`Aiff.OK`	分享成功
`Aiff.NotExistUser`	未找到對應使用者
`Aiff.NotInit`	未初始化

8.4 `shareMessage(message)`

使用宿主分享能力分享一段文字。

AiffJS.shareMessage("您的邀请码为：xxx").then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`message`	`string`	是	要分享的文字

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

8.5 `sendCmd(cmd)`

向宿主傳送命令。

AiffJS.sendCmd({
  action: "active",
  data: {}
}).then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`cmd`	`Object`	是	命令物件，具體格式由業務和宿主約定

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

8.6 `sendData(data)`

向宿主傳送擴充套件資料。

AiffJS.sendData({
  action: "setCallState",
  args: {
    state: "oncall"
  }
});

引數：

引數	型別	必填	說明
`data`	`Object`	是	擴充套件資料，具體格式由業務和宿主約定

返回值：無穩定返回值。

當前原始碼實現注意：

初始化成功且宿主存在 sendData 方法時，會呼叫 AiffJS.aileAPI.sendData(data)。
未初始化或宿主未實現 sendData 時，原始碼會引用未在當前作用域定義的 res。呼叫方不應依賴該分支返回值。

9. 視窗、導航與標題

9.1 `openWindow(args)`

開啟 URL。

AiffJS.openWindow({
  url: "https://www.example.com",
  external: false
});

引數：

引數	型別	必填	說明
`args.url`	`string`	是	要開啟的 URL
`args.external`	`boolean`	否	`false` 表示用 Aiff 方式開啟；`true` 表示使用系統預設瀏覽器開啟

返回值：

狀態	返回
已初始化	宿主 `openWindow(args)` 返回值
未初始化	`null`

9.2 `closeWindow()`

關閉當前 Aiff 頁面。

AiffJS.closeWindow();

返回值：

狀態	返回
已初始化	呼叫宿主 `closeAiff()` 後返回 `true`
未初始化	`null`

9.3 `changeAiffTitle(title)`

修改當前 Aiff 會話標題。

AiffJS.changeAiffTitle("新的标题").then(function (res) {
  console.log(res);
});

引數：

引數	型別	必填	說明
`title`	`string`	是	新標題

返回值：Promise<Object> 或宿主方法返回值。

當前原始碼呼叫順序：

若已初始化且 AiffJS.aileAPI.changeAiffTitle 是函式，直接呼叫該方法並返回其結果。
否則若 window.AileAPI.request 是函式，呼叫 request("changeAiffTitle", { title })。
若宿主不支援，返回 { code: "Aiff.NotSupport" }。
未初始化時返回 Promise.resolve({ code: "Aiff.NotInit" })。

9.4 `changeAiffTilte(title)`

歷史拼寫相容介面，建議新程式碼使用 changeAiffTitle。

AiffJS.changeAiffTilte("新的标题").then(function (res) {
  console.log(res);
});

當前原始碼呼叫順序：

若已初始化且 AiffJS.aileAPI.changeAiffTilte 是函式，直接呼叫歷史拼寫方法。
否則若 AiffJS.aileAPI.changeAiffTitle 是函式，呼叫標準拼寫方法。
否則若 window.AileAPI.request 是函式，先呼叫 request("changeAiffTilte", { title })；若失敗，再嘗試 request("changeAiffTitle", { title })。
若宿主不支援，返回 { code: "Aiff.NotSupport" }。
未初始化時返回 Promise.resolve({ code: "Aiff.NotInit" })。

9.5 `navigateToTab(mainAiffId, args = null)`

跳轉並開啟主框架中的內嵌 Aiff 應用。

AiffJS.navigateToTab("179f5470-fff0-00d9-21fb-000c29cfe318", {
  data: 1234567
});

引數：

引數	型別	必填	預設值	說明
`mainAiffId`	`string`	是	-	要開啟的 Aiff 專案 ID
`args`	`Object`	否	`null`	要傳給被開啟頁面的資料

返回值：無。

被開啟頁面可透過瀏覽器 message 事件接收資料：

window.addEventListener("message", function (event) {
  console.log(event.data);
});

訊息格式：

{
  "action": "aiffCall",
  "args": {}
}

當前原始碼實現注意：未初始化分支會引用未在當前作用域定義的 res。呼叫方應在初始化成功後再呼叫。

10. 裝置能力與事件控制

10.1 `scanCode()`

啟動掃碼器並取得結果。

AiffJS.scanCode().then(function (res) {
  console.log(res);
});

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

舊文件說明：掃碼成功後返回識別結果；若取消或失敗，返回空值。當前原始碼會透傳宿主回撥資料。

10.2 `getCurrentPosition()`

獲取當前地理位置。

AiffJS.getCurrentPosition().then(function (res) {
  console.log(res);
});

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回資料：

{
  "longitude": 103.333,
  "latitude": 33.222
}

欄位：

欄位	型別	說明
`longitude`	`number`	經度
`latitude`	`number`	緯度

10.3 `subscribeCurrentPosition()`

訂閱當前位置變化。

const subscription = AiffJS.subscribeCurrentPosition();

subscription.subscribe({
  next: function (data) {
    console.log("position changed", data);
  },
  complete: function () {
    console.log("position complete");
  }
});

返回值：簡易 Observable 物件。

物件結構：

{
  subscribe: function (observer) {}
}

observer 引數：

欄位	型別	必填	說明
`next`	`Function`	是	收到位置變化資料時呼叫
`complete`	`Function`	是	宿主通知訂閱結束時呼叫

當前原始碼事件：

監聽事件	行為
`CurrentPositionChanged` + 隨機 key	呼叫 `observer.next(data)`
`CurrentPositionComplete` + 隨機 key	呼叫 `observer.complete()`

未初始化時會依次呼叫：

observer.next({ code: "Aiff.NotInit" });
observer.complete();

10.4 `startEvent(eventName)`

通知宿主啟動指定事件。

AiffJS.startEvent("eventName");

引數：

引數	型別	必填	說明
`eventName`	`string`	是	事件名稱

當前原始碼行為：

已初始化時生成隨機 key，監聽 startEvent + key，並呼叫宿主 startEvent(eventName, key)。
當前方法沒有返回 Promise 或 Observable。
回撥中引用了未在當前作用域定義的 res。
未初始化分支引用了未在當前作用域定義的 observer。

呼叫方應將該介面視為通知型介面，不依賴返回值。

10.5 `stopEvent(eventName)`

通知宿主停止指定事件。

AiffJS.stopEvent("eventName");

引數：

引數	型別	必填	說明
`eventName`	`string`	是	事件名稱

當前原始碼行為：

已初始化時生成隨機 key，監聽 stopEvent + key，並呼叫宿主 stopEvent(eventName, key)。
當前方法沒有返回 Promise 或 Observable。
回撥中引用了未在當前作用域定義的 res。
未初始化分支引用了未在當前作用域定義的 observer。

呼叫方應將該介面視為通知型介面，不依賴返回值。

11. Aiff 狀態顯示

11.1 `sendAiffState(ibState)`

設定當前 Aiff 圖示的紅點狀態。

AiffJS.sendAiffState(true);

引數：

引數	型別	必填	說明
`ibState`	`boolean`	是	`true` 顯示紅點，`false` 取消紅點

返回值：

狀態	返回
已初始化	宿主 `sendState(ibState)` 返回值
未初始化	`null`

11.2 `sendAiffStateNumber(iNumber)`

設定當前 Aiff 圖示的未讀數字。

AiffJS.sendAiffStateNumber(10);

引數：

引數	型別	必填	說明
`iNumber`	`number`	是	未讀數字

返回值：

狀態	返回
已初始化	宿主 `sendNumber(iNumber)` 返回值
未初始化	`null`

12. 原生資訊介面

12.1 `getNative()`

獲取宿主原生資訊。

AiffJS.getNative().then(function (res) {
  console.log(res);
});

返回值：Promise<Object | null>

狀態	返回
已初始化且宿主實現 `getNative`	宿主 `getNative` 回撥資料
已初始化但宿主未實現 `getNative`	`null`
未初始化	`null`

13. 事件回撥

13.1 `onCloseWindow(cancelFun)`

宿主要求關閉 Aiff 頁面時觸發。

預設實現：

AiffJS.onCloseWindow = function (cancelFun) {
  cancelFun(false);
};

業務可覆寫：

AiffJS.onCloseWindow = function (cancelFun) {
  cancelFun(true);

  if (window.confirm("Aiff Close?")) {
    AiffJS.closeWindow();
  }
};

引數：

引數	型別	說明
`cancelFun`	`Function`	關閉控制回撥

cancelFun(cancel) 引數：

值	說明
`true`	阻止宿主立即關閉 Aiff 頁面
`false`	不阻止關閉

舊文件說明：該事件需要在 Aiff 設定中勾選“頁面控制 Aiff 關閉”後生效。

13.2 `onAiffEvent(args)`

宿主主動通知 Aiff 頁面時觸發。

AiffJS.onAiffEvent = function (args) {
  console.log(args);
};

引數：

引數	型別	說明
`args`	`Object`	宿主傳入的事件資料

常見格式：

{
  "action": "active",
  "aiffId": "aiff-item-id",
  "args": {}
}

說明：active 表示側邊欄啟用 Aiff 時觸發。其他事件格式由業務和宿主約定。

14. Aiff 協議開啟規則

舊文件說明：Aile 客戶端可以透過以下 URL 形式開啟 Aiff 頁面：

https://aiff.aile.com.tw/[aiffid]
https://aiff.aile.cloud/[aiffid]

流程：

拆解 URL 中的 [aiffId]。
獲取 Aiff 資料並確認是否存在對應設定。
若不存在，由宿主提示。
若存在，獲取對應 Endpoint URL，並以 Aiff 方式開啟。

協議開啟可以攜帶引數：

https://aiff.aile.com.tw/[aiffid]?a=123&b=321

宿主開啟 Endpoint 時會附加 aiff.query 引數，內容為 URL 編碼後的 JSON 字串。

示例：

AiffId: abcdef
EndpointURL: https://www.chainsea.com.tw/ecp.page
协议 URL: https://aiff.aile.com.tw/abcdef?a=123&b=321
实际打开: https://www.chainsea.com.tw/ecp.page?aiff.query=%7B%22a%22%3A123%2C%22b%22%3A321%7D

15. 內部輔助成員

以下成員存在於當前原始碼中，主要服務於 SDK 內部流程，不建議業務程式碼直接修改。

成員	型別	說明
`aileAPI`	`Object \| null`	初始化成功後儲存 `window.AileAPI` 引用
`_initSuccessed`	`boolean`	初始化成功標記，當前原始碼保留該拼寫
`_iniData`	`Object`	儲存宿主初始化返回資料
`_initEvent()`	`Function`	註冊 `closeAiff` 與 `aiffEvent` 監聽，指令碼載入後會自動執行
`_closeEvent(cancel)`	`Function`	`cancel` 為 `false` 時呼叫宿主 `closeAiff()`
`hasLog()`	`Function`	當宿主存在 `isLog` 標記時返回該值，否則返回 `false`
`log(msg)`	`Function`	`hasLog()` 為 `true` 時輸出帶版本號的日誌

16. 常見返回碼

code	說明
`Aiff.OK`	操作成功
`Aiff.NotInit`	未初始化
`Aiff.NotSupport`	當前宿主不支援該能力
`Aiff.NotExistUser`	未找到對應使用者
`Aiff.NotExist`	未找到對應 Aiff

17. 當前原始碼實現注意事項

以下說明來自 aiff.js 1.0.19 的實際實現：

openContactChat 與 openBossContactChat 在已初始化時會立即返回 { code: "Aiff.OK" }，不會等待宿主實際處理結果。
changeAiffTitle 是標準拼寫；changeAiffTilte 是歷史拼寫相容介面。
selectMessage 仍保留 iframe 判斷，在 iframe 中會直接返回 null。
startEvent、stopEvent 當前沒有穩定返回值，且內部引用了未在當前作用域定義的變數；呼叫方不應依賴返回值。
navigateToTab、sendData 的未初始化或宿主未實現分支也存在未定義變數引用；呼叫方應在初始化成功且宿主能力存在時呼叫。
getAllRooms、openChat、openUserChat、getUserRooms 未初始化時返回 Promise<null>；而 getRoomStatus、getAvatar、getUser、getAiffItem、scanCode、getCurrentPosition、shareMessage、sendCmd、shareTargetPicker 未初始化時返回 { code: "Aiff.NotInit" }。

1. 概述​

2. 快速開始​

3. 版本記錄​

4. 介面總覽與應用支援狀態​

5. 初始化與執行環境​

5.1 AiffJS.version​

5.2 init(aiffId)​

5.3 getClientType()​

5.4 openDev()​

6. 當前使用者、Aiff 設定與開啟來源​

6.1 getAuthToken()​

6.2 getAiffConfig()​

6.3 getProfile()​

6.4 getOpener()​

6.5 getAiffItem(aiffKey)​

7. 聊天室與使用者介面​

7.1 getRoomStatus(roomId = "")​

7.2 openChat(roomId)​

7.3 openUserChat(openId)（取決於宿主同事聊天室能力）​

7.4 getUserRooms(openId)​

7.5 getAllRooms()​

7.6 openContactChat(serviceNumberId, openId)​

7.7 openBossContactChat(openId)​

7.8 getUser(openId, type = "")​

7.9 getAvatar(openId, type = "")​

8. 訊息與分享介面​

8.1 sendMessage(msgObj, type)​

8.2 selectMessage(msgObj)​

8.3 shareTargetPicker(templateObj, type)​

8.4 shareMessage(message)​

8.5 sendCmd(cmd)​

8.6 sendData(data)​

9. 視窗、導航與標題​

9.1 openWindow(args)​

9.2 closeWindow()​

9.3 changeAiffTitle(title)​

9.4 changeAiffTilte(title)​

9.5 navigateToTab(mainAiffId, args = null)​

10. 裝置能力與事件控制​

10.1 scanCode()​

10.2 getCurrentPosition()​

10.3 subscribeCurrentPosition()​

10.4 startEvent(eventName)​

10.5 stopEvent(eventName)​

11. Aiff 狀態顯示​

11.1 sendAiffState(ibState)​

11.2 sendAiffStateNumber(iNumber)​

12. 原生資訊介面​

12.1 getNative()​

13. 事件回撥​

13.1 onCloseWindow(cancelFun)​

13.2 onAiffEvent(args)​

14. Aiff 協議開啟規則​

15. 內部輔助成員​

16. 常見返回碼​

17. 當前原始碼實現注意事項​

1. 概述

2. 快速開始

3. 版本記錄

4. 介面總覽與應用支援狀態

5. 初始化與執行環境

5.1 `AiffJS.version`

5.2 `init(aiffId)`

5.3 `getClientType()`

5.4 `openDev()`

6. 當前使用者、Aiff 設定與開啟來源

6.1 `getAuthToken()`

6.2 `getAiffConfig()`

6.3 `getProfile()`

6.4 `getOpener()`

6.5 `getAiffItem(aiffKey)`

7. 聊天室與使用者介面

7.1 `getRoomStatus(roomId = "")`

7.2 `openChat(roomId)`

7.3 `openUserChat(openId)`（取決於宿主同事聊天室能力）

7.4 `getUserRooms(openId)`

7.5 `getAllRooms()`

7.6 `openContactChat(serviceNumberId, openId)`

7.7 `openBossContactChat(openId)`

7.8 `getUser(openId, type = "")`

7.9 `getAvatar(openId, type = "")`

8. 訊息與分享介面

8.1 `sendMessage(msgObj, type)`

8.2 `selectMessage(msgObj)`

8.3 `shareTargetPicker(templateObj, type)`

8.4 `shareMessage(message)`

8.5 `sendCmd(cmd)`

8.6 `sendData(data)`

9. 視窗、導航與標題

9.1 `openWindow(args)`

9.2 `closeWindow()`

9.3 `changeAiffTitle(title)`

9.4 `changeAiffTilte(title)`

9.5 `navigateToTab(mainAiffId, args = null)`

10. 裝置能力與事件控制

10.1 `scanCode()`

10.2 `getCurrentPosition()`

10.3 `subscribeCurrentPosition()`

10.4 `startEvent(eventName)`

10.5 `stopEvent(eventName)`

11. Aiff 狀態顯示

11.1 `sendAiffState(ibState)`

11.2 `sendAiffStateNumber(iNumber)`

12. 原生資訊介面

12.1 `getNative()`

13. 事件回撥

13.1 `onCloseWindow(cancelFun)`

13.2 `onAiffEvent(args)`

14. Aiff 協議開啟規則

15. 內部輔助成員

16. 常見返回碼

17. 當前原始碼實現注意事項