{"id":33,"type":"Article","title":"X-SDK Android 集成","slug":"x-sdk-andriod","content":"在 Android App 应用中，X-SDK 是一串针对某个应用的 Java 代码，你可以在创建完成一个Android应用或在应用设置的地方找到，在开始进行体验数据收集时，需要确保 X-SDK 已经成功集成到你的应用中。\r\n\r\n我们在 github 上放置了浩客的集成 demo repo 代码库，[可以进行查看](https://github.com/howxm). \u003cbr\u003e\r\n\r\n浩客 Android SDK 通过 Java 进行开发，通过 gradle 引入 AAR 包进行引用。\r\n\r\n**注意：SDK / API level 最低支持版本为：Level 28**\r\n\r\n\r\n| 最新AAR 包下载地址 | 描述   |发布时间 |\r\n| -------- | -------- | -------- |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.4.3.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.4.3.aar)       | 修复极少数场景下因页面切换时序导致弹窗异常关闭引发的crash |2026-01-06     |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.4.2.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.4.2.aar)       | 解决某些情况下context失效导致无法弹出问卷 |2025-07-16     |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.4.1.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.4.1.aar)       | 支持自定义checkOpen接口的超时时间 |2025-06-16     |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.4.0.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.4.0.aar)       | 不再获取ANDROID_ID敏感信息 |2025-06-03     |\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cstrong\u003eX-SDK Android 个人信息处理规则说明\u003c/strong\u003e\u003c/summary\u003e\r\n\r\n为保障用户合法权益，现公开 **X-SDK Android** 的个人信息处理规则如下：\r\n\r\n### 一、信息采集声明\r\n\r\n1. **当前版本未收集任何设备标识信息**，包括但不限于：\r\n   - IMEI（国际移动设备识别码）\r\n   - MAC 地址（Wi-Fi、蓝牙等网络硬件标识）\r\n   - Android ID、OAID、设备序列号等\r\n\r\n2. SDK 不会主动读取、存储或传输任何属于《中华人民共和国个人信息保护法》中定义的：\r\n   - “个人信息”\r\n   - “敏感个人信息”\r\n\r\n### 二、权限声明情况\r\n\r\n- 当前 SDK **不请求任何 Android 敏感权限**；\r\n- 未使用以下权限：\r\n  - `READ_PHONE_STATE`\r\n  - `ACCESS_WIFI_STATE`\r\n  - `PACKAGE_USAGE_STATS`\r\n- 不会主动触发系统权限弹窗，也不包含隐性权限请求逻辑。\r\n\r\n### 三、第三方依赖与数据链条\r\n\r\n- 当前 SDK **无任何第三方组件嵌套依赖**；\r\n- 未集成任何第三方广告平台、分析工具（如友盟、百度统计等）；\r\n- 不会通过如下方式绕过权限限制：\r\n  - WebView 注入或加载远程网页\r\n  - 使用 JavaScript Bridge 进行本地数据访问\r\n  - 拉取远程配置或动态行为配置\r\n\r\n### 四、联系方式\r\n\r\n如有任何问题，请联系开发者团队：\r\n\r\n📧 **support@howxm.com**\r\n\r\n\u003c/details\u003e\r\n\r\n\r\n\r\n\r\n# **Step 1：创建 Android App 应用**\r\n创建应用时，选择应用类型「Android」，并完善应用信息，包括应用名称（必填）及 App Package Name（非必填）。\r\n![](https://help-assets.jinshuju.net/assets/file/1261/WeChatWorkScreenshot_ef513b00-948d-4bf0-9db0-76474749fb0e.png)\r\n# **Step2：复制 SDK 代码进行集成**\r\n在创建完成一个Android应用后，可以在左侧的「应用设置」里下载 Android SDK AAR 包、找到 SDK 代码。\r\n![](https://help-assets.jinshuju.net/assets/file/1262/WeChatWorkScreenshot_02d410da-93d6-454b-93af-a2248b4d4283.png)\r\n\r\n你可以自行完成 SDK 集成，也可以下载SDK代码交由研发人员处理。如有任何疑问请随时联系我们，会有专业客户顾问为你解答。\r\n![](https://help-assets.jinshuju.net/assets/file/1263/WeChatWorkScreenshot_b2efb4bd-72f0-4ba7-9769-a15f027f259b.png)\r\n\r\nAndroid App 集成示例代码：\u003cbr\u003e\r\n\r\n```java\r\nimport android.os.Bundle;\r\n\r\nimport androidx.appcompat.app.AppCompatActivity;\r\nimport com.howxm.knowhow.sdk.api.Howxm;\r\n\r\npublic class MainActivity extends AppCompatActivity {\r\n\r\n    private static final String APP_ID = \"your app id\";\r\n\r\n    @Override\r\n    protected void onCreate(Bundle savedInstanceState) {\r\n        super.onCreate(savedInstanceState);\r\n        setContentView(R.layout.activity_main);\r\n\t\t\t\t//为了避免ANR，可以放在子线程进行初始化\r\n        Howxm.initializeSDK(APP_ID, MainActivity.this, clientID);\r\n    }\r\n\r\n    @Override\r\n    protected void onResume() {\r\n        super.onResume();\r\n        //在onResume 的时候，也需要调用initializeSDK 来保障sdk正常工作\r\n        Howxm.initializeSDK(APP_ID, MainActivity.this, clientID);\r\n    }\r\n}\r\n```\r\n**注意：该代码只可应用于所绑定的 Android App，在进行集成之前，请确认应用ID是否正确。**\u003cbr\u003e\r\n\r\n**获取应用ID**\r\n\r\n你可以在 **应用设置-App 设置** 中直接复制应用ID。\r\n\r\n**clientId**\r\nclientId作为对匿名用户投放时用户的唯一标识，免打扰校验使用。\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1361/28.png)\r\n\r\n# **Step3：验证 SDK 集成是否生效**\r\n在完成第二步 SDK 代码集成后，你可以访问所集成 X-SDK 代码的App应用，就可以看到 X-SDK 集成的状态变为   绿色  ，点击会提示App连通中，可以对评价、问卷进行正常投放。\r\n![](https://help-assets.jinshuju.net/assets/file/1265/WeChatWorkScreenshot_ac0cb42d-98e3-49bf-9b05-d2c77b41473a.png)\r\n\r\n否则你将会看到「App 未连通」的红色提醒：\r\n![](https://help-assets.jinshuju.net/assets/file/1264/WeChatWorkScreenshot_bdb66328-21ac-4113-b3cb-05176536711d.png)\r\n\r\n需要检查SDK代码是否正确安装，或者确认应用绑定的应用ID是否正确。\u003cbr\u003e\r\n\u003cbr\u003e\r\n**注意：如果在72小时内，X-SDK没有收到来自目标App的访问数据时，也会出现「App 未连通」的提醒，你可以再次进入App应用，状态即可恢复。**\u003cbr\u003e\r\n\r\n# **Step 4：投放问卷、评价，回收数据**\r\n当 SDK 集成完毕，即可使用浩客评价、问卷等相关能力；也可以邀请团队成员加入到你的应用中，协作进行管理。\u003cbr\u003e\r\n\u003cbr\u003e\r\n* **[创建一个评价](https://howxm.com/help/articles/create-feedback)**\u003cbr\u003e\r\n* **[创建一个问卷](https://howxm.com/help/articles/create-survey)**\u003cbr\u003e\r\n* **[邀请团队成员加入](https://howxm.com/help/articles/apps-team)**\u003cbr\u003e\r\n\r\n# **X-SDK 接口能力**\r\n\r\n**X-SDK 的接口信息、参数、使用场景，请先查看  [接口文档](https://howxm.com/help/articles/x-sdk-api)**\r\n\r\n在完成 X-SDK 集成后，可以使用相关的接口能力进行用户身份验证、复杂的免打扰机制，完成更加复杂的场景，比如：\u003cbr\u003e\r\n\u003cbr\u003e\r\n- 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放\u003cbr\u003e\r\n- 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察\u003cbr\u003e\r\n- 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等\u003cbr\u003e\r\n\u003cbr\u003e\r\n在完成 X-SDK 集成后，可以使用相关的接口能力进行用户身份验证、复杂的免打扰机制，完成更加复杂的场景，比如：\u003cbr\u003e\r\n\u003cbr\u003e\r\n- 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放\u003cbr\u003e\r\n- 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察\u003cbr\u003e\r\n- 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n\r\n# **1. identify 用户身份信息传递**\r\n\r\n接口信息，详细可查看：[identify](https://howxm.com/help/articles/x-sdk-api#1-identify)\r\n\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```java\r\n/* 方法定义: */\r\n/**\r\n * 当你可以获取用户身份信息时，可以调用 identify 方法传入用户信息，将数据与用户进行关联\r\n *\r\n * @param customer 当前登录客户的信息\r\n*/\r\n public static void identify(@NonNull Customer customer);\r\n \r\n/* 示例代码：*/\r\nCustomer customer = new Customer();\r\ncustomer.setUid(\"当前用户的唯一ID (required)\"); // 必填\r\n\r\n// 选填，自定义用户属性，传入后在浩客后台查询\r\nMap\u003cString, Object\u003e customerAttrs = new HashMap\u003c\u003e();\r\ncustomerAttrs.put(\"customer_1\", \"c001\");\r\ncustomer.setCustomerAttrs(\"传入其他用户属性，例如生日、会员等级、套餐信息等等。属性以 key:value 的形式传入，目前支持数字、字符串、日期类型的数据\"); \r\n\r\nHowxm.identify(customer);\r\n```\r\n\r\n\r\n# **2. event 抛出事件接口**\r\n\r\n接口信息，详细可查看：[event](https://howxm.com/help/articles/x-sdk-api#2-event)\r\n\r\n\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```java\r\n/* 方法定义: */\r\n/**\r\n* @param eventCode 事件code，必填\r\n* @param eventExtra 触发事件时的一些自定义定义，比如当前页面的访问次数等\r\n* @param context 需要进行弹框的Activity Context\r\n*/\r\nHowxm.event(@NonNull String eventCode, Map\u003cString, Object\u003e eventExtra,@NonNull Context context);\r\n\r\n/* 示例代码：*/\r\nContext context = \"获取当前页面的context\";\r\nMap\u003cString, Object\u003e eventExtra = new HashMap\u003c\u003e();\r\neventExtra.put(\"pageAccessTimes\",3);//页面访问次数\r\nHowxm.event(\"eventCode\", eventExtra, context);\r\n```\r\n**注意：当触发方式为「通过传入事件触发」时，投放规则自动生效。**\u003cbr\u003e\r\n\r\n\r\n\r\n# **3. checkOpen 弹出策略检查接口**\r\n\r\n接口信息，详细可查看：[checkOpen](https://howxm.com/help/articles/x-sdk-api#3-checkopen)\r\n\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```java\r\n/* 方法定义: */\r\n/**\r\n  * 校验是否需要弹出投放问卷，会进行免打扰规则的校验\r\n  *\r\n  * @param campaignId 通过浩客后台获取\r\n  * @param uid        当前登录的客户信息，如果是匿名用户，可以不传入\r\n  * @return 是否允许弹出问卷，如果为false，则该用户需要被免打扰，如果为true，则可以进行问卷投放，参考   {@link #open(String, Customer, Map, Context)}\r\n */\r\npublic static boolean checkOpen(@NonNull String campaignId, String uid);\r\n\r\n/* 示例代码：*/\r\nString campaignId=\"\"; // 问卷/评价ID\r\nString uid=\"uid\" // 可为空\r\n\r\n// boolean，返回true，表示可调用open()进行投放，返回false，表示当未通过投放规则校验，投放失败\r\nboolean shouldOpen = Howxm.checkOpen(campaignId,uid);\r\n\r\n```\r\n**传入参数说明:**\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **字段**     | **说明** | **是否必填** | **类型**    | **备注**      |\r\n|------------|--------|----------|-----------|-------------|\r\n| campaignId | 问卷/评价ID  | 必填       | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取|\r\n| uid        | 用户id   | 必填       | String 类型 | 用于识别唯一用户身份  |\r\n\r\n\u003cbr\u003e\r\n\r\n**错误情况**：\u003cbr\u003e\r\n1. 传入不存在的campaignId，网络请求404\r\n\u003cbr\u003e\r\n\r\n\r\n\r\n# **4. open 弹出问卷接口**\r\n\r\n接口信息，详细可查看：[open](https://howxm.com/help/articles/x-sdk-api#4-open)\r\n\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```java\r\n/* 方法定义: */\r\n/**\r\n  * 对当前用户进行问卷投放显示\r\n  *\r\n  * @param campaignId 通过浩客后台获取\r\n  * @param customer   当前登录的客户信息，如果是匿名用户，可以不传入\r\n  * @param extraAttrs 当前投放场景下的场景参数，场景参数/一次性字段字段在浩克后台页面获取\r\n */\r\npublic static void open(@NonNull String campaignId, Customer customer, Map\u003cString, Object\u003e extraAttrs, @NonNull Context context);\r\n\r\n/* 示例代码：*/\r\nContext context = \"获取当前页面的context\";\r\nString campaignId=\"\"; // 问卷/评价ID\r\nCustomer customer = new Customer(); // 可为空\r\ncustomer.setUid(\"uid\")\r\nMap\u003cString, Object\u003e eventExtra = new HashMap\u003c\u003e();\r\neventExtra.put(\"pageAccessTimes\",3);//页面访问次数\r\nHowxm.open(campaignId,customer,eventExtra,context); \r\n\r\n```\r\n**注意：当触发自动弹出方式为「通过代码调用 Open 触发」时，建议代码调用 checkOpen 使投放规则生效**\u003cbr\u003e\r\n\r\n```java\r\n\r\nString campaignId=\"\"; // 问卷/评价ID\r\nString uid=\"uid\" // 可为空\r\n\r\n// boolean，返回true，表示可调用open()进行投放，返回false，表示当未通过投放规则校验，投放失败\r\nboolean shouldOpen = Howxm.checkOpen(campaignId,uid);\r\n\r\n```\r\n\r\n# **5. register 注册事件回调**\r\n通过此方法可注册全局回调事件，在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下：\r\n\r\n```\r\nHowxm.onBeforeOpen(new Howxm.OnBeforeOpenListener() {\r\n    @Override\r\n    public void onBeforeOpen(String campaignId, String uid, Map\u003cString, Object\u003e extraAttrs) {\r\n        Log.i(\"LOG_TAG\", \"OnBeforeOpen: campaignId=\" + campaignId + \",uid=\" + uid + \",extraAttrs=\" + extraAttrs);\r\n    }\r\n});\r\nHowxm.onOpen(new Howxm.OnOpenListener() {\r\n    @Override\r\n    public void onOpen(String campaignId, String uid, Map\u003cString, Object\u003e extraAttrs) {\r\n        Log.i(\"LOG_TAG\", \"OnOpen: campaignId=\" + campaignId + \",uid=\" + uid + \",extraAttrs=\" + extraAttrs);\r\n    }\r\n});\r\nHowxm.onPageComplete(new Howxm.OnPageCompleteListener() {\r\n    @Override\r\n    public void onPageComplete(String campaignId, String uid, List\u003cFieldEntry\u003e fieldsEntry) {\r\n        Log.i(\"LOG_TAG\", \"OnPageComplete: campaignId=\" + campaignId + \",uid=\" + uid + \",fieldsEntry=\" + fieldsEntry);\r\n    }\r\n});\r\nHowxm.onComplete(new Howxm.OnCompleteListener() {\r\n    @Override\r\n    public void onComplete(String campaignId, String uid) {\r\n        Log.i(\"LOG_TAG\", \"OnComplete: campaignId=\" + campaignId + \",uid=\" + uid + \");\r\n    }\r\n});\r\nHowxm.onClose(new Howxm.OnCloseListener() {\r\n    @Override\r\n    public void onClose(String campaignId, String uid) {\r\n        Log.i(\"LOG_TAG\", \"OnClose: campaignId=\" + campaignId + \",uid=\" + uid);\r\n    }\r\n});\r\n```\r\n\r\n回调阶段定义\r\n\r\n| 名称                            | 说明                                                       |\r\n|--------------------------|---------------------------------------------|\r\n| onBeforeOpen            | 问卷展示前调用                                    |\r\n| onOpen                      | 问卷展示后调用                                     |\r\n| onClose                      | 问卷在屏幕消失后调用                          |\r\n| onComplete               | 用户提交了最后一页题目后调用            |\r\n| onPageComplete       | 用户每提交一页，系统调用一次            |\r\n\r\n# **其他接口**\r\n\r\n### setCheckOpenTimeout\r\n**checkOpen会默认的等待时间为2000毫秒，超时后直接返回false，可通过该接口修改等待时间，单位毫秒**\r\n```\r\nHowxm.setCheckOpenTimeout(5000); \r\n```\r\n\r\n\r\n### setClientId\r\n**clientId作为对匿名用户的免打扰校验，由于安全合规性问题，当前默认是生成随机数缓存到内存中，用户可以通过该接口主动自定义clientId，比如使用ANDROID_ID（安全合规的情况下)**\r\n```\r\nHowxm.setClientId(Settings.System.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID)); \r\n```\r\n\r\n# 打包注意事项\r\n- 打包后需要在代码混淆文件中添加： \\-keep class com.howxm.knowhow.sdk.**{*;}","featured":false,"category_id":4,"created_at":"2023-02-15T01:19:24.567Z","updated_at":"2026-01-06T03:27:26.178Z"}