Contact Center AI 平台會使用使用者驗證機制，安全地識別使用主機應用程式的人員。這項機制可確保只有獲得授權的使用者能存取 CCAI Platform API，且他們的即時通訊工作階段和資料會安全地連結至特定身分。
如要識別使用者，主機應用程式必須提供代表該特定人員的通用唯一識別碼 (UUID)。
CCAI 平台的驗證方式
CCAI Platform 的驗證機制是透過 JSON Web Token (JWT) 進行安全交握。JWT 是一種開放標準，用於以 JSON 物件的形式安全傳輸資訊。
標準驗證流程如下：
要求：使用者開始使用 CCAI Platform 客服服務時，CCAI Platform SDK 會向主機應用程式要求已簽署的 JWT。
簽章：主機應用程式會使用共用的 CCAI 平台公司機密 (
company_secret) 簽署 JWT。交換：主機應用程式會將已簽署的 JWT 傳回給 CCAI Platform SDK。接著，SDK 會將這個 JWT 傳送至 CCAI Platform 伺服器。
驗證：CCAI Platform 伺服器會驗證簽章。如果有效，CCAI Platform 會核發授權權杖，授予使用者 API 存取權，並將使用者與帳戶建立關聯 (如果使用者沒有帳戶，系統會建立新帳戶)。
如果主機應用程式未在 JWT 酬載中提供 ID，CCAI Platform 會為使用者建立匿名訪客帳戶。
必要條件
實作驗證前，您需要專屬的 SDK 驗證元素。這些憑證會安全地向 CCAI Platform API 識別貴公司。
使用管理員帳戶登入 CCAI Platform。
依序前往「設定」 >「開發人員設定」 >「API 憑證」。
找出 SDK 金鑰名稱 (
sdk_key_name)、SDK 金鑰 (sdk_key) 和公司密碼 (company_secret)。
請妥善保管這些憑證。請只與授權系統和開發人員分享。
開發人員導入指南
下一節說明開發人員應如何建構 JWT 酬載，以及在不同平台初始化 CCAI Platform SDK。
JWT 酬載規定
如要將使用者的資訊傳遞至 CCAI Platform，主機應用程式必須建構 JWT 酬載。回呼方法會提供預設酬載 (可能包含推送權杖和預設名稱)，但您可以使用下列保留鍵新增特定使用者詳細資料：
identifier(選用，但強烈建議使用 UUID)name(選填)email(選填)phone(選填，必須使用 E.164 格式)iss(選填，公司名稱)iat(必要，核發時的時間戳記)exp(必填，到期時間戳記)
伺服器端簽署 (建議)
伺服器上的 API 範例 (Ruby on Rails)
本範例說明如何使用 Ruby on Rails 架構和 JWT Gem，在伺服器端簽署酬載。
這段程式碼會使用 jwt Gem 設定 API 端點 (/api/ujet/sign)，以公司機密編碼酬載，並將編碼後的權杖傳回給用戶端。
假設主機應用程式的基準網址是 https://company.com/api/。 如要簽署 CCAI Platform 的酬載，您可以在 https://company.com/api/ujet/sign 新增另一個 API 端點。
這段程式碼會在應用程式的路徑檔案中新增路徑，以處理對 /api/ujet/sign 網址的 POST 要求。
ujet_controller.rb 檔案會定義 UjetController 類別，其中包含單一端點 sign，用於簽署 CCAI Platform 的酬載。
在程式碼中，COMPANY_SECRET 定義為用於簽署酬載的密鑰。酬載會從要求主體中擷取，然後加入各種值，例如 UNIQUE-IDENTIFIER、使用者名稱、電子郵件地址、電話號碼。
JWT.encode 方法用於將酬載和 ujet_secret 編碼為 JSON Web Token (JWT)，然後以含有權杖鍵的 JSON 物件形式，在回應中傳回。
# routes.rb
post 'ujet/sign' => "ujet#sign"
# ujet_controller.rb
class UjetController
def sign
# In production, securely store and call your secret (e.g., via environment variables)
ujet_secret = "COMPANY_SECRET"
payload = body["payload"]
payload["identifier"] = "UNIQUE-IDENTIFIER"
payload["name"] = "user name"
payload["email"] = "test@email.com"
payload["phone"] = "" # E.164 format
payload["iss"] = "YOUR_COMPANY_NAME"
payload["iat"] = Time.now.to_i
payload["exp"] = Time.now.to_i + 10.minutes # Valid for 10 minutes
token = JWT.encode(payload, ujet_secret)
render json: {token: token}
end
end
用戶端初始化
請按照下列指南初始化 CCAI Platform 行動版 SDK。
從 iOS SDK 簽署
這個範例說明如何透過 iOS SDK 簽署酬載，並向網址 https://your.company.com/api/ujet/sign 的伺服器發出 POST 要求，酬載則做為要求主體。
伺服器應在回應中傳回已簽署的權杖，然後以 JSON 物件中「token」鍵的形式，傳遞至成功回呼。
如果要求期間發生錯誤，系統會將錯誤傳遞至失敗回呼。
- (void)signPayload:(NSDictionary *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success failure:(void (^)(NSError *))failure
{
if (payloadType == UjetPayloadAuthToken) {
NSURLSessionConfiguration *sessionConfiguration = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfiguration];
NSMutableURLRequest *mutableRequest = [[NSMutableURLRequest alloc] init];
mutableRequest.URL = [NSURL URLWithString:@"https://your.company.com/api/ujet/sign"];
mutableRequest.HTTPMethod = @"POST";
NSError *error;
NSDictionary *data = @{@"payload": payload};
mutableRequest.HTTPBody = [NSJSONSerialization dataWithJSONObject:data options:0 error:&error];
NSURLSessionDataTask *task = [session dataTaskWithRequest:mutableRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if(error) {
failure(error);
}
else {
NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
success(json[@"token"]);
}
}];
[task resume];
}
}
透過 Android SDK 簽署
以下範例說明如何從 Android SDK 簽署酬載。
這個範例使用 Android 的 HTTP 用戶端 Retrofit，向伺服器要求已簽署的酬載。這個函式會將酬載、酬載類型和權杖回呼做為輸入內容。
如果酬載類型為 UjetPayloadType.AuthToken，系統會建立 Retrofit 執行個體，並使用該執行個體向 https://company.com/api API 端點發出要求，以簽署酬載，然後在 tokenCallback 執行個體的 onToken 方法中傳回已簽署的權杖。
如果失敗，系統會顯示訊息 "Authentication failed"。
public void onSignPayloadRequest(Map<String, Object> payload, UjetPayloadType ujetPayloadType, final UjetTokenCallback tokenCallback) {
if (ujetPayloadType == UjetPayloadType.AuthToken) {
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://company.com/api/")
.addConverterFactory(GsonConverterFactory.create())
.build();
AuthService authService = retrofit.create(AuthService.class);
Call<AuthToken> authenticate = authService.authenticate(new AuthRequest(payload));
authenticate.enqueue(new Callback<AuthToken>() {
@Override
public void onResponse(Call<AuthToken> call, Response<AuthToken> response) {
if (response.isSuccessful()) {
AuthToken authToken = response.body();
tokenCallback.onToken(authToken.getToken());
} else {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
}
@Override
public void onFailure(Call<AuthToken> call, Throwable t) {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
});
}
}
透過 Web SDK 簽署
以下範例說明如何透過向伺服器發出含有酬載的 API 要求，在 Web SDK 中簽署酬載。
伺服器應設定為處理 API 要求，並使用安全方法簽署酬載。結果隨後會傳回網頁，並使用回呼函式將簽署的權杖傳回 CCAI Platform。
$(function() {
UJET.initialize({
// ... other parameters
handlers: {
authentication(callback) {
$.ajax({
type: 'POST',
url: 'https://company.com/api/ujet/sign',
data: JSON.stringify({
payload: {
identifier: 'UNIQUE-Identifier',
name: 'Test user'
}
}),
success: function(result) {
callback({
token: result.token,
user: {
identifier: 'UNIQUE-IDENTIFIER',
name: 'Test user'
}
});
}
});
}
}
}).then(function() {
// successfully initialized
}).catch(function(error) {
// Handle initialization error
});
});
工作階段中驗證和 SDK 重新初始化
在某些情況下，使用者可能會以訪客身分 (未通過驗證) 開始即時通訊工作階段，並在工作階段中驗證身分 (例如透過虛擬助理或流程中的登入畫面)。如要確保系統安全地更新有效工作階段，並將其與新驗證的使用者建立關聯，請按照下列步驟操作：
工作階段中驗證的步驟
使用臨時 ID 初始化 SDK：使用者未通過驗證時，請使用隨機或訪客 ID 初始化 CCAI Platform SDK。
引導使用者進行驗證：引導使用者進入驗證流程，例如 CCAI 平台虛擬助理 (VA) 或應用程式內建的登入畫面。
透過 API 更新使用者資訊：使用者成功完成驗證後 (且仍在虛擬代理或驗證流程中)，後端必須呼叫 CCAI Platform Apps API，使用者的真實 ID 更新聊天工作階段。
使用新的 JWT 重新初始化 SDK：後端更新成功後，請為通過驗證的使用者產生新的 JWT。使用這個新 JWT 再次呼叫初始化方法，重新初始化 CCAI Platform SDK。
提升工作階段 (如果使用 VA)：如果使用者是透過虛擬助理驗證，虛擬代理程式現在應將消費者提升至最終目的地佇列。
範例 (Web SDK)
如要重新初始化，請再次呼叫 UJET.initialize 函式。這會觸發驗證處理常式，以擷取新權杖。
// Call this after successful authentication and the CCAI Platform Apps API update
UJET.initialize({
// ...include your existing parameters
handlers: {
authentication(callback) {
// Fetch the new JWT for the newly authenticated user
$.ajax({
type: 'POST',
url: 'https://your.company.com/api/ujet/sign',
data: JSON.stringify({
payload: {
identifier: 'AUTHENTICATED-USER-UUID',
name: 'Authenticated User Name'
}
}),
success: function(result) {
callback({
token: result.token,
user: {
identifier: 'AUTHENTICATED-USER-UUID',
name: 'Authenticated User Name'
}
});
}
});
}
}
}).then(function() {
// SDK successfully reinitialized with the authenticated user
}).catch(function(error) {
// Handle reinitialization errors
});
為什麼需要這麼做？
確保所有後續動作、路徑和記錄都安全地與通過驗證的使用者建立關聯，而不是與匿名訪客工作階段建立關聯。
這項功能可防止資料外洩，並確保 CRM 和使用者記錄的準確性。
摘要表格
| 情境 | 敬請採取行動 |
|---|---|
| 使用者已通過驗證 | 使用使用者的真實 UUID 和 JWT 初始化 SDK。 |
| 使用者未通過驗證 | 使用訪客/隨機 ID 初始化 SDK。 |
| 使用者在工作階段中驗證身分 | 使用 API 更新 CCAI Platform、產生新的 JWT，然後重新初始化 SDK。 |