EloView Home SDK 6.23.14

支持的平台： Android 12 和 Android 14 Elo 设备，包括 Backpack 4（标准/增值），I-Series 4（标准/增值），I-Series 标准，M50，M60 Pay，M100，以及 7 英寸 Pay。

完整参考（知识库 + SDK Javadoc）

API 按功能类别（系统、网络、包等）组织，以简化发现和加速实现。

---

全球最佳实践（来自 KB）

1. 始终在调用任何 API 之前绑定服务。
   在收到 onServiceConnected() 之前，请勿调用方法。

2. 假设设备策略可以覆盖本地设置。
   这对于时间、时区、USB、亭模式和应用程序安装尤其正确。

3. 在生产中使用 NTP 进行时间同步。
   除了测试外，请避免手动配置时间。

4. 了解重置行为。

   • 企业重置 清除 Elo 配置和注册状态。

   • 出厂重置 删除所有用户数据并将设备恢复到开箱状态。

5. 记录每个 API 调用的结果。
   这对于故障排除和升级至关重要。

---

常见真实场景（来自 KB）

场景：设备注册后时区不正确

system.setNtpEnabled(true);
system.setNtpServer("time.aws.com");
system.setTimeZone("US/Central");
system.syncTimeNow();

// 验证
String tz = system.getTimeZone();
Log.d(TAG, "Timezone=" + tz);

提示：如果重启后时区恢复，请验证 Android 自动时区是否启用，并确保设备策略未重新应用不同的区域。

场景：安全配置单应用亭模式

pkg.setKioskApp("com.example.kiosk");
pkg.setKioskModeEnabled(true);
pkg.launchApp("com.example.kiosk");

警告： 永远在生产中启用亭模式之前验证管理逃生路径。

服务绑定模板（来自 KB）

eloView.bindService(context, callback, accessToken);
// 在 callback.onServiceConnected() 内安全调用 SDK API
eloView.unbindService(context);

重要提示： bindService() 和 unbindService() 不返回值。SDK API 只能在 onServiceConnected() 被调用后执行。

核心 / 服务绑定 API

EloView

EloView 类提供以下操作：

• 在设备处于离线或未注册到帐户的 EloView 控制模式下，使用 setOfflinePlayContent() 设置要播放的内容。
• 使用 getPlayContent() 检索当前在 EloView 控制模式下设置的内容的类型（APK 或 WebView）和名称。
• 使用 getPlayContentStatus() 获取在 EloView 控制模式下配置内容的当前播放状态。
• 使用 getDeviceCloudStatus() 检查设备是否当前连接到 EloView Cloud（在线或离线）。
• 使用 toggleWifi() 在 Elo 快捷设置和 Android 主屏幕模式中切换 Wi-Fi。
• 使用 toggleBT() 在 Elo 快捷设置和 Android 主屏幕模式中切换蓝牙。

bindService

public void bindService(android.content.Context context, ServiceConnectionCallback callback, java.lang.String accessToken)

此方法将 EloView 服务绑定到应用程序。在调用任何 EloView API 之前，必须首先调用此方法。

参数

• context – 使用 EloView API 的上下文。

例如

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.bindService(context, callback, "accessToken");
    Log.d(TAG, "OK: bindService result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: bindService", e);
}

unbindService

public void unbindService(android.content.Context context)

此方法用于从应用程序中解绑服务。在清除资源时使用此方法。

参数

• context – 上下文

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.unbindService(context);
    Log.d(TAG, "OK: unbindService result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: unbindService", e);
}

setOfflinePlayContent

public java.lang.String setOfflinePlayContent(java.lang.String packageName)

此方法用于在设备处于离线或未注册到帐户的 EloView 控制模式下设置要播放的内容。如果设备上线并通过 EloView 设置了内容，则会覆盖通过此 API 设置的内容。

参数

• packageName – 要在设备上设置为默认内容的包。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.setOfflinePlayContent("packageName");
    Log.d(TAG, "OK: setOfflinePlayContent result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: setOfflinePlayContent", e);
}

getPlayContent

public java.lang.String getPlayContent()

此方法返回设备上设置的内容的类型和名称。此方法仅在 EloView 控制模式下工作。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getPlayContent();
    Log.d(TAG, "OK: getPlayContent result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getPlayContent", e);
}

getPlayContentStatus

public java.lang.String getPlayContentStatus()

此方法返回设备在控制模式下播放内容的状态。状态可以是以下字符串之一：

YET_TO_DOWNLOAD, DOWNLOADING, DOWNLOADED, INSTALLING, INSTALLED, DOWNLOAD_FAILED, INSTALL_FAILED, UNKNOWN_STATUS

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getPlayContentStatus();
    Log.d(TAG, "OK: getPlayContentStatus result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getPlayContentStatus", e);
}

