X-SDK Android 集成
在 Android App 应用中，X-SDK 是一串针对某个应用的 Java 代码，你可以在创建完成一个Android应用或在应用设置的地方找到，在开始进行体验数据收集时，需要确保 X-SDK 已经成功集成到你的应用中。
我们在 github 上放置了浩客的集成 demo repo 代码库，可以进行查看.
浩客 Android SDK 通过 Java 进行开发，通过 gradle 引入 AAR 包进行引用。
注意：SDK / API level 最低支持版本为：Level 21
| 最新AAR 包下载地址 | 描述 | 发布时间 |
|---|---|---|
| https://howxm.com/sdks/android/HowxmSDK-V3.3.0.aar | 极大地优化SDK网络请求，丰富了debug模式的日志 | 2023-11-01 |
Step 1：创建 Android App 应用
创建应用时，选择应用类型「Android」，并完善应用信息，包括应用名称（必填）及 App Package Name（非必填）。
Step2：复制 SDK 代码进行集成
在创建完成一个Android应用后，可以在左侧的「应用设置」里下载 Android SDK AAR 包、找到 SDK 代码。
你可以自行完成 SDK 集成，也可以下载SDK代码交由研发人员处理。如有任何疑问请随时联系我们，会有专业客户顾问为你解答。
Android App 集成示例代码：
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.howxm.knowhow.sdk.api.Howxm;
public class MainActivity extends AppCompatActivity {
private static final String APP_ID = "your app id";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//为了避免ANR，可以放在子线程进行初始化
Howxm.initializeSDK(APP_ID, MainActivity.this);
}
@Override
protected void onResume() {
super.onResume();
//在onResume 的时候，也需要调用initializeSDK 来保障sdk正常工作
Howxm.initializeSDK(APP_ID, MainActivity.this);
}
}
注意：该代码只可应用于所绑定的 Android App，在进行集成之前，请确认应用ID是否正确。
获取应用ID
你可以在 应用设置-App 设置 中直接复制应用ID。
Step3：验证 SDK 集成是否生效
在完成第二步 SDK 代码集成后，你可以访问所集成 X-SDK 代码的App应用，就可以看到 X-SDK 集成的状态变为 绿色 ，点击会提示App连通中，可以对评价、问卷进行正常投放。
否则你将会看到「App 未连通」的红色提醒：
需要检查SDK代码是否正确安装，或者确认应用绑定的应用ID是否正确。
注意：如果在72小时内，X-SDK没有收到来自目标App的访问数据时，也会出现「App 未连通」的提醒，你可以再次进入App应用，状态即可恢复。
Step 4：投放问卷、评价，回收数据
当 SDK 集成完毕，即可使用浩客评价、问卷等相关能力；也可以邀请团队成员加入到你的应用中，协作进行管理。
* 创建一个评价
* 创建一个问卷
* 邀请团队成员加入
X-SDK 接口能力
X-SDK 的接口信息、参数、使用场景，请先查看 接口文档
在完成 X-SDK 集成后，可以使用相关的接口能力进行用户身份验证、复杂的免打扰机制，完成更加复杂的场景，比如：
- 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放
- 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察
- 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等
在完成 X-SDK 集成后，可以使用相关的接口能力进行用户身份验证、复杂的免打扰机制，完成更加复杂的场景，比如：
- 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放
- 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察
- 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等
1. identify 用户身份信息传递
接口信息，详细可查看：identify
以下为示例代码：
/* 方法定义: */
/**
* 当你可以获取用户身份信息时，可以调用 identify 方法传入用户信息，将数据与用户进行关联
*
* @param customer 当前登录客户的信息
*/
public static void identify(@NonNull Customer customer);
/* 示例代码：*/
Customer customer = new Customer();
customer.setUid("当前用户的唯一ID (required)"); // 必填
// 选填，自定义用户属性，传入后在浩客后台查询
Map<String, Object> customerAttrs = new HashMap<>();
customerAttrs.put("customer_1", "c001");
customer.setCustomerAttrs("传入其他用户属性，例如生日、会员等级、套餐信息等等。属性以 key:value 的形式传入，目前支持数字、字符串、日期类型的数据");
Howxm.identify(customer);
2. event 抛出事件接口
接口信息，详细可查看：event
以下为示例代码：
/* 方法定义: */
/**
* @param eventCode 事件code，必填
* @param eventExtra 触发事件时的一些自定义定义，比如当前页面的访问次数等
* @param context 需要进行弹框的Activity Context
*/
Howxm.event(@NonNull String eventCode, Map<String, Object> eventExtra,@NonNull Context context);
/* 示例代码：*/
Context context = "获取当前页面的context";
Map<String, Object> eventExtra = new HashMap<>();
eventExtra.put("pageAccessTimes",3);//页面访问次数
Howxm.event("eventCode", eventExtra, context);
注意：当触发方式为「通过传入事件触发」时，投放规则自动生效。
3. checkOpen 弹出策略检查接口
接口信息，详细可查看：checkOpen
以下为示例代码：
/* 方法定义: */
/**
* 校验是否需要弹出投放问卷，会进行免打扰规则的校验
*
* @param campaignId 通过浩客后台获取
* @param uid 当前登录的客户信息，如果是匿名用户，可以不传入
* @return 是否允许弹出问卷，如果为false，则该用户需要被免打扰，如果为true，则可以进行问卷投放，参考 {@link #open(String, Customer, Map, Context)}
*/
public static boolean checkOpen(@NonNull String campaignId, String uid);
/* 示例代码：*/
String campaignId=""; // 问卷/评价ID
String uid="uid" // 可为空
// boolean，返回true，表示可调用open()进行投放，返回false，表示当未通过投放规则校验，投放失败
boolean shouldOpen = Howxm.checkOpen(campaignId,uid);
传入参数说明:
| 字段 | 说明 | 是否必填 | 类型 | 备注 |
|---|---|---|---|---|
| campaignId | 问卷/评价ID | 必填 | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取 |
| uid | 用户id | 必填 | String 类型 | 用于识别唯一用户身份 |
错误情况：
1. 传入不存在的campaignId，网络请求404
4. open 弹出问卷接口
接口信息，详细可查看：open
以下为示例代码：
/* 方法定义: */
/**
* 对当前用户进行问卷投放显示
*
* @param campaignId 通过浩客后台获取
* @param customer 当前登录的客户信息，如果是匿名用户，可以不传入
* @param extraAttrs 当前投放场景下的场景参数，场景参数/一次性字段字段在浩克后台页面获取
*/
public static void open(@NonNull String campaignId, Customer customer, Map<String, Object> extraAttrs, @NonNull Context context);
/* 示例代码：*/
Context context = "获取当前页面的context";
String campaignId=""; // 问卷/评价ID
Customer customer = new Customer(); // 可为空
customer.setUid("uid")
Map<String, Object> eventExtra = new HashMap<>();
eventExtra.put("pageAccessTimes",3);//页面访问次数
Howxm.open(campaignId,customer,eventExtra,context);
注意：当触发自动弹出方式为「通过代码调用 Open 触发」时，建议代码调用 checkOpen 使投放规则生效
String campaignId=""; // 问卷/评价ID
String uid="uid" // 可为空
// boolean，返回true，表示可调用open()进行投放，返回false，表示当未通过投放规则校验，投放失败
boolean shouldOpen = Howxm.checkOpen(campaignId,uid);
5. register 注册事件回调
通过此方法可注册全局回调事件，在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下：
Howxm.onBeforeOpen(new Howxm.OnBeforeOpenListener() {
@Override
public void onBeforeOpen(String campaignId, String uid, Map<String, Object> extraAttrs) {
Log.i("LOG_TAG", "OnBeforeOpen: campaignId=" + campaignId + ",uid=" + uid + ",extraAttrs=" + extraAttrs);
}
});
Howxm.onOpen(new Howxm.OnOpenListener() {
@Override
public void onOpen(String campaignId, String uid, Map<String, Object> extraAttrs) {
Log.i("LOG_TAG", "OnOpen: campaignId=" + campaignId + ",uid=" + uid + ",extraAttrs=" + extraAttrs);
}
});
Howxm.onPageComplete(new Howxm.OnPageCompleteListener() {
@Override
public void onPageComplete(String campaignId, String uid, List<FieldEntry> fieldsEntry) {
Log.i("LOG_TAG", "OnPageComplete: campaignId=" + campaignId + ",uid=" + uid + ",fieldsEntry=" + fieldsEntry);
}
});
Howxm.onComplete(new Howxm.OnCompleteListener() {
@Override
public void onComplete(String campaignId, String uid) {
Log.i("LOG_TAG", "OnComplete: campaignId=" + campaignId + ",uid=" + uid + ");
}
});
Howxm.onClose(new Howxm.OnCloseListener() {
@Override
public void onClose(String campaignId, String uid) {
Log.i("LOG_TAG", "OnClose: campaignId=" + campaignId + ",uid=" + uid);
}
});
回调阶段定义
| 名称 | 说明 |
|---|---|
| onBeforeOpen | 问卷展示前调用 |
| onOpen | 问卷展示后调用 |
| onClose | 问卷在屏幕消失后调用 |
| onComplete | 用户提交了最后一页题目后调用 |
| onPageComplete | 用户每提交一页，系统调用一次 |
打包注意事项
- 打包后需要在代码混淆文件中添加： -keep class com.howxm.knowhow.sdk.*{;}