5.3 Android 接入文档中文版

优质
小牛编辑
151浏览
2023-12-01

开发环境


  • Android 版本
    • Android SDK 要求最低系统版本为 API 17(Android 4.2),集成之前请将Android SDK升级到API 17及以上。
  • v4兼容包 SDK内部使用到了Pair类,需要依赖android-support-v4.jar,请在工程内集成或替换最新版本的v4包即可。

集成 SDK


第1步:导入SDK

  • Eclipse ADT

    • 登录及策网站,点击右下角设置,进入APP信息管理页面,点击Andriod SDK按钮下载SDK。将jicesdk.jar拷贝到工程的libs目录下,重新build工程即可。

第2步: 添加相关权限到 AndroidManifest.xml

导入我方SDK后,需配置设备信息相关权限到 AndroidManifest.xml,我方才可以获取用户相关设备信息,配置完成后默认授权我方进行数据采集,同时建站方应在用户首次激活APP时添加相关隐私协议声明获取用户同意。

<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 网络状态相关权限 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- 设备信息相关权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<!-- 缓存推送活动图片文件读写权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

初始化 SDK


第1步: 从Jice网站获取appkey

登录及策网站,点击右下角设置,进入APP信息管理页面,获取appkey.

第2步: 在AndroidManifest.xml中配置appkey

在你的应用AndroidManifest.xml文件的application节点下为应用配置AppKey

<meta-data android:name="com.admaster.jicesdk.appKey" android:value="Jice网站为您分配的appkey" />

第3步: 在 main activity 中引入Jice instance

在程序入口Activity中引入 com.admaster.jicesdk.api.JiceSDK,调用 getInstance(Context context, JiceConfig config) 初始化SDK;

说明:建议开发者将初始化接口放到android:name="android.intent.category.LAUNCHER"属性Activity的onCreate()方法中,确保每次启动APP时都能调用即可。如果在自定义的Application内初始化SDK,可能会由第三方服务在独立进程工作使自定义Application多次初始化,会引起JiceSDK初始化时统计事件异常。

  • API参数
    • appKey: JICE系统为您分配的应用唯一标识符.
    • config:SDK 配置类,如果你想做一些自定义设置,可以移步自定义SDK配置查看更详细的说明.
JiceSDK mJiceAPI = JiceSDK.getInstance(getApplicationContext(), new JiceConfig());

恭喜,按照上述步骤,您已经完成了SDK的基础集成,您可以重新启动app,登录Jice系统,进入事件分析,按截图选择启动事件,如果事件总数不为0,则说明,您已经嵌入成功。您可能需要等几分钟才能看到数据。

追踪事件


在完成了SDK的基础集成后,您可以调用mJiceAPI.trackEventName来进行事件追踪。在进行事件追踪之前,需要您的运营人群在Jice网站定义好需要追踪的事件,并导出代码文件给您,您只需要把事件追踪代码放到事件触发的位置即可。

  • API参数
    • eventname :事件名称,需为英文,例如addtocart.
    • eventlabels: 事件属性,属性的key需为英文,例如,itemprice。
void trackEventName(String eventName,HashMap<String, ?> eventlabels)
  • 示例
//加入购物车时 
HashMap<String, Object> eventlabel = new HashMap<String, Object>();
eventlabel.put("pid", 22473); // item id
eventlabel.put("itemname", "tshirt"); // item name
eventlabel.put("itemprice", 800); // item price
mJiceAPI.trackEventName("productview", eventlabel);

您也可以调用如下方法进行事件追踪。

void trackEventName(String eventname)
void trackEventName(String eventname, JSONObject eventlabels)
  • 注意事项:

    • 事件名称参数必填,事件属性可选;
    • 事件名称 key 和事件属性 key 必须和在Jice系统中设置的相同,否则无法在Jice系统中查看该事件的数据;
    • 最多可以支持 50 个事件,每个事件最多能添加 20 个属性。

恭喜,按照上述步骤,您已经完成了SDK的事件追踪设置,您可以登录Jice系统,进入事件分析,选择您追踪的事件,如果事件总数不为0,则说明,您已经嵌入成功。您可能需要等几分钟才能看到数据。

追踪用户信息


如果想进一步追踪触发事件的用户信息,您需要调用mJiceAPI.addUserIdentifier方法。在进行用户信息追踪之前,需要您的运营人群在Jice网站定义好需要追踪的用户属性,并导出代码文件给您。

  • 当用户注册时候进行调用该接口,传入用户的属性。
  • 当用户编辑更新个人信息后需要调用重新设置用户属性;

  • API参数

    • userid: 用户的唯一标识符,不能为空。
    • properties:用户属性, 例如:昵称、性别等,用户属性key需为英文。
void addUserIdentifier(String userId, HashMap<String, Object> properties)
  • 示例
HashMap<String, Object> profile = new HashMap<String, Object>();
profile.put("name", "Jim");//昵称
profile.put("gender", "Male");//性别
profile.put("birthday", "1990-10-12");//生日
profile.put("email","vip@jice.com");//邮箱
mJiceAPI.addUserIdentifier("421484", profile);//421484 用户id
  • 注意事项:

    • 用户属性key和在Jice系统中设置的必须一致,否则无法在Jice系统中查看该事件的数据。

恭喜,按照上述步骤,您已经完成了SDK的用户信息追踪设置。您可以登录Jice系统,进入用户分析,当用户注册成功后,您可以在用户列表中看到该用户。您可能需要等几分钟才能看到数据。

应用内推送设置


Jice系统提供强大的应用内消息推送功能,可以将特定的消息推送给特定的人群,在使用这个神奇的功能之前,您需要做如下工作:

第1步: 定义展示推送消息的时机

例如,您是一名电商app的开发人员,您的运营人员希望在用户进入生鲜类商品列表页面时,展示一条推送消息,那么您需要做如下事情。

AndroidManifest.xml 中的application标签内添加 JiceSDK推送视图。

<activity android:name="com.admaster.jicesdk.api.JicePushActivity"         
    android:theme="@android:style/Theme.Translucent.NoTitleBar" />

目标Activity界面,例如生鲜类商品列表页面Activity的OnCreate()方法中调用addJicePushView接口。

  • API参数
    • context: 上下文环境对象。
    • jiceViewCallback:如果您想在展示推送或点击推送时做一些额外的操作,例如,点击推送后进入到某个页面,您需要实现JiceViewListener中相应的方法,具体见下一步。
void addJicePushView(Context context,JiceViewListener jiceViewCallback)
  • 示例
mJiceAPI.addJicePushView(MainActivity.this, new JiceViewListener() {

    @Override
    public void onJiceViewWillShow() {
        //todo something
    }

    @Override
    public void onJiceViewShowed() {
        //todo something
    }

    @Override
    public void onJiceViewError(String errorMsg) {
        //todo something
    }

    @Override
    public void onJiceViewDismissed() {
        //todo something
    }

    @Override
    public void onJiceViewClicked(String clickUrl) {
        //todo something
    }
});

第2步: 定义点击推送消息后的操作

例如,用户点击推送消息后,您希望他进入某个页面,那么您需要实现JiceViewListener中的onJiceViewClicked:方法。其中clickUrl是在Jice系统中填写的跳转链接。SDK统一作为字符串传输,开发者可以根据需求对其他格式的数据自行解析进行相应处理

当然,你也可以实现JiceViewListener中的其他方法,在推送展示和点击的过程中进行其他处理。

  • 示例
mJiceAPI.addJicePushView(MainActivity.this, new JiceViewListener() {

    @Override
    public void onJiceViewWillShow() {
        //todo something
    }

    @Override
    public void onJiceViewShowed() {
        //todo something
    }

    @Override
    public void onJiceViewError(String errorMsg) {
        //todo something
    }

    @Override
    public void onJiceViewDismissed() {
        //todo something
    }

    //Open clickUrl in the default operater
    @Override
    public void onJiceViewClicked(String clickUrl) {
        Intent intent = new Intent();
        intent.setAction("android.intent.action.VIEW");
        Uri destUri = Uri.parse(clickUrl);
        intent.setData(destUri);
        startActivity(intent);
    }
});
  • 在onJiceViewError方法中可用的错误码枚举值
JicePushShowError.JicePushNoData = 1000, // 没有推送数据
JicePushShowError.JicePushIsShowing = 1001, // 推送正在展示中
JicePushShowError.JicePushNoNet = 1002, // 暂时没有网络
JicePushShowError.JicePushIsDownloading = 1003;// 推送正在下载中

第3步: 集成线上测试模式

我们建议在正式推送消息前,先进行真机测试,这样可以查看推送活动的展示和点击效果是否和预期的一致。

  • 定义url scheme, 在Manifest中的MainActivity标签内添加scheme属性。
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- url scheme -->
    <data android:scheme="com.admaster.jicedemo" />
</intent-filter>
  • 在Jice网站中录入此url scheme.

  • MainActivityonCreate()方法中加入如下代码. 其中getIntent() 将会返回被测试推送消息的相关信息。
    mJiceAPI.handleOpenURL(getIntent());
    

在完成上述步骤后,应用内推送的设置就已经完成了。您或者您的运营人员登录及策系统,新建推送活动,通过二维码扫描测试,如果活动流程正常,则表示已经嵌入成功。您可能需要等几分钟才能看到数据。

自定义SDK设置


SDK还支持一些自定义设置,例如发送监测数据包的网络策略等,如果有相关需求,可以在JiceSDK.getInstance(Context context, JiceConfig config)时,通过实例化 JiceConfig类来控制相关策略。

  • API参数

    • isEventWifiOnly: 追踪事件的上报网络策略,可以设置为true或者false.默认值为false,代表在wifi或者(2/3/4G)网络下都进行上报。
    • isPushWifiOnly:推送活动展示的网络策略. 可以设置为true或者false.默认值为false,代表在wifi或者(2/3/4G)网络下都进行展示。
    • debugMode: 设置为调试模式,可以看到内部打印的Log日志,方便调试。
    • isOldUser: 设置设备已激活,标识用户是否在SDK使用前已经激活过设备,开发者如果设置为true,则后台不会再把这台设备算为新激活用户,默认为false。
    • pushServerURL: 支持私有化部署,设置推送下发的服务器地址,默认会发送到jice推送服务器地址。
    • trackServerURL: 支持私有化部署,设置事件上报的服务器地址,默认会发送到jice事件服务器地址。
JiceConfig(boolean isEventWifiOnly, boolean isPushWifiOnly, boolean debugMode, boolean isOldUser, String pushServerURL, String trackServerURL)
  • 示例
@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    JiceSDK.getInstance(this, new JiceConfig(false,false,true,false,null,null));

    //如果不需要标识旧用户和私有化部署,可以使用三个参数的初始化函数
    //JiceSDK.getInstance(this, new JiceConfig(false, false, false));

}

混淆配置


如果您的项目使用了 Proguard 混淆打包,为了避免 SDK 被二次混淆导致无法使用,请在 proguard-project.txt 中添加以下代码:

-dontwarn com.admaster.**
-keep class com.admaster.** {
    *;
}