登录
目录
当前位置： 首页 > 文档资料 > 及策实时分析平台帮助文档 >

5.3 Android 接入文档中文版

优质
小牛编辑
146浏览
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.

  • 在MainActivity的onCreate()方法中加入如下代码. 其中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.** {
    *;
}
免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn