Skip to content
This repository has been archived by the owner on Jan 13, 2020. It is now read-only.

Latest commit

 

History

History
449 lines (347 loc) · 13.3 KB

README.md

File metadata and controls

449 lines (347 loc) · 13.3 KB

Sugo Android SDK 使用文档

1. SDK 集成

集成 Sugo Android SDK 有三种方式，选择其中一种即可。

1.1 Gradle 集成

dependencies {
    compile 'io.sugo.android:sugo-android-sdk:2.3.2'
}

如果需要支持XWalkView，请另外再添加
(如果不知道这个，就不需要)

dependencies {
    compile 'io.sugo.android:sugo-xwalkview-support:2.1.0'
}

2. SDK 配置

请先登录您的【数果星盘】管理台，在数据管理-埋点项目-新建项目-新建应用中，创建您的应用，以获取对应的项目配置等。

2.1 AndroidManifest.xml 基本配置

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    >

    <!-- 必要的权限 -->
    <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.BLUETOOTH"/>

  <application

    >
    ...
  </application>
</manifest>
  • SDK 配置说明

以下配置不包括{}，填入配置时，请删除大括号{}

2.1.0 权限说明

2.1.1 调试模式

开启调试模式，可以输出 SugoSDK 的日志

    <meta-data
        android:name="io.sugo.android.SGConfig.EnableDebugLogging"
        android:value="true"/>

2.1.2 Token 配置

必填

    <meta-data
        android:name="io.sugo.android.SGConfig.token"
        android:value="{YOUR_TOKEN}" />

2.1.3 Project Id 配置

必填

    <meta-data
        android:name="io.sugo.android.SGConfig.ProjectId"
        android:value="{YOUR_PROJECT_ID}" />

2.1.4 埋点配置地址

必填

    <meta-data
        android:name="io.sugo.android.SGConfig.APIHost"
        android:value="{API_URL}" />

2.1.5 可视化埋点地址

必填

<meta-data
        android:name="io.sugo.android.SGConfig.EditorHost"
        android:value="{EDITOR_URL}" />

2.1.6 数据上报地址

必填

    <meta-data
        android:name="io.sugo.android.SGConfig.EventsHost"
        android:value="{EVENTS_URL}" />

2.1.7 扫码跳转页面

在启动的 Activity 上（该 Activity 不能在初始化Sugo.startSugo()被调用之前），配置

    <intent-filter>
        <data android:scheme="sugo.{YOUR_TOKEN}"/>
        <action android:name="android.intent.action.VIEW"/>

        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>

2.1... 代码混淆

如果您的应用使用了代码混淆， 请添加


#保护注解
-keepattributes *Annotation*
#不混淆资源类
-keepclassmembers class **.R$* {
    public static <fields>;
}
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}
-keepattributes *JavascriptInterface*

-keep class android.view.* { *; }
-keep class io.sugo.* { *; }
-keep class io.sugo.android.metrics.SugoAPI { *; }
-keep class io.sugo.android.metrics.SugoWebEventListener { *; }
-keep class io.sugo.android.metrics.SugoWebNodeReporter { *; }

3. SDK 使用

添加依赖

    compile 'com.android.support:support-annotations:{support_version}'
    compile 'com.android.support:support-compat:{support_version}'
    compile 'com.android.support:support-v4:{support_version}'

初始化

    SugoAPI.startSugo(this, SGConfig.getInstance(this));

标准的使用实例，应该是在 APP 启动的第一个Activity中，添加以下代码

public class MainActivity extends Activity {

    SugoAPI mSugo;

    public void onCreate(Bundle saved) {
        // SDK 将会初始化，此处若设置 Token 、 ProjectId，将覆盖 AndroidManifest 中的设置
        SugoAPI.startSugo(this, SGConfig.getInstance(this)
            .logConfig());

        // 获取 SugoAPI 实例，在第一次调用时，
        mSugo = SugoAPI.getInstance(this);
        ...
    }

    // 使用 SugoAPI.track 方法来记录事件
    public void whenSomethingInterestingHappens(int flavor) {
        JSONObject properties = new JSONObject();
        properties.put("flavor", flavor);
        mSugo.track("Something Interesting Happened", properties);
        ...
    }

    public void onDestroy() {
        // 如果启动的 Activity 不是最后销毁的 Activity，
        // 这行代码可以移到对应的最后销毁的 Activity 的 onDestroy 方法里
        mSugo.flush();      // 非必须，仅推荐使用
        super.onDestroy();
    }
}

3.1 基本功能

3.1.1 自定义事件

调用 SugoAPI.track()实现在代码中埋点来统计一次用户行为 参数说明

  • eventId : 事件 id
  • eventName : 事件名称
  • properties : 事件的属性
SugoAPI sugoAPI = SugoAPI.getInstance(context);

JSONObject props = new JSONObject();
props.put("Gender", "Female");
props.put("Plan", "Premium");

sugoAPI.track("Plan Selected", props);

3.1.2 时长事件

调用SugoAPI.timeEvent()来追踪一个事件发生的时长，例如统计一次图片上传所消耗的时间

SugoAPI sugoAPI = SugoAPI.getInstance(context);

// start the timer for the event "Image Upload"
sugoAPI.timeEvent("Image Upload");

// stop the timer if the imageUpload() method returns true
if(imageUpload()){
    sugoAPI.track("Image Upload");
}

3.1.3 首次登录

调用 SugoAPI.login(userIdKey, userIdValue) 来记录一次用户登录行为（后台需要配置用户表）
其中，userIdKey 是上报 userIdValue 的维度名，userIdValue 一般是用户标识，例如 SugoAPI.login("userId", 123456) 。
调用 login之后，如果是第一次登录，则触发【首次登录】事件，并且将来所有上报的事件都会带上【首次登录时间】【userIdKey】这个维度。
调用 SugoAPI.logout() 退出登录，这两个维度将不会继续上报。

3.1.3 开启 H5 埋点

3.1.3.1. WebView 支持
    webView.getSettings().setJavaScriptEnabled(true);
    SugoAPI instance = SugoAPI.getInstance(this);
    instance.addWebViewJavascriptInterface(webView);
    webView.setWebViewClient(new SugoWebViewClient() {
    });
    webView.loadUrl("http://sugo.io");

如果开发者不能实现或继承SugoWebViewClient，想要设置自己的WebViewClient， 则需要在自己的WebViewClient的onPageFinished()回调里， 调用SugoWebViewClient.handlePageFinished(webView, url)即可

webView.setWebViewClient(new WebViewClient() {
        @Override
        public void onPageFinished(WebView view, String url) {
            super.onPageFinished(view, url);
            SugoWebViewClient.handlePageFinished(webView, url);
        }
    });
3.1.3.2 XWalkView 支持

如果您想要在项目中支持 XWalkView 的可视化埋点 ，可以使用以下代码 (先要引用 sugo android sdk 的 xwalk 扩展库)

  • 1 初始化 SugoAPI 是，使能 XWalkView
    // 首先，在第一次初始化 SugoAPI 的时候，使能 XWalkView 功能
    mSugoAPI = SugoAPI.getInstance(this);
    SugoXWalkViewSupport.enableXWalkView(mSugoAPI, true);
  • 2 然后，在 XWalkView 使用的 Activity (继承了 XWalkActivity ) 中, 调用SugoXWalkViewSupport.handleXWalkView
  • 3 接着，调用XWalkView.setResourceClient 重写 onLoadFinished方法，调用SugoXWalkViewClient.handlePageFinished 即可完成
    @Override
    protected void onXWalkReady() {
        mXWalkView = (XWalkView) findViewById(R.id.xwalkview);
        SugoXWalkViewSupport.handleXWalkView(SugoAPI.getInstance(this), mXWalkView);
        mXWalkView.setResourceClient(new XWalkResourceClient(mXWalkView) {
                    @Override
                    public void onLoadFinished(XWalkView view, String url) {
                        super.onLoadFinished(view, url);
                        SugoXWalkViewClient.handlePageFinished(view, url);
                    }
                });
        mXWalkView.load("http://sugo.io", null);
    }
  • 4 最后，在onCreate 中调用XWalkPreferences.setValue(XWalkPreferences.ANIMATABLE_XWALK_VIEW, true); 才能使得 XWalkView 的网页内容被上传至可视化埋点
3.1.3.3 H5 代码埋点

在进行了 3.1.3.1 或 3.1.3.2 的操作之后，SugoSDK 可支持 H5 的可视化埋点。 如果需要代码埋点，可在 js 中调用以下方法：

