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://static.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.*{;}