本文档描述了在集成 XAPP SDK 过程当中可能遇到的相关问题和解决方法。
一、常见配置问题
1.1. 在哪儿下载 XAPP SDK?
请到下载页面下载 XAPP SDK ：资源下载
1.2. 如何获得PID(产品ID)和CropID(企业ID)?
一般情况,通过对平台的账号注册即可得到一个企业ID（CorpID），有了企业后台账号之后，可以添加企业的产品，每个产品会有对应的产品ID生成，即可得到产品ID（PID），详情请通过链接了解。
1.3. 如何使用 XAPP SDK 自带的崩溃信息收集功能？
详情说明请参考进阶篇-SDK高级配置中，崩溃日志处理章节。
1.4. 第三方崩溃收集工具好像不能使用了？
请查看是否开启了 XAPP SDK 的崩溃信息收集功能。崩溃信息收集实际上是利用了 Java 中UncaughtExceptionHandler进行收集处理，若第三方崩溃收集工具使用了类似的方式处理则可能导致被 XAPP SDK 覆盖而无法正常使用。
建议如果使用第三方崩溃收集工具时，不要开启 XAPP SDK 的崩溃信息收集功能。该功能为辅助性功能，所有的崩溃信息仅保存到本地，并且无相应的崩溃信息分析工具（通常第三方工具会有功能丰富的崩溃信息工具）。
1.5. 为什么无法在控制台查看到日志输出？
请确认使用 XAPP SDK 时配置了日志输出功能setLogConfig(config)，同时一般情况下可以使用XLinkAndroidSDK.defaultConfig(context)提供的默认日志配置，该配置将会输出所有 debug 等级的日志并将 XAPP SDK 日志保存到文件中。
当需要将文件路径输出到指定位置而不是默认位置，也可以通过简单修改相关的配置自定义日志输出地址。
一般情况下建议在 Android 环境中使用XLinkAndroidSDK.defaultConfig(context)提供的配置文件作为母版进行更改，此时不需要自行实现 Loggable 接口。
//直接使用 XLinkAndroidSDK.defaultLogConfig 创建的Cofnig进行配置修改
//不需要实现Loggable接口
BaseLog.Config newConfig = XLinkAndroidSDK.defaultLogConfig(this)
.setDebugLevel(Loggable.ERROR)
.setEnableLogFile(false)
.setLogoutPath("xxx");请注意默认 XAPP SDK 日志不会自动输出到 Android 环境中 logcat 控制台，如果使用完全自定义的日志配置（即直接创建一个BaseLog.Config对象进行配置），请务必设置setLoggable(loggable)，通过对 Loggable 接口的实现将日志输出到 logcat。
BaseLog.Config config = new BaseLog.Config()
.setLoggable(new Loggable() {
@Override
public int log(int i, String s, String s1, Throwable throwable) {
//根据日志等级输出对应等级日志到 logcat
switch (i) {
case Loggable.DEBUG:
Log.d(s, s1);
break;
case Loggable.ERROR:
Log.e(s, s1);
break;
case Loggable.WARN:
Log.w(s, s1);
break;
}
return i;
}
});详情说明请参考[进阶篇-SDK高级配置](A-进阶篇/A-XAPP SDK高级配置.md)中，日志信息处理章节
二、常见数据端点问题
2.1. 多个设备同时上报数据端点都会收到事件回调么？
在 XAPP SDK 初始化时配置了XLinkDataListener，该回调用于监听数据端点变更时通知。当多个设备同时发生了数据端点变更并进行了上报时，只要 XAPP SDK 与设备保持着云端连接或内网连接，设备变更的数据端点即会通知到 XAPP SDK，XAPP SDK 进行处理后即会通过回调通知相应的变更事件。
如果 XAPP SDK 是与云端连接着，设备上报能正常上报到云端时，云端能下发到 XAPP SDK 则会回调该方法；如果 XAPP SDK 是设备保持内网连接着，设备上报时设备能将数据正常发送给 XAPP SDK，则XAPP SDK会回调该方法；
2.2. 为什么获取数据端点不全？
获取数据端点不全（或为空）时，对于通过内网获取与外网获取原因是有差异的。
- 在内网获取时
由于数据端点此时来源为设备，即设备会直接提供本身的数据端点，所以如果设备本身不存在数据端点（如 MCU 未上报数据端点信息给 Wifi 模块），则设备的 Wifi 模块也无法返回数据端点信息； - 在外网获取时
由于数据端点此时来源为云端，如果云端不存在缓存的数据端点信息时（如设备从未进行过上报数据给云端，云端也就不会有任何的缓存记录），则云端无法返回数据端点信息；
关于数据端点获取时，请留意以下情况：
- 该数据端点是否产品一开始定义是存在的，还是后续添加的
- 该数据数据端点是否为“虚拟数据端点”，即通过计算公式等方式产生的数据。如果是虚拟的数据端点，则直接通过设备获取时可能获取不到该数据端点，因为该数据端点只会在云端进行数据处理并更新信息。
- 设备本身在激活后是否有上报过该数据端点，若有的话请确认一下是平台的数据端点值与设备的数据端点值是否相同。确认方式可以如下操作：
- 在设备在线时（必须确保设备在线），登录管理台并查找到该设备
- 查看设备详情页面下方“实时数据”，若无数据信息可配置选择需要检验的数据端点
- 查看数据端点值信息。若存在数据说明设备已经上报过，若暂无数据说明设备未上报过该数据
若设备未上报过数据端点，则通过云端方式获取不到未上报过的数据端点值。产品中的数据端点配置仅仅是一个数据端点模板，对于实际的设备来说，当设备未进行对应索引的数据端点上报过时，平台不会保存该索引的数据端点值（因为不知道该数据端点到底可能值是什么），所以获取数据端点时是不存在未上报过的数据端点值的。
若以上建议无法解决问题，请尝试以下操作：
- 请将产品后台数据端点配置提供一下，并提供一下获取数据端点时输出的日志信息以确认该数据端点信息（注意若无法确认日志信息有效，也可以将 APP 开启到获取数据端点操作的完整日志一起提供，可以从日志中定位获取的数据端点模板信息是否正确有效，请开发人员根据应用过滤日志，避免大量系统日志），然后通过工单系统提出问题
- 如提供日志时，请提供对应产品 PID/MAC 及预期需要的数据端点索引及其信息
- 如果允许也可以直接提供企业 ID 与管理台账号信息，此方式更便于查找和发现问题
2.3. 为什么数据端点变更回调时，有时会没有设备模板信息？
关于数据端点的信息，数据端点的获取与更新实际上只会有数据端点的具体值和基本信息，数据端点的其它信息如描述等是由数据端点模板确定的。
XAPP SDK在默认情况下会去获取数据端点模板，但是该操作是异步的，并不会必须获取到模板的情况下才允许数据端点的获取与通知。所以当存在模板时，会使用模板信息更新数据；但是不存在模板时，数据端点仅会有基本数据。
模板功能为辅助功能，模板的使用在 XAPP SDK 中将尽可能保证有效，但无法确定任何时候都必然有效。如果需要确保数据端点模板任何时候都一定有效，建议自行进行模板信息维护。可通过XLinkGetDataPointMetaInfoTask任务获取到相关的产品的数据端点模板，详情请查看API-Task API
正常情况下，模板功能都是可用有效的，即使无效也仅会出现在最开始的时候，随着设备的使用只要该设备的模板不存在，XAPP SDK 都会在操作时尝试获取该设备的模板进行处理。
三、常见设备问题
3.1. 为什么扫描不到设备?
请按下述步骤进行排查：
- 设备是否跟 APP 在同一局域网内
- PID 设置是否正确
- 扫描超时是否设置过短（可能由于网络环境问题导致通讯不及时）
- 设备和 APP 的网络连接是否正常
- 使用 demo 进行扫描，对比结果
- 使用 IOS Demo 进行扫描，对比结果
- 使用 debug 模式开启 XAPP SDK ，查看具体日志
- 联系我们，提供相关操作或者日志信息(可以通过工单系统提出问题)
3.2. 为什么无法添加设备?
请按下述骤进行排查：
- 设备是否跟 APP 在同一局域网内
- 设备和 APP 的网络连接是否正常
- 登录管理后台确认设备是否正常上线
- 查看 onError 中返回的 errorCode 和异常信息
- 使用 debug 模式开启 XAPP SDK，查看具体日志
- 联系我们，提供相关的操作或者日志消息
3.3. 什么情况下会自动管理连接设备?
正常情况下，只要设备在维护列表中，即会对设备进行自动管理连接（包括云端连接与本地连接）。在以下情况下默认会将设备添加到设备维护列表中。
- 通过 XLinkSyncDeviceListTask 任务同步设备列表后设备将添加到维护列表中
- 通过 XLinkAddDeviceTask 添加订阅设备后设备将添加到维护列表中
部分情况下设备的本地连接是不一定需要的（如仅 Wi-Fi 使用的设备或 2G 设备），取决于某些操作是否有取消本地连接要求，可以进行连接管理方式的调整，默认情况下都会自动管理本地连接。
- 当开发者使用 XLinkSyncDeviceListTask 获取设备列表成功时，如果设置了
setConnectLocal(true)，XAPP SDK 自动对设备进行云端及本地连接。若设置不需要本地连接，则仅进行云端连接管理 - 当开发者使用 XLinkAddDeviceTask 添加新设备成功后，同样可设置
setConnectLocal(false)，处理同上所述
注意事项：v6.2版本与之前版本的设备自动管理连接策略是不一样的，详情请参考进阶篇-设备连接状态管理
3.4. XAPP SDK 如何管理设备连接状态?
正常情况下，开发者不需要自行维护设备的连接状态，由 XAPP SDK 内部进行连接和处理;
开发者对设备状态有跟踪需求时,可以通过设置设备状态监听达到及时正确处理设备状态的目的
详情说明请参考进阶篇-设备连接状态管理
3.5. 如何在扫描设备时判断设备是否已经被订阅了？
出于安全问题考虑，目前并无可以查询设备是否已经订阅过的接口。建议处理方式为直接对该设备进行订阅操作，如果返回订阅失败则可以确定该设备被订阅过。
四、常见用户问题
4.1. 为什么一直无法登录成功？
在登录操作中，不仅是通过账号密码登录服务器成功获取到用户 API 调用凭证即可，由于实际应用中会与设备进行通讯，而设备的通讯方式不依赖于 API 的调用。因此用户登录成功还需要与云端服务器（CM 服务器）建立连接。
如果无法登录成功时，可能是未能正确登录 HTTP 服务器获取用户调用作证，也可能是未能正确与云端服务器建立连接。请确认一下以下注意事项：
- APP 必须在网络通畅并能连接到外网的情况下才能登录成功，请确保 APP 可以正常使用外网。
- 请留意 API 服务器地址及端口是否配置正确，默认情况下 https 域名端口号对应为 443，http 域名端口号对应为 80。
- 请留意云端服务器地址及端口是否配置正确，使用公有云默认端口号为 1884，如果使用私有云地址，请自行确认使用的端口号。
- 请留意是否需要开启 SSL 的验证，默认公有云使用 1884 端口时需要开启 SSL 验证，开启方式请参考配置。
XLinkConfig config = XLinkConfig.newBuilder()`` ``//true为开启SSL验证，false为不开启`` ``.setEnableSSL(``true``)`` ``...`` ``.build();``XLinkAndroidSDK.init(config);- 如果使用私有云环境，并配置了 SSL 证书验证，请注意添加 SSL 验证。
XLinkConfig config = XLinkConfig.newBuilder()`` ``.setSSLFactoryProvider(``new` `SSLFactoryProviderable() {`` ``@Override`` ``public` `SocketFactory getSSLFactory() {`` ``//配置自行处理的SSL验证的对象，用于云端服务器连接使用`` ``return` `socketFactory;`` ``}`` ``})`` ``.setNetworkClientProcessor(``new` `NetworkClientProcessor() {`` ``@Override`` ``public` `void` `processorClient(OkHttpClient.Builder builder) {`` ``//配置自行处理SSL验证的对象，用于http请求`` ``builder.sslSocketFactory(socketFactory，trustManager);`` ``}`` ``})`` ``...`` ``.build();``XLinkAndroidSDK.init(config);4.2. 为什么账号被其它用户登录的情况下，启动 APP 会提示用户的 token 过期？
默认情况下同一时间同一账号不允许重复登录。该问题出现需要以下几个前提：
- 使用快捷登录功能
- APP 仅支持用户单点登录（即同一时间同一账号只能登录一次，不支持如多平台或多端登录）
- 用户在 APP1 登录后退出 APP1，之后该账号在其它 APP 或使用其它方式登录过
- 启动 APP 后立即进行快捷登录
当满足以上前提时，由于用户在其它地方已重新登录过，用户在 APP1 上原有的登录信息将失效，此时启动 APP1 将立即进行快捷登录，但是由于账号信息已经失效，因此将接收到 TOKEN_EXIPIRED 的错误。
如果需要为用户做自动登录，请注意处理好 token 过期的操作。该方式并不是踢掉用户，开发者可以自行处理为用户重新自动登录或者提示登录时间过长需要重新登录。请注意 token 是具有有效期的，如果长时间不登录（或者通过其它方式在其它地方进行了登录）必然会导致 token 过期。
注意：v6.2版本起强烈建议使用新的快捷登录方式，详情请参考进阶篇-用户授权管理
4.3. 什么情况下需要用户重新授权(登录)?
开发者应使用 XLinkUserAuthorizeTask 来进行用户授权（登录），只有用户授权后才能使用云端相关的功能（获取设备列表，云端连接等等）
如果 APP 已经保存了授权信息，那么在启动 XAPP SDK 时需提供（包装成 XLinkUser 对象传入），其后 XAPP SDK 启动后会自动进行授权管理。
快捷登录操作处理请参考进阶篇-用户授权管理快捷登录处理章节
未授权或者授权信息无效的情况下，开发者应主动调用 XLinkUserAuthorizeTask 进行授权，一般在登录页（Login/SignIn）进行。
4.4. 如果私有云环境使用了自签证书，需要如何处理？
如果使用私有云环境，并使用了自签证书，需要启用自定义的 SSL 验证，请通过以下方式添加 SSL 验证，更多详情可参考进阶篇-SDK高级配置
XLinkConfig config = XLinkConfig.newBuilder()`` ``.setSSLFactoryProvider(``new` `SSLFactoryProviderable() {`` ``@Override`` ``public` `SocketFactory getSSLFactory() {`` ``//配置自行处理的SSL验证的对象，用于云端服务器连接使用`` ``return` `socketFactory;`` ``}`` ``})`` ``.setNetworkClientProcessor(``new` `NetworkClientProcessor() {`` ``@Override`` ``public` `void` `processorClient(OkHttpClient.Builder builder) {`` ``//配置自行处理SSL验证的对象，用于http请求`` ``builder.sslSocketFactory(socketFactory，trustManager);`` ``}`` ``})`` ``...`` ``.build();``XLinkAndroidSDK.init(config);4.5. 用户退出登录状态的原因有什么？
如果 Token 过期或者被同一账号踢下线，那么void onUserLogout(LogoutReason reason)会被调用。登出原因一般情况下有三种：
- 用户主动退出
- token 过期
- 用户账号被踢出
其中后两种登出原因要求用户应该重新进行登录操作，才能进行重新授权并使用XAPP SDK相关的功能。
注意事项：XAPP SDK 在 token 过期/账号踢出的情况下都会自动中止（即进行了 stop 操作），注意再次使用时需要启动 XAPP SDK ，详情请参考开发指南
详情说明请参考进阶篇-用户授权管理
4.6. XAPP SDK 中如何维护凭证（token） ？
请参考 进阶篇-用户授权管理 相关章节详细说明了用户凭证如何维护。
五、常见 API 问题
5.1. 错误码处理
错误码在v5版本与v6版本 XAPP SDK 中是不同的，v6 XAPP SDK 中的错误码将更加准确具体以及携带足够的信息用于辅助处理与分析。
- 对于v5版本升级到v6版本中错误码的变更,请参考版本升级
- 对于v6版本中错误码列表请参考[APP-SDK错误码](../5）APP SDK错误码.md)
- 对于v6版本中新旧错误码的对照说明请参考API-错码说明与使用
六、其它问题（与 SDK 无关）
6.1. 为什么注册或修改密码邮件接收不到？
邮件发送是通过第三方邮件服务发送的，邮件是否能发送成功需要满足第三方邮件服务规则。通常有可能是发送人的格式存在问题（如部分邮件服务商不允许发送人携带如逗号、小数点等特殊符号），相关发件要求或规则可参考：邮件服务商规则
七、更新说明
| 日期 | 更新内容 |
|---|---|
| 2019.05.11 | 更新获取不到数据端点的问题说明；新增邮件无法接收到的问题说明； |
| 2018.10.11 | 更新部分用户及设备常见问题解答，新增数据端点相关的问题解答 |
| 2018.05.18 | 针对v6版本 XAPP SDK 更新所有问题 |