自定义事件，参数如下： 参数说明

  • event_id : 事件 id
  • event_name : 事件名称
  • props : 事件的属性
sugo.track(event_id, event_name, props);

时长事件（可参照 3.1.2）

sugo.timeEvent(event_name);

3.1.4 默认属性

有一种很常见的情况，你想让一些常见的属性在每一个事件中都添加上，因此，你可以将这些属性注册为默认属性。

默认属性是保存在设备上的，将会持续存在 APP 里。 SugoSDK 也设置了一些默认的默认属性，点这里查看

想要设置默认属性，调用SugoAPI.registerSuperProperties

SugoAPI sugoAPI = SugoAPI.getInstance(context);

// Send a "User Type: Paid" property will be sent with all future track calls.
JSONObject props = new JSONObject();
props.put("User Type", "Paid");
sugoAPI.registerSuperProperties(props);

接下来，你记录的任何事件，这些默认属性都会被一起发送。 默认属性是存储在设备上的，退出 APP 后下次启动，该默认属性依旧存在。

只设置一次默认属性 通过SugoAPI.registerSuperProperties会强行覆盖已有的同名属性，如果有些属性你想只设置一次（例如第一次登录的时间），可以调用SugoAPI.registerSuperPropertiesOnce，这个方法只保存第一次设置时的值，后面对该属性的修改操作将无效。

移除默认属性 通过SugoAPI.unregisterSuperProperty可移除已设置的默认属性

3.2 热图

2 在启动的 Activity 上，配置

如果已经配置了可视化埋点，这里也是一样的，可以跳过

    <intent-filter>
        <data android:scheme="sugo.c6749a4f1ef039ca196148ed1cb65d87"/>

        <action android:name="android.intent.action.VIEW"/>

        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>

在控制台网页点击【埋点热图】，使用浏览器扫描二维码，跳转到该App，即可进入热图模式。

1 进入热图模式后，热图模式将一直存在，只有 kill 掉 App 进程才会退出 2 在热图模式中，无法进入可视化埋点，反之，在可视化埋点模式时，无法进入热图

4 Q&A

Q. 定位 View 失败
A. SDK 通过资源 id 定位 View，如果 applicationId 与应用包名不一致，则需要修改

        <meta-data
            android:name="io.sugo.android.SGConfig.ResourcePackageName"
            android:value="{YOUR_PACKAGE_NAME}" />

Sugo SDK 之 Weex 扩展

Weex 支持

Weex 是一套简单易用的跨平台开发方案，能以 web 的开发体验构建高性能、可扩展的 native 应用,
若要支持 Weex 生成的页面，请额外添加

    compile 'io.sugo.android:weex:0.0.1'

首先，在原生代码中，注册 Sugo SDK Weex 扩展模块

必须先确保 Weex SDK 已正确添加到项目中

    WXSDKEngine.registerModule("sugo", WXSugoModule.class);

接着，在 JS 中引入模块

  var sugo = weex.requireModule('sugo');

最后，调用相关的功能

  1. 记录事件：track(eventName, props)
    例如：
sugo.track("buycart", {"productId","p123456"});
  1. 记录时常事件：timeEvent(eventName)
    例如：
    sugo.timeEvent("play")      // 开始记录时间
    ...
    ...
    sugo.track("play",{});      // 事件记录
  1. 超级属性
    sugo.registerSuperProperties(props)     // 注册超级属性
    sugo.registerSuperPropertiesOnce(props) // 注册不可覆盖的超级属性
    sugo.unregisterSuperProperty(propName)  // 取消注册
    sugo.getSuperProperties(callback)       // 获取已有的超级属性
    sugo.clearSuperProperties()             // 清除所有超级属性
  1. 登录统计：sugo.login(userIdKey, userIdValue)
    sugo.login("userId", "123456") // "userId" 是一个自定义的字段
    
    sugo.logout()                  // 退出登录
  1. web 组件埋点支持（仅安卓需要额外的代码，iOS 将自动支持）
    <template>
        <web ref="webview" :src="url" @pagestart="start" @pagefinish="finish" @error="error"></web>
    </template>
    <script>
        export default {
            mounted() {
                sugo.initWebView(this.$refs.webview);
            },
            methods: {
                finish() {
                    sugo.handleWebView(url, this.$refs.webview);
                }
            }
        }
    </script>