getDeviceCloudStatus

public java.lang.String getDeviceCloudStatus()

此方法返回设备的在线或离线状态。状态可以是以下字符串之一： "在线"、"离线"、"连接中"、"重新连接中"、"在线（未配置）"。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getDeviceCloudStatus();
    Log.d(TAG, "OK: getDeviceCloudStatus result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getDeviceCloudStatus", e);
}

toggleWifi

void toggleWifi(boolean isEnableWifi)

启用或禁用设备上的 Wi-Fi。这适用于 EloView 模式和 Android 主屏幕模式。

参数

• isEnableWifi – Boolean，用于在快速设置中启用或禁用 Wi-Fi。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.toggleWifi(true);
    Log.d(TAG, "OK: toggleWifi result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: toggleWifi", e);
}

switchToAndroidHomeMode

void switchToAndroidHomeMode() void switchToAndroidHomeMode(boolean isRebootNeeded, boolean isAndroidHomeMode)

此方法用于从 EloView 模式切换到 Android 主屏幕模式。此方法与 switchToAndroidHomeMode() 的区别在于，它接受两个布尔参数。 没有办法在没有工厂重置的情况下切换回 EloView 模式，因此请谨慎使用。

参数

• 将设备从 EloView 模式切换到 Android 主屏幕模式。
• 如果 isRebootNeeded 设置为 true，则设备将在应用模式更改时重启。
• 重要提示：切换到 Android 主屏幕模式可能会禁用 EloView 管理的限制和策略。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.switchToAndroidHomeMode(true, true);
    Log.d(TAG, "OK: switchToAndroidHomeMode result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: switchToAndroidHomeMode", e);
}

toggleBT

public int toggleBT(boolean isEnableBT)

此方法用于在快速设置中切换蓝牙（EloView 模式）或在 Android 主屏幕模式中 切换蓝牙。

参数

• isEnableBT – Boolean，用于在快速设置中启用或禁用蓝牙。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.toggleBT(true);
    Log.d(TAG, "OK: toggleBT result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: toggleBT", e);
}

帐户 API

AccountManager

AccountManager 类提供以下操作：

1. 根据用户提供的凭据（emailId/password 或 clientId/secretKey）从 EloServer 提供认证令牌。

2. 验证给定认证令牌是否有效或已过期。认证令牌可以是从 EloView 服务器获取的令牌，也可以是由 Elo 支持团队提供的离线 JWT 令牌。 （离线令牌是使用您的应用程序的包名生成的，只能与其生成的包一起使用。）

3. 所有 API 都需要离线令牌才能工作，不能使用在线令牌。唯一的例外是 OTA API。应用 OTA 时，OTA API 需要在线令牌。通过自定义服务器 URL 或设备上的本地文件应用 OTA 时，可以使用离线令牌。

例如，获取认证令牌：

1. 使用 emailId 和密码调用 getEloAccessToken。 2. 使用 clientId 和 secretKey，调用 getEloOAuthToken。在成功认证后，这些方法将返回一个令牌。 3. 对于离线 JWT 令牌，请联系 Elo 支持团队。

从服务器或支持团队检索到的令牌通过 verifyEloToken 方法进行验证。

使用 unregisterAccountManagerListener 方法注册用于这些 AccountManager API 的广播接收器，以避免内存泄漏。 请确保在使用这些 API 的活动的 onPause 和 onDestroy 方法中调用此方法。

getProperty

public static java.lang.String getProperty()

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getProperty();
    Log.d(TAG, "OK: getProperty result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getProperty", e);
}

setProperty

public void setProperty(java.lang.String property)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.setProperty("property");
    Log.d(TAG, "OK: setProperty result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: setProperty", e);
}

getClientId

public static java.lang.String getClientId()

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getClientId();
    Log.d(TAG, "OK: getClientId result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getClientId", e);
}

getBaseUri

public static android.net.Uri getBaseUri()

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getBaseUri();
    Log.d(TAG, "OK: getBaseUri result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getBaseUri", e);
}

getEloAccessToken

public void getEloAccessToken(android.content.Context context, java.lang.String userEmail, java.lang.String password, android.os.Handler handler)

此方法用于从 Elo 服务器获取访问令牌。

参数

• context – 调用类的上下文对象（Activity 或 Service）。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getEloAccessToken(context, "userEmail", "password", handler);
    Log.d(TAG, "OK: getEloAccessToken result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getEloAccessToken", e);
}

configureOAuthHostedUI

public void configureOAuthHostedUI(android.app.Activity activity, android.os.Handler handler)

