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();

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

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. 版本記錄

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

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

狀態說明：

5. 初始化與執行環境

5.1 AiffJS.version

當前版本號：

AiffJS.version // "1.0.19"

5.2 init(aiffId)

初始化當前 Aiff 頁面。

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

引數：

返回值：Promise<boolean>

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

5.3 getClientType()

獲取當前載具型別。

const clientType = AiffJS.getClientType();

返回值：string

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

5.4 openDev()

開啟宿主開發工具。

AiffJS.openDev();

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

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

6.1 getAuthToken()

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

const token = AiffJS.getAuthToken();

返回值：

6.2 getAiffConfig()

獲取當前 Aiff 設定。

const config = AiffJS.getAiffConfig();

返回值：

常見欄位：

6.3 getProfile()

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

const profile = AiffJS.getProfile();

返回值：

常見欄位：

6.4 getOpener()

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

const opener = AiffJS.getOpener();

返回值：

頂層欄位：

openerType 常見值：

openerSource 常見值：

roomInfo 欄位：

objectInfo 欄位：

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

6.5 getAiffItem(aiffKey)

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

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

7. 聊天室與使用者介面

7.1 getRoomStatus(roomId = "")

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

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

7.2 openChat(roomId)

開啟指定聊天室。

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

引數：

返回值：Promise<Object | null>

常見 code：

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

開啟指定同事的聊天室。

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

引數：

返回值：Promise<Object | null>

7.4 getUserRooms(openId)

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

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

引數：

返回值：Promise<Object | null>

7.5 getAllRooms()

獲取聊天室列表。

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

返回值：Promise<Object | null>

7.6 openContactChat(serviceNumberId, openId)

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

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

引數：

返回值：Promise<Object | null>

當前原始碼行為：

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

7.7 openBossContactChat(openId)

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

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

引數：

返回值：Promise<Object | null>

當前原始碼行為：

7.8 getUser(openId, type = "")

獲取 OpenId 對應使用者資料。

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

7.9 getAvatar(openId, type = "")

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

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見返回欄位：

8. 訊息與分享介面

8.1 sendMessage(msgObj, type)

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

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

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

引數：

返回值：

8.2 selectMessage(msgObj)

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

AiffJS.selectMessage("hello");

引數：

返回值：

8.3 shareTargetPicker(templateObj, type)

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

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

常見 code：

8.4 shareMessage(message)

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

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

8.5 sendCmd(cmd)

向宿主傳送命令。

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

引數：

返回值：Promise<Object>

未初始化時返回：

{ "code": "Aiff.NotInit" }

8.6 sendData(data)

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

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

引數：

返回值：無穩定返回值。

當前原始碼實現注意：

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

9. 視窗、導航與標題

9.1 openWindow(args)

開啟 URL。

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

引數：

返回值：

9.2 closeWindow()

關閉當前 Aiff 頁面。

AiffJS.closeWindow();

返回值：

9.3 changeAiffTitle(title)

修改當前 Aiff 會話標題。

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

引數：

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

當前原始碼呼叫順序：

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

9.4 changeAiffTilte(title)

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

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

當前原始碼呼叫順序：

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

9.5 navigateToTab(mainAiffId, args = null)

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

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

引數：

返回值：無。

被開啟頁面可透過瀏覽器 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
}

欄位：

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 引數：

當前原始碼事件：

未初始化時會依次呼叫：

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

10.4 startEvent(eventName)

通知宿主啟動指定事件。

AiffJS.startEvent("eventName");

引數：

當前原始碼行為：

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

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

10.5 stopEvent(eventName)

通知宿主停止指定事件。

AiffJS.stopEvent("eventName");

引數：

當前原始碼行為：

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

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

11. Aiff 狀態顯示

11.1 sendAiffState(ibState)

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

AiffJS.sendAiffState(true);

引數：

返回值：

11.2 sendAiffStateNumber(iNumber)

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

AiffJS.sendAiffStateNumber(10);

引數：

返回值：

12. 原生資訊介面

12.1 getNative()

獲取宿主原生資訊。

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

返回值：Promise<Object | 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(cancel) 引數：

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

13.2 onAiffEvent(args)

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

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

引數：

常見格式：

{
  "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]

流程：

1. 1. 拆解 URL 中的 [aiffId]。
2. 2. 獲取 Aiff 資料並確認是否存在對應設定。
3. 3. 若不存在，由宿主提示。
4. 4. 若存在，獲取對應 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 內部流程，不建議業務程式碼直接修改。

16. 常見返回碼

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" }。