傳送應用程式意見回饋給 EMM

企業行動管理服務 (EMM) 供應商提供機構管理 Android 裝置和安裝應用程式的解決方案。這些解決方案通常可做為網路控制台 (稱為「EMM 控制台」) 使用。IT 管理員可使用 EMM 控制台代表所屬機構執行裝置和應用程式管理工作。

指定企業機構的應用程式可透過鍵入的應用程式狀態，將意見回饋傳送給 EMM。EMM 可透過 API 擷取金鑰的應用程式狀態資料，以便在 EMM 控制台中顯示。這個通訊管道可讓 IT 管理員針對所管理裝置上的應用程式安裝狀態接收意見回饋。

舉例來說，電子郵件用戶端應用程式可以使用具有鍵的應用程式狀態，確認帳戶是否設定成功、在同步處理錯誤發生時回報，或傳送應用程式開發人員認為合適的其他狀態更新。

索引鍵應用程式狀態的元件

應用程式金鑰狀態包含下列元素：

• 鍵：應用程式狀態的專屬 ID。長度上限為 100 個半形字元。
• 訊息：說明應用程式狀態的選用訊息。長度上限為 1,000 個半形字元。注意：訊息通常比這則訊息短很多。
• 資料：這是選用供 EMM 使用的機器可讀取值，可讓 IT 管理員根據值設定快訊或篩選條件。舉例來說，如果資料欄位 battery_percentage < 10，IT 管理員可以設定快訊。長度上限為 1,000 個半形字元。
• 嚴重性： 應用程式狀態的嚴重性。允許的值為 SEVERITY_ERROR 和 SEVERITY_INFO (預設值)。只有確實發生錯誤狀況時，機構必須採取行動來修正嚴重性等級，才將嚴重性設為 SEVERITY_ERROR。
• 時間戳記： 設定了索引鍵的應用程式狀態後，系統會自動以時間戳記 (從 Epoch 紀元時間起算，以毫秒為單位) 傳送該狀態。

針對受管理設定傳送意見回饋

如果您的應用程式支援受管理的設定，建議您傳送鍵入的應用程式狀態，以便更新 IT 管理員所設設定的狀態。以下工作流程範例說明一種執行方式。

1. IT 管理員可透過 EMM 控制台為安裝在全代管裝置或工作資料夾中的應用程式，指定及傳送受管理的設定。例如：
   • 音量：「50%」
   • 貨幣：「USDD」
2. 應用程式會嘗試套用設定。已成功將磁碟區設為 50%，但貨幣代碼無效，因此無法套用。
3. 應用程式會根據各項設定的狀態設定金鑰的應用程式狀態。每個已鍵的應用程式狀態都包含專屬金鑰，以及含有狀態詳細資料的訊息。建議您盡可能比對受管理的設定金鑰。例如：

   鍵	訊息	嚴重程度	時間戳記
   volume	設為 50%	SEVERITY_INFO	1554461130
   currency	無法辨識貨幣「USDD」	SEVERITY_ERROR	1554461130

4. EMM 供應商會擷取應用程式設定的帶鍵應用程式狀態，並顯示在 EMM 控制台中。例如：

   設定	狀態	敬請採取行動	分秒必爭
   音量	設為 50%	否	2019 年 4 月 5 日上午 10:45:30
   貨幣	錯誤：無法辨識貨幣「USDD」。	是	2019 年 4 月 5 日上午 10:45:30

   EMM 供應商也應明確使用 SEVERITY_ERROR 標記任何收到的狀態至 IT 管理員。IT 管理員可以在 EMM 控制台中查看相關資訊，並採取行動修正設定中的任何錯誤。

回報已解決的錯誤

解決錯誤後，請立即傳送後續應用程式狀態，防止 EMM 無限期顯示錯誤訊息。此後續狀態應包含：

• 與初始錯誤訊息相同的金鑰。
• SEVERITY_INFO 的嚴重性，表示狀態未處於錯誤狀況，因此不需機構採取進一步行動。

在應用程式中新增對金鑰應用程式狀態的支援

下列步驟說明如何在應用程式中整合金鑰化應用程式狀態。

步驟 1：將 Google 的 Maven 存放區新增至您的 settings.gradle 檔案

將 Google 的 Maven 存放區新增為專案的 settings.gradle 檔案中的存放區位置，如下所示：

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
       google()
  }
}

步驟 2：將企業意見回饋程式庫新增至模組層級的 build.gradle 檔案

將以下依附元件新增至模組層級的 build.gradle 檔案：

dependencies {
    implementation 'androidx.enterprise:enterprise-feedback:1.0.0'
}

步驟 3：取得 KeyedAppStatesReporter 的執行個體

在您的 onCreate() 方法中，取得並儲存 KeyedAppStatesReporter 的例項。如此一來，應用程式與 EMM 供應商之間就能建立通訊管道。

val reporter = KeyedAppStatesReporter.create(context)

KeyedAppStatesReporter reporter = KeyedAppStatesReporter.create(context);

步驟 4：建立索引鍵應用程式狀態的集合

在建立具有金鑰的應用程式狀態時，請採用下列最佳做法：

• 請勿在任何狀態中加入個人識別資訊 (PII)，有鍵的應用程式狀態不適用於機密資料。
• 讓索引鍵的應用程式狀態保持在 MAX_KEY_LENGTH、MAX_MESSAGE_LENGTH 和 MAX_DATA_LENGTH 中定義的限制範圍內。
• 單一 setStates 或 setStatesImmediate 呼叫最多總計 300 KB (約每天可儲存的總資料量約 1/3)。超過這個上限時，就會產生未定義的行為。
• 只有在機構存在必須採取行動的問題時，才將狀態的嚴重性設為 SEVERITY_ERROR。
• 傳送含有錯誤的應用程式狀態時，請務必在錯誤解決後傳送後續追蹤狀態，讓 EMM 停止在控制台中標記錯誤。
• 針對後續追蹤狀態，請使用與傳回錯誤的初始狀態相同的金鑰，並將嚴重性設為 SEVERITY_INFO。

下列程式碼片段會建立索引鍵應用程式狀態的集合：

    val states = hashSetOf(KeyedAppState.builder()
             .setKey("key")
             .setSeverity(KeyedAppState.SEVERITY_INFO)
             .setMessage("message")
             .setData("data")
             .build())
    

    Collection states = new HashSet<>();
    states.add(KeyedAppState.builder()
     .setKey("key")
     .setSeverity(KeyedAppState.SEVERITY_INFO)
     .setMessage("message")
     .setData("data")
     .build());
    

步驟 5：設定金鑰的應用程式狀態

如果應用程式已安裝在裝置上，setStates() 方法會立即將帶鍵的應用程式狀態傳送至 Play 商店應用程式 (套件名稱：com.android.vending)，以及裝置或工作資料夾的任何管理員。

keyedAppStatesReporter.setStates(states)

keyedAppStatesReporter.setStates(states);

測試金鑰應用程式狀態