{"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 21**\r\n\r\n\r\n| 最新AAR 包下载地址 | 描述   |发布时间 |\r\n| -------- | -------- | -------- |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.3.0.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.3.0.aar)       | 极大地优化SDK网络请求，丰富了debug模式的日志 |2023-11-01     |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.3.1.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.3.1.aar)       |优化init逻辑，避免频繁获取设备信息|2024-03-06     |\r\n| [https://static.howxm.com/sdks/android/HowxmSDK-V3.3.2.aar](https://static.howxm.com/sdks/android/HowxmSDK-V3.3.2.aar)       | identify 支持 successCallback 和 failedCallback 回调 |2024-09-12     |\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);\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);\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![](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- 打包后需要在代码混淆文件中添加： \\-keep class com.howxm.knowhow.sdk.**{*;}","featured":false,"category_id":4,"created_at":"2023-02-15T01:19:24.567Z","updated_at":"2024-09-12T07:50:35.763Z"}