此方法用于初始化 OAuth 托管 UI。

参数

• activity – 调用类的 Activity 实例。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.configureOAuthHostedUI(activity, handler);
    Log.d(TAG, "OK: configureOAuthHostedUI result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: configureOAuthHostedUI", e);
}

stopOAuth

public void stopOAuth()

在活动的 onStop() 重写方法中调用 stopOAuth。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.stopOAuth();
    Log.d(TAG, "OK: stopOAuth result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: stopOAuth", e);
}

destroyOAuth

public void destroyOAuth()

在活动的 onStop() 重写方法中调用 destroyOAuth。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.destroyOAuth();
    Log.d(TAG, "OK: destroyOAuth result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: destroyOAuth", e);
}

logoutOAuth

public void logoutOAuth()

调用 logoutOAuth 以结束当前登录会话。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.logoutOAuth();
    Log.d(TAG, "OK: logoutOAuth result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: logoutOAuth", e);
}

verifyEloToken

public void verifyEloToken(android.content.Context context, java.lang.String accessToken, android.os.Handler handler)

此函数请求 Elo 服务器验证给定令牌。验证成功后，处理程序将收到类型为 TOKEN_VERIFY_SUCCESS 的消息。出现故障时，将收到 TOKEN_VERIFY_FAIL。

参数

• context – 调用类的上下文对象（Activity 或 Service）。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.verifyEloToken(context, "accessToken", handler);
    Log.d(TAG, "OK: verifyEloToken result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: verifyEloToken", e);
}

getEloOAuthToken

public void getEloOAuthToken(android.content.Context context, java.lang.String clientID, java.lang.String secret, android.os.Handler handler)

此方法用于请求 EloView 门户获取新的 OAuth 令牌。认证成功后，令牌将发送到设备。此令牌在发出后的 24 小时内有效。 当令牌过期时，进一步尝试验证令牌和调用 API 将获得 TOKEN_VERIFY_FAIL 响应。 如果从未获得或收到令牌，情况也相同。

如果成功，处理程序将收到类型为 OAUTH_TOKEN_VALID 的消息。 以下是成功响应的示例：

如因错误的 clientID 或 secretID 导致认证失败，处理程序将收到类型为 OAUTH_TOKEN_INVALID 的消息。

参数

• context – 调用类的上下文对象（Activity 或 Service）。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getEloOAuthToken(context, "clientID", "secret", handler);
    Log.d(TAG, "OK: getEloOAuthToken result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getEloOAuthToken", e);
}

unregisterAccountManagerListener

public void unregisterAccountManagerListener(android.content.Context context)

此方法用于注销在使用任何 AccountManager API 时注册的广播接收器。 如果您使用了任何 AccountManager API，请确保在活动的 “onPause” 和 “onDestroy” 方法中调用此方法，以确保接收器不会泄漏。

参数

• context – 在其中使用系统 API 的上下文。
• context – 用于注销账户管理器监听器的 Android 上下文。

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.unregisterAccountManagerListener(context);
    Log.d(TAG, "OK: unregisterAccountManagerListener result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: unregisterAccountManagerListener", e);
}

setDefaultEnvironment

public void setDefaultEnvironment(android.content.Context ctx)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.setDefaultEnvironment(context);
    Log.d(TAG, "OK: setDefaultEnvironment result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: setDefaultEnvironment", e);
}

getClientId

public static java.lang.String getClientId()

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getClientId();
    Log.d(TAG, "OK: getClientId result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getClientId", e);
}

getBaseUri

public static android.net.Uri getBaseUri()

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.getBaseUri();
    Log.d(TAG, "OK: getBaseUri result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: getBaseUri", e);
}

setProperty

public void setProperty(java.lang.String property)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.setProperty("property");
    Log.d(TAG, "OK: setProperty result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: setProperty", e);
}

文件 API

DocumentManager

DocumentManager 类提供文档管理功能，包括：

• 上传文件。
• 删除文件。
• 列出目录中的文件。

uploadFile

public boolean uploadFile(java.lang.String filePath)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.uploadFile("filePath");
    Log.d(TAG, "OK: uploadFile result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: uploadFile", e);
}

deleteFile

public boolean deleteFile(java.lang.String fileName)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.deleteFile("fileName");
    Log.d(TAG, "OK: deleteFile result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: deleteFile", e);
}

listFiles

public java.util.List listFiles(java.lang.String directory)

示例

try {
    // TODO: 确保在调用 SDK API 之前绑定服务
    Object result = sdk.listFiles("directory");
    Log.d(TAG, "OK: listFiles result=" + result);
} catch (Exception e) {
    Log.e(TAG, "FAIL: listFiles", e);
}