{"id":15111155,"url":"https://github.com/datafruit/sugo-android-sdk","last_synced_at":"2025-09-27T13:30:29.223Z","repository":{"id":57736272,"uuid":"75692559","full_name":"Datafruit/sugo-android-sdk","owner":"Datafruit","description":null,"archived":true,"fork":false,"pushed_at":"2019-10-08T03:44:11.000Z","size":11548,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-09-27T00:01:51.226Z","etag":null,"topics":["android","codeless","sdk","sugo"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Datafruit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-06T03:53:03.000Z","updated_at":"2023-01-28T16:07:14.000Z","dependencies_parsed_at":"2022-08-23T19:00:46.238Z","dependency_job_id":null,"html_url":"https://github.com/Datafruit/sugo-android-sdk","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Datafruit%2Fsugo-android-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Datafruit%2Fsugo-android-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Datafruit%2Fsugo-android-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Datafruit%2Fsugo-android-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Datafruit","download_url":"https://codeload.github.com/Datafruit/sugo-android-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234438014,"owners_count":18832604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","codeless","sdk","sugo"],"created_at":"2024-09-26T00:01:53.865Z","updated_at":"2025-09-27T13:30:28.679Z","avatar_url":"https://github.com/Datafruit.png","language":"Java","readme":"# Sugo Android SDK 使用文档   \n\n## 1. SDK 集成   \n\u003e 集成 Sugo Android SDK   \n\n**通过 Gradle 集成**   \n```Groovy   \ndependencies {\n    compile 'io.sugo.android:sugo-android-sdk:2.3.5'\n}\n```\n\n添加 sugo sdk 依赖后，进入项目管理 / SDK 接入 / Android 接入页面，点击【接入说明】按钮，   \n拷贝 SDK 配置，运行 app 即可完成接入。   \n\n如需了解更多详细配置和功能使用，可继续往下看。   \n\n**Weex 支持**    \n\u003e Weex 是一套简单易用的跨平台开发方案，能以 web 的开发体验构建高性能、可扩展的 native 应用,   \n若要支持 Weex 生成的页面，请额外添加   \n\n```Groovy    \n    compile 'io.sugo.android:sugo-weex:0.0.1'\n```\n\n**XWalkView 支持**   \n\n\u003e 如果需要支持`XWalkView`，请另外再添加   \n(如果不知道这个，就不需要)   \n\n```Groovy   \n    compile 'io.sugo.android:sugo-xwalkview-support:2.1.0'\n```\n\n---\n\n## 2. SDK 配置   \n\n\u003e 请先登录您的【数果星盘】管理台，在数据管理-埋点项目-新建项目-新建应用中，创建您的应用，以获取对应的 Token 等。   \n\n![image](doc/img/create_app.png)   \n\n![image](doc/img/APP_INFO.png)   \n\n\n\n### 2.1 AndroidManifest.xml 基本配置   \n```xml   \n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    \u003e\n\n    \u003c!-- 必要的权限 --\u003e\n    \u003cuses-permission android:name=\"android.permission.INTERNET\"/\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/\u003e\n    \u003cuses-permission android:name=\"android.permission.READ_PHONE_STATE\"/\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH\"/\u003e\n\n  \u003capplication\n\n    \u003e\n    ...\n  \u003c/application\u003e\n\u003c/manifest\u003e\n```\n\n- SDK 配置说明   \n\n\u003e 以下配置不包括`{}`，填入配置时，请删除大括号`{}`   \n\n#### 2.1.0 权限说明   \n\n#### 2.1.1 调试模式   \n\u003e 开启调试模式，可以输出 SugoSDK 的日志   \n\n```xml\n    \u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.EnableDebugLogging\"\n        android:value=\"true\"/\u003e\n```\n\n#### 2.1.2 Token 配置  \n\u003e 必填   \n\n```xml\n    \u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.token\"\n        android:value=\"{YOUR_TOKEN}\" /\u003e\n```\n\n#### 2.1.3 Project Id 配置   \n\u003e 必填   \n\n```xml\n    \u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.ProjectId\"\n        android:value=\"{YOUR_PROJECT_ID}\" /\u003e\n```\n\n#### 2.1.4 埋点配置地址   \n\u003e 必填   \n\n```xml\n    \u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.APIHost\"\n        android:value=\"{API_URL}\" /\u003e\n```\n\n#### 2.1.5 可视化埋点地址   \n\u003e 必填   \n\n```xml\n\u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.EditorHost\"\n        android:value=\"{EDITOR_URL}\" /\u003e\n```\n\n#### 2.1.6 数据上报地址   \n\u003e 必填   \n\n```xml\n    \u003cmeta-data\n        android:name=\"io.sugo.android.SGConfig.EventsHost\"\n        android:value=\"{EVENTS_URL}\" /\u003e\n```\n\n#### 2.1.7 扫码跳转页面   \n\u003e 必填   \n\n在启动的 Activity 上，也就是配置有\n```xml\n    \u003cintent-filter\u003e\n        \u003caction android:name=\"android.intent.action.MAIN\" /\u003e\n\n        \u003ccategory android:name=\"android.intent.category.LAUNCHER\" /\u003e\n    \u003c/intent-filter\u003e\n```\n的 Activity 下，添加以下配置\n\n```\n    \u003cintent-filter\u003e\n        \u003cdata android:scheme=\"sugo.{YOUR_TOKEN}\"/\u003e\n        \u003caction android:name=\"android.intent.action.VIEW\"/\u003e\n\n        \u003ccategory android:name=\"android.intent.category.DEFAULT\"/\u003e\n        \u003ccategory android:name=\"android.intent.category.BROWSABLE\"/\u003e\n    \u003c/intent-filter\u003e\n```\n\n#### 2.1.8 代码混淆   \n\u003e 如果您的应用使用了代码混淆， 请添加   \n\n\n```\n\n#保护注解\n-keepattributes *Annotation*\n#不混淆资源类\n-keepclassmembers class **.R$* {\n    public static \u003cfields\u003e;\n}\n-keepclassmembers enum * {\n    public static **[] values();\n    public static ** valueOf(java.lang.String);\n}\n-keepattributes *JavascriptInterface*\n\n-keep class android.view.* { *; }\n-keep class io.sugo.* { *; }\n-keep class io.sugo.android.metrics.SugoAPI { *; }\n-keep class io.sugo.android.metrics.SugoWebEventListener { *; }\n-keep class io.sugo.android.metrics.SugoWebNodeReporter { *; }\n\n```\n\n\n---\n\n## 3. SDK 使用   \n\n### 添加依赖   \n\n```groovy\n    compile 'com.android.support:support-annotations:{support_version}'\n    compile 'com.android.support:support-compat:{support_version}'\n    compile 'com.android.support:support-v4:{support_version}'\n```\n\n### 初始化   \n\n```Java\n    public class App extends Application {\n    \n        @Override\n        public void onCreate() {\n            super.onCreate();\n            SugoAPI.startSugo(this, SGConfig.getInstance(this));\n        }\n    \n    }\n```   \n\n标准的使用实例，应该是在 APP 启动的第一个`Activity`中，添加以下代码  \n\n```Java\npublic class MainActivity extends Activity {\n\n    SugoAPI mSugo;\n\n    public void onCreate(Bundle saved) {\n        // 获取 SugoAPI 实例，在第一次调用时，\n        mSugo = SugoAPI.getInstance(this);\n    }\n\n    // 使用 SugoAPI.track 方法来记录事件\n    public void whenSomethingInterestingHappens(int flavor) {\n        JSONObject properties = new JSONObject();\n        properties.put(\"flavor\", flavor);\n        mSugo.track(\"Something Interesting Happened\", properties);\n    }\n\n    public void onDestroy() {\n        // 如果启动的 Activity 不是最后销毁的 Activity，\n        // 这行代码可以移到对应的最后销毁的 Activity 的 onDestroy 方法里\n        mSugo.flush();      // 非必须，仅推荐使用\n        super.onDestroy();\n    }\n}\n```\n\n### 3.1 基本功能\n#### 3.1.1 自定义事件\n调用 `SugoAPI.track()`实现在代码中埋点来统计一次用户行为\n**参数说明**\n- eventId : 事件 id\n- eventName : 事件名称\n- properties : 事件的属性   \n\n```Java   \nSugoAPI sugoAPI = SugoAPI.getInstance(context);\n\nJSONObject props = new JSONObject();\nprops.put(\"Gender\", \"Female\");\nprops.put(\"Plan\", \"Premium\");\n\nsugoAPI.track(\"Plan Selected\", props);\n```\n\n#### 3.1.2 时长事件\n调用`SugoAPI.timeEvent()`来追踪一个事件发生的时长，例如统计一次图片上传所消耗的时间\n```Java   \n\nSugoAPI sugoAPI = SugoAPI.getInstance(context);\n\n// start the timer for the event \"Image Upload\"\nsugoAPI.timeEvent(\"Image Upload\");\n\n// stop the timer if the imageUpload() method returns true\nif(imageUpload()){\n    sugoAPI.track(\"Image Upload\");\n}\n```\n#### 3.1.3 首次登录  \n调用 `SugoAPI.login(userIdKey, userIdValue)` 来记录一次用户登录行为（后台需要配置用户表）   \n其中，`userIdKey` 是上报 userIdValue 的维度名，`userIdValue` 一般是用户标识，例如  `SugoAPI.login(\"userId\", 123456)` 。   \n调用 `login`之后，如果是第一次登录，则触发【首次登录】事件，并且将来所有上报的事件都会带上【首次登录时间】【userIdKey】这个维度。   \n调用 `SugoAPI.logout()` 退出登录，这两个维度将不会继续上报。   \n\n\n\n#### 3.1.3 开启 H5 埋点\n##### 3.1.3.1. WebView 支持\n```Java\n    webView.getSettings().setJavaScriptEnabled(true);\n    SugoAPI instance = SugoAPI.getInstance(this);\n    instance.addWebViewJavascriptInterface(webView);\n    webView.setWebViewClient(new SugoWebViewClient() {\n    });\n    webView.loadUrl(\"http://sugo.io\");\n```\n\n\u003e 如果开发者不能实现或继承`SugoWebViewClient`，想要设置自己的`WebViewClient`，\n\u003e 则需要在自己的`WebViewClient`的`onPageFinished()`回调里，\n\u003e 调用`SugoWebViewClient.handlePageFinished(webView, url)`即可\n```Java\nwebView.setWebViewClient(new WebViewClient() {\n        @Override\n        public void onPageFinished(WebView view, String url) {\n            super.onPageFinished(view, url);\n            SugoWebViewClient.handlePageFinished(webView, url);\n        }\n    });\n```\n\n##### 3.1.3.2 XWalkView 支持\n\u003e 如果您想要在项目中支持 XWalkView 的可视化埋点 ，可以使用以下代码\n\u003e (先要引用 sugo android sdk 的 xwalk 扩展库)\n\n- 1   初始化 SugoAPI 是，使能 XWalkView\n```Java\n    // 首先，在第一次初始化 SugoAPI 的时候，使能 XWalkView 功能\n    mSugoAPI = SugoAPI.getInstance(this);\n    SugoXWalkViewSupport.enableXWalkView(mSugoAPI, true);\n```\n- 2   然后，在 XWalkView 使用的 Activity (继承了 XWalkActivity ) 中, 调用`SugoXWalkViewSupport.handleXWalkView`\n- 3   接着，调用`XWalkView.setResourceClient` 重写 `onLoadFinished`方法，调用`SugoXWalkViewClient.handlePageFinished` 即可完成\n```Java\n    @Override\n    protected void onXWalkReady() {\n        mXWalkView = (XWalkView) findViewById(R.id.xwalkview);\n        SugoXWalkViewSupport.handleXWalkView(SugoAPI.getInstance(this), mXWalkView);\n        mXWalkView.setResourceClient(new XWalkResourceClient(mXWalkView) {\n                    @Override\n                    public void onLoadFinished(XWalkView view, String url) {\n                        super.onLoadFinished(view, url);\n                        SugoXWalkViewClient.handlePageFinished(view, url);\n                    }\n                });\n        mXWalkView.load(\"http://sugo.io\", null);\n    }\n```\n- 4  最后，在`onCreate` 中调用`XWalkPreferences.setValue(XWalkPreferences.ANIMATABLE_XWALK_VIEW, true);`\n才能使得 XWalkView 的网页内容被上传至可视化埋点\n\n\n##### 3.1.3.3 H5 代码埋点\n\n在进行了 `3.1.3.1` 或 `3.1.3.2` 的操作之后，SugoSDK 可支持 H5 的可视化埋点。\n如果需要代码埋点，可在 js 中调用以下方法：\n\n自定义事件，参数如下：\n**参数说明**\n- event_id : 事件 id\n- event_name : 事件名称\n- props : 事件的属性\n```JavaScript\nsugo.track(event_id, event_name, props);\n```\n\n时长事件（可参照 3.1.2）\n```JavaScript\nsugo.timeEvent(event_name);\n```\n\n#### 3.1.4 默认属性\n有一种很常见的情况，你想让一些常见的属性在每一个事件中都添加上，因此，你可以将这些属性注册为`默认属性`。\n\n`默认属性`是保存在设备上的，将会持续存在 APP 里。\nSugoSDK 也设置了一些默认的`默认属性`，[点这里查看]()\n\n想要设置`默认属性`，调用`SugoAPI.registerSuperProperties`\n```Java\nSugoAPI sugoAPI = SugoAPI.getInstance(context);\n\n// Send a \"User Type: Paid\" property will be sent with all future track calls.\nJSONObject props = new JSONObject();\nprops.put(\"User Type\", \"Paid\");\nsugoAPI.registerSuperProperties(props);\n```\n接下来，你记录的任何事件，这些`默认属性`都会被一起发送。\n`默认属性`是存储在设备上的，退出 APP 后下次启动，该`默认属性`依旧存在。\n\n**只设置一次`默认属性`**\n通过`SugoAPI.registerSuperProperties`会强行覆盖已有的同名属性，如果有些属性你想只设置一次（例如第一次登录的时间），可以调用`SugoAPI.registerSuperPropertiesOnce`，这个方法只保存第一次设置时的值，后面对该属性的修改操作将无效。\n\n**移除`默认属性`**\n通过`SugoAPI.unregisterSuperProperty`可移除已设置的`默认属性`\n\n\n\n---\n\n### 3.2 热图\n\n\n2 在启动的 Activity 上，配置\n\u003e 如果已经配置了可视化埋点，这里也是一样的，可以跳过   \n\n```\n    \u003cintent-filter\u003e\n        \u003cdata android:scheme=\"sugo.c6749a4f1ef039ca196148ed1cb65d87\"/\u003e\n\n        \u003caction android:name=\"android.intent.action.VIEW\"/\u003e\n\n        \u003ccategory android:name=\"android.intent.category.DEFAULT\"/\u003e\n        \u003ccategory android:name=\"android.intent.category.BROWSABLE\"/\u003e\n    \u003c/intent-filter\u003e\n```\n\n在控制台网页点击【埋点热图】，使用浏览器扫描二维码，跳转到该App，即可进入热图模式。\n\n\u003e 1 进入热图模式后，热图模式将一直存在，只有 kill 掉 App 进程才会退出\n\u003e 2 在热图模式中，无法进入可视化埋点，反之，在可视化埋点模式时，无法进入热图\n\n\n## 4 Q\u0026A\n\nQ. 定位 View 失败   \nA. SDK 通过资源 id 定位 View，如果 applicationId 与应用包名不一致，则需要修改   \n```xml\n        \u003cmeta-data\n            android:name=\"io.sugo.android.SGConfig.ResourcePackageName\"\n            android:value=\"{YOUR_PACKAGE_NAME}\" /\u003e\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatafruit%2Fsugo-android-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatafruit%2Fsugo-android-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatafruit%2Fsugo-android-sdk/lists"}