如何儲存使用者喜好設定
本文示範如何透過 -preferences 和 -onPreferencesChanged 沈浸式閱讀程式 SDK 選項來儲存使用者的 UI 設定 (或稱為使用者喜好設定)。
當 CookiePolicy SDK 選項設定為 [已啟用] 時，沈浸式閱讀程式應用程式會使用 Cookie 來儲存使用者喜好設定，例如文字大小、主題色彩和字型。 這些 Cookie 是特定瀏覽器和裝置的本機。 使用者每次在相同瀏覽器和裝置上啟動沈浸式閱讀程式時，都會開啟該裝置上一個工作階段的使用者喜好設定。 不過，如果使用者在不同的瀏覽器或裝置上開啟沈浸式閱讀程式應用程式，其設定一開始會採用沈浸式閱讀程式的預設值；使用者每使用一台裝置，就必須再次設定其喜好設定。 沈浸式閱讀程式 SDK 選項 -preferences 和 -onPreferencesChanged，為應用程式提供了一種在各種瀏覽器和裝置之間漫遊使用者喜好設定的方法，讓使用者無論在何處使用應用程式，都能得到一致的體驗。
首先，在啟動沈浸式閱讀程式應用程式時提供 -onPreferencesChanged 回撥 SDK 選項，這樣每當使用者在沈浸式閱讀程式工作階段中變更其喜好設定時，沈浸式閱讀程式都會向主應用程式回傳一個 -preferences 字串。 然後，主應用程式會負責將使用者喜好設定儲存在其系統中。 接下來，當同一位使用者再次啟動沈浸式閱讀程式時，主應用程式可以從儲存體擷取該使用者的喜好設定，並在啟動沈浸式閱讀程式應用程式時以它們作為 -preferences 字串 SDK 選項，以便還原使用者的喜好設定。
當使用 Cookie 不適合或不可行時，此功能可作為另一種儲存使用者喜好設定的方式。
警告
請勿嘗試以程式設計方式變更傳送至沈浸式閱讀程式應用程式和從沈浸式閱讀程式應用程式傳送的 -preferences 字串值，因為這可能會導致非預期的行為，進而使得使用者體驗降級。 主應用程式絕對不應為 -preferences 字串指派自訂值或操作該字串。 使用 -preferences 字串選項時，只使用從 -onPreferencesChanged 回呼選項傳回的確切值。
啟用儲存使用者喜好設定
沈浸式閱讀程式 SDK launchAsync options 參數包含 -onPreferencesChanged 回撥。 每當使用者變更其喜好設定時，就會呼叫此函式。 參數 value 包含一個字串，代表使用者目前的喜好設定。 接下來，主應用程式會為該使用者儲存這個字串。
const options = {
onPreferencesChanged: (value: string) => {
// Store user preferences here
}
};
ImmersiveReader.launchAsync(YOUR_TOKEN, YOUR_SUBDOMAIN, YOUR_DATA, options);
範例喜好設定 JSON 結構
以下是剖析時 value 參數的外觀範例，以及每個欄位的類型：
{
"displayOptionsState": {
"textSize": "number",
"fontFamily": "string",
"textSpacing": "number",
"formattingEnabled": "boolean",
"theme": "string",
"themeSetByUser": "boolean",
"syllabificationEnabled": "boolean",
"nounHighlightingEnabled": "boolean",
"nounHighlightingColor": "string",
"verbHighlightingEnabled": "boolean",
"verbHighlightingColor": "string",
"adjectiveHighlightingEnabled": "boolean",
"adjectiveHighlightingColor": "string",
"adverbHighlightingEnabled": "boolean",
"adverbHighlightingColor": "string",
"pictureDictionaryEnabled": "boolean",
"posLabelsEnabled": "boolean"
},
"readAloudState": {
"readAloudSpeed": "number",
"voice": "string"
},
"translationState": {
"shouldTranslateWords": "boolean",
"translationLanguage": "string" // encoded JSON
}
}
而這裡是 translationLanguage 已解碼 JSON 的範例。
{
"text": "string",
"key": "string",
"data": {
"tlc": "string",
"slc": "string"
}
}
載入使用者喜好設定
使用 -preferences 選項將使用者的喜好設定傳入沈浸式閱讀程式應用程式。 儲存和載入使用者喜好設定的簡單範例如下：
const storedUserPreferences = localStorage.getItem("USER_PREFERENCES");
let userPreferences = storedUserPreferences === null ? null : storedUserPreferences;
const options = {
preferences: userPreferences,
onPreferencesChanged: (value: string) => {
userPreferences = value;
localStorage.setItem("USER_PREFERENCES", userPreferences);
}
};