513 lines
18 KiB
Plaintext
513 lines
18 KiB
Plaintext
================================================================================
|
||
友盟统计SDK集成配置文档
|
||
================================================================================
|
||
文档版本: 1.0
|
||
创建日期: 2024
|
||
用途: 用于排查友盟统计SDK集成问题，适用于项目分支切换时的配置检查
|
||
|
||
================================================================================
|
||
一、基本信息
|
||
================================================================================
|
||
|
||
1.1 SDK版本
|
||
-----------
|
||
- 友盟统计SDK版本: 9.8.8
|
||
- 必选依赖库版本:
|
||
* com.umeng.umsdk:common:9.8.8
|
||
* com.umeng.umsdk:asms:1.8.7
|
||
- 可选依赖库版本:
|
||
* com.umeng.umsdk:uyumao:1.1.4 (高级运营分析功能)
|
||
* com.umeng.umsdk:abtest:1.0.1 (ABTest能力)
|
||
|
||
1.2 AppKey配置
|
||
--------------
|
||
- AppKey: 69009244644c9e2c2067d39b
|
||
- 渠道标识: default (或 "Channel")
|
||
- 配置位置: app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
* 常量定义: UMENG_APP_KEY = "69009244644c9e2c2067d39b"
|
||
* 常量定义: UMENG_CHANNEL = "default"
|
||
|
||
================================================================================
|
||
二、依赖配置 (app/build.gradle)
|
||
================================================================================
|
||
|
||
2.1 必需依赖
|
||
-----------
|
||
在 app/build.gradle 的 dependencies 块中添加：
|
||
|
||
// 友盟统计SDK - 使用具体版本确保兼容性
|
||
implementation 'com.umeng.umsdk:common:9.8.8' // 必选，版本9.4.0以上
|
||
implementation 'com.umeng.umsdk:asms:1.8.7' // 必选
|
||
implementation 'com.umeng.umsdk:uyumao:1.1.4' // 高级运营分析功能依赖库（可选）
|
||
implementation 'com.umeng.umsdk:abtest:1.0.1' // U-App中ABTest能力（可选）
|
||
|
||
2.2 注意事项
|
||
-----------
|
||
- 确保依赖版本与SDK版本匹配
|
||
- 如果使用Gradle 7.0+，可能需要添加仓库配置
|
||
- 检查是否有依赖冲突（特别是与高德地图、腾讯地图SDK的冲突）
|
||
|
||
================================================================================
|
||
三、初始化流程
|
||
================================================================================
|
||
|
||
3.1 Application中的初始化 (MyApp.java) - 当前工作版本
|
||
---------------------------------------------------
|
||
位置: app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
方法: onCreate()
|
||
行号: 第109-117行
|
||
|
||
关键代码:
|
||
// 预初始化（不会采集设备信息，不会上报数据）
|
||
UMConfigure.preInit(this, "69009244644c9e2c2067d39b", "Channel");
|
||
|
||
// 正式初始化（会采集设备信息并上报数据）
|
||
UMConfigure.init(this, "69009244644c9e2c2067d39b", "Channel",
|
||
UMConfigure.DEVICE_TYPE_PHONE, "PushSecret");
|
||
|
||
// 开启Log（仅调试模式，正式发布请关闭）
|
||
UMConfigure.setLogEnabled(true);
|
||
|
||
重要说明（当前工作版本）:
|
||
- ✅ 预初始化和正式初始化都在 Application.onCreate() 中直接调用
|
||
- ✅ 这是老版本的实现方式，简单直接
|
||
- ✅ 初始化时机：应用启动时立即初始化，不等待用户同意隐私政策
|
||
- ⚠️ 注意：这种方式不符合隐私合规要求，但当前版本可以正常工作
|
||
- ⚠️ 如果切换到新版本，需要改为在用户同意隐私政策后初始化
|
||
|
||
3.2 正式初始化方法 (MyApp.java)
|
||
-------------------------------
|
||
位置: app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
方法: initUmengSDKFormally()
|
||
|
||
关键代码:
|
||
public static void initUmengSDKFormally() {
|
||
if (isUmengInitialized) {
|
||
Log.d("MyApp", "友盟统计SDK已经初始化，跳过重复初始化");
|
||
return;
|
||
}
|
||
|
||
try {
|
||
// 正式初始化（会采集设备信息并上报数据）
|
||
UMConfigure.init(getApplication(), UMENG_APP_KEY, UMENG_CHANNEL,
|
||
UMConfigure.DEVICE_TYPE_PHONE, null);
|
||
|
||
// 设置日志开关
|
||
UMConfigure.setLogEnabled(true);
|
||
|
||
// 设置页面采集模式（重要：影响启动和活跃数据）
|
||
MobclickAgent.setPageCollectionMode(MobclickAgent.PageMode.AUTO);
|
||
|
||
// 统计SDK是否支持采集在子进程中打点的自定义事件
|
||
UMConfigure.setProcessEvent(true); // 支持多进程打点
|
||
|
||
// 获取OAID（Android Q设备标识）
|
||
UMConfigure.getOaid(getApplication(), new OnGetOaidListener() {
|
||
@Override
|
||
public void onGetOaid(String oaid) {
|
||
Log.d("MyApp", "获取到OAID: " + oaid);
|
||
}
|
||
});
|
||
|
||
isUmengInitialized = true;
|
||
|
||
// 立即发送一个测试事件
|
||
sendTestEvent();
|
||
|
||
} catch (Exception e) {
|
||
Log.e("MyApp", "❌ 友盟统计SDK正式初始化失败", e);
|
||
}
|
||
}
|
||
|
||
3.3 初始化状态检查
|
||
-----------------
|
||
位置: app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
方法: isUmengSDKInitialized()
|
||
|
||
public static boolean isUmengSDKInitialized() {
|
||
return isUmengInitialized;
|
||
}
|
||
|
||
3.4 初始化调用位置（当前工作版本）
|
||
---------------------------------
|
||
1. Application.onCreate() - 主要初始化位置 ✅
|
||
- 第109行: UMConfigure.preInit()
|
||
- 第113行: UMConfigure.init()
|
||
- 第117行: UMConfigure.setLogEnabled(true)
|
||
- 这是当前工作版本的主要初始化方式
|
||
|
||
2. MainActivity.afterViews() - 备用初始化（如果未初始化）
|
||
- 代码位置: MainActivity.java 第332-341行
|
||
- 代码:
|
||
if (!MyApp.isUmengSDKInitialized()) {
|
||
MyApp.initUmengSDKFormally();
|
||
}
|
||
MyApp.setUserPrivacyAgreement(true);
|
||
MyApp.checkUmengDataReportStatus(this);
|
||
- 作用: 如果Application中初始化失败，在这里进行备用初始化
|
||
- 注意: 当前工作版本中，Application.onCreate()已经初始化，这里通常不会执行
|
||
|
||
3. 测试和调试调用
|
||
- MainActivity.afterViews() 第343行: testUmengAnalytics()
|
||
- MainActivity.afterViews() 第347行: UmengDebugHelper.checkUmengEnvironment(this)
|
||
|
||
================================================================================
|
||
四、工具类配置 (UmengAnalytics.java)
|
||
================================================================================
|
||
|
||
4.1 工具类位置
|
||
-------------
|
||
app/src/main/java/com/xunpaisoft/social/utils/UmengAnalytics.java
|
||
|
||
4.2 主要方法
|
||
-----------
|
||
1. 页面统计:
|
||
- onPageStart(Context context, String pageName)
|
||
- onPageEnd(Context context, String pageName)
|
||
|
||
2. 事件统计:
|
||
- onEvent(Context context, String eventId)
|
||
- onEvent(Context context, String eventId, String eventLabel)
|
||
- onEvent(Context context, String eventId, Map<String, String> eventMap)
|
||
|
||
3. 用户相关:
|
||
- setUserId(Context context, String userId)
|
||
- onProfileSignOff(Context context)
|
||
|
||
4. 其他配置:
|
||
- setSessionContinueMillis(Context context, long timeout)
|
||
- setLogEnabled(boolean enabled)
|
||
- getSDKVersion()
|
||
|
||
4.3 使用示例
|
||
-----------
|
||
// 页面统计
|
||
UmengAnalytics.onPageStart(this, "MainActivity");
|
||
UmengAnalytics.onPageEnd(this, "MainActivity");
|
||
|
||
// 事件统计
|
||
UmengAnalytics.onEvent(this, "button_click", "login");
|
||
|
||
// 自定义事件
|
||
Map<String, String> eventMap = new HashMap<>();
|
||
eventMap.put("user_type", "vip");
|
||
eventMap.put("action", "purchase");
|
||
UmengAnalytics.onEvent(this, "user_action", eventMap);
|
||
|
||
// 设置用户ID
|
||
UmengAnalytics.setUserId(this, userId);
|
||
|
||
================================================================================
|
||
五、AndroidManifest.xml配置
|
||
================================================================================
|
||
|
||
5.1 权限配置
|
||
-----------
|
||
友盟统计SDK需要以下权限（通常已在AndroidManifest.xml中配置）:
|
||
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
|
||
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
|
||
<uses-permission android:name="android.permission.INTERNET"/>
|
||
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
|
||
|
||
5.2 埋点验证配置（可选）
|
||
-----------------------
|
||
在 <application> 标签内添加:
|
||
<!-- 友盟统计埋点验证配置 -->
|
||
<meta-data
|
||
android:name="UMENG_ANALYTICS_DEBUG_MODE"
|
||
android:value="false" />
|
||
|
||
注意: 生产环境应设置为 false
|
||
|
||
================================================================================
|
||
六、关键配置检查清单
|
||
================================================================================
|
||
|
||
6.1 依赖检查
|
||
-----------
|
||
□ app/build.gradle 中是否添加了友盟统计SDK依赖？
|
||
□ 依赖版本是否为 9.8.8？
|
||
□ 是否添加了 asms:1.8.7 依赖？
|
||
|
||
6.2 初始化检查
|
||
-----------
|
||
□ Application.onCreate() 中是否调用了 UMConfigure.preInit()？
|
||
□ Application.onCreate() 中是否调用了 UMConfigure.init()？（老版本）
|
||
□ 或者是否在用户同意隐私政策后调用了 initUmengSDKFormally()？（新版本）
|
||
□ 是否设置了 UMConfigure.setLogEnabled(true)？（调试模式）
|
||
□ 是否设置了 MobclickAgent.setPageCollectionMode(MobclickAgent.PageMode.AUTO)？
|
||
|
||
6.3 AppKey检查
|
||
-----------
|
||
□ MyApp.java 中的 UMENG_APP_KEY 是否正确？
|
||
□ MyApp.java 中的 UMENG_CHANNEL 是否正确？
|
||
□ 是否与友盟后台配置的AppKey一致？
|
||
|
||
6.4 工具类检查
|
||
-----------
|
||
□ UmengAnalytics.java 是否存在？
|
||
□ 是否在页面生命周期中调用了 onPageStart() 和 onPageEnd()？
|
||
□ 是否在关键事件中调用了 onEvent()？
|
||
|
||
6.5 网络权限检查
|
||
-----------
|
||
□ AndroidManifest.xml 中是否配置了 INTERNET 权限？
|
||
□ AndroidManifest.xml 中是否配置了 ACCESS_NETWORK_STATE 权限？
|
||
|
||
================================================================================
|
||
七、常见问题排查
|
||
================================================================================
|
||
|
||
7.1 SDK未初始化
|
||
--------------
|
||
症状: 日志显示 "友盟统计SDK未初始化，跳过页面统计"
|
||
排查:
|
||
1. 检查 Application.onCreate() 中是否调用了初始化方法
|
||
2. 检查 isUmengSDKInitialized() 返回值
|
||
3. 查看 Logcat 中是否有初始化相关的日志
|
||
4. 确认是否在用户同意隐私政策后调用初始化（新版本）
|
||
|
||
7.2 数据未上报
|
||
--------------
|
||
症状: 友盟后台看不到数据
|
||
排查:
|
||
1. 检查网络连接是否正常
|
||
2. 检查 AppKey 是否正确
|
||
3. 检查是否开启了日志: UMConfigure.setLogEnabled(true)
|
||
4. 查看 Logcat 中是否有上报相关的日志
|
||
5. 确认是否设置了页面采集模式: MobclickAgent.setPageCollectionMode()
|
||
6. 等待几分钟，数据上报有延迟
|
||
|
||
7.3 依赖冲突
|
||
-----------
|
||
症状: 编译错误或运行时崩溃
|
||
排查:
|
||
1. 检查是否有重复的依赖
|
||
2. 检查是否与其他SDK（如高德地图、腾讯地图）冲突
|
||
3. 查看 build.gradle 中的依赖树: ./gradlew :app:dependencies
|
||
4. 检查 packagingOptions 配置
|
||
|
||
7.4 页面统计不准确
|
||
-----------------
|
||
症状: 页面停留时间或访问次数不准确
|
||
排查:
|
||
1. 检查是否在 onResume() 中调用了 onPageStart()
|
||
2. 检查是否在 onPause() 中调用了 onPageEnd()
|
||
3. 检查页面名称是否唯一且有意义
|
||
4. 确认页面采集模式设置正确
|
||
|
||
================================================================================
|
||
八、日志关键字
|
||
================================================================================
|
||
|
||
8.1 初始化相关日志
|
||
-----------------
|
||
搜索关键字: "MyApp", "友盟", "UMConfigure", "MobclickAgent"
|
||
正常日志示例:
|
||
D/MyApp: 开始正式初始化友盟统计SDK
|
||
D/MyApp: AppKey: 69009244644c9e2c2067d39b
|
||
D/MyApp: Channel: default
|
||
D/MyApp: ✅ 友盟统计SDK正式初始化完成
|
||
D/MyApp: ✅ 开始采集和上报数据
|
||
|
||
8.2 页面统计日志
|
||
---------------
|
||
搜索关键字: "UmengAnalytics", "页面开始统计", "页面结束统计"
|
||
正常日志示例:
|
||
D/UmengAnalytics: 页面开始统计: MainActivity
|
||
D/UmengAnalytics: 页面结束统计: MainActivity
|
||
|
||
8.3 事件统计日志
|
||
---------------
|
||
搜索关键字: "事件统计", "onEvent"
|
||
正常日志示例:
|
||
D/UmengAnalytics: 事件统计: button_click, 标签: login
|
||
|
||
8.4 错误日志
|
||
-----------
|
||
搜索关键字: "❌", "失败", "错误"
|
||
常见错误:
|
||
E/MyApp: ❌ 友盟统计SDK正式初始化失败
|
||
W/UmengAnalytics: 友盟统计SDK未初始化，跳过页面统计
|
||
|
||
================================================================================
|
||
九、调试工具
|
||
================================================================================
|
||
|
||
9.1 UmengDebugHelper
|
||
-------------------
|
||
位置: app/src/main/java/com/xunpaisoft/social/utils/UmengDebugHelper.java
|
||
功能: 检查友盟统计环境
|
||
调用: UmengDebugHelper.checkUmengEnvironment(context);
|
||
|
||
9.2 MyApp.checkUmengDataReportStatus()
|
||
------------------------------------
|
||
位置: app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
功能: 检查友盟数据上报状态
|
||
调用: MyApp.checkUmengDataReportStatus(context);
|
||
|
||
9.3 测试方法
|
||
-----------
|
||
在 MainActivity.afterViews() 中:
|
||
// 测试友盟统计功能
|
||
testUmengAnalytics();
|
||
|
||
// 友盟统计环境检查
|
||
UmengDebugHelper.checkUmengEnvironment(this);
|
||
|
||
================================================================================
|
||
十、关键文件清单
|
||
================================================================================
|
||
|
||
10.1 核心文件
|
||
------------
|
||
1. app/src/main/java/com/xunpaisoft/social/MyApp.java
|
||
- 友盟SDK初始化
|
||
- AppKey配置
|
||
- 初始化状态管理
|
||
|
||
2. app/src/main/java/com/xunpaisoft/social/utils/UmengAnalytics.java
|
||
- 友盟统计工具类
|
||
- 封装统计方法
|
||
|
||
3. app/src/main/java/com/xunpaisoft/social/utils/UmengDebugHelper.java
|
||
- 调试工具类
|
||
- 环境检查
|
||
|
||
4. app/build.gradle
|
||
- 依赖配置
|
||
|
||
5. app/src/main/AndroidManifest.xml
|
||
- 权限配置
|
||
- 埋点验证配置
|
||
|
||
10.2 使用位置
|
||
------------
|
||
1. app/src/main/java/com/xunpaisoft/social/im/main/MainActivity.java
|
||
- 页面统计
|
||
- 初始化检查
|
||
|
||
2. 其他Activity和Fragment
|
||
- 页面统计调用
|
||
- 事件统计调用
|
||
|
||
================================================================================
|
||
十一、版本差异说明
|
||
================================================================================
|
||
|
||
11.1 老版本（当前工作版本）✅ 正在使用
|
||
------------------------------------
|
||
- 在 Application.onCreate() 中直接调用预初始化和正式初始化
|
||
- 代码位置: MyApp.onCreate() 第109-117行
|
||
- 关键代码:
|
||
UMConfigure.preInit(this, "69009244644c9e2c2067d39b", "Channel");
|
||
UMConfigure.init(this, "69009244644c9e2c2067d39b", "Channel",
|
||
UMConfigure.DEVICE_TYPE_PHONE, "PushSecret");
|
||
UMConfigure.setLogEnabled(true);
|
||
- 特点:
|
||
✅ 简单直接，初始化成功率高
|
||
✅ 不需要用户交互，应用启动即初始化
|
||
⚠️ 不符合隐私合规要求（在用户同意前就初始化）
|
||
⚠️ 可能在某些应用市场审核时被拒绝
|
||
|
||
11.2 新版本（隐私合规版本）
|
||
--------------------------
|
||
- 在 Application.onCreate() 中只调用预初始化
|
||
- 在用户同意隐私政策后调用正式初始化
|
||
- 代码位置: SplashActivity 或 MainActivity
|
||
- 特点: 符合隐私合规要求，但需要用户交互
|
||
|
||
11.3 切换版本时的注意事项
|
||
------------------------
|
||
1. 检查初始化调用位置
|
||
2. 确认是否需要在用户同意隐私政策后初始化
|
||
3. 检查 isUmengSDKInitialized() 的使用
|
||
4. 确认日志输出是否正常
|
||
|
||
================================================================================
|
||
十二、快速检查命令
|
||
================================================================================
|
||
|
||
12.1 检查依赖
|
||
-----------
|
||
在项目根目录执行:
|
||
./gradlew :app:dependencies | grep umeng
|
||
|
||
12.2 检查初始化
|
||
-----------
|
||
在 Logcat 中搜索:
|
||
"MyApp" AND ("友盟" OR "UMConfigure" OR "MobclickAgent")
|
||
|
||
12.3 检查统计调用
|
||
---------------
|
||
在 Logcat 中搜索:
|
||
"UmengAnalytics" AND ("页面" OR "事件")
|
||
|
||
================================================================================
|
||
十三、联系信息
|
||
================================================================================
|
||
|
||
友盟官方文档: https://developer.umeng.com/docs/119267/detail/118585
|
||
友盟技术支持: https://developer.umeng.com/support
|
||
|
||
================================================================================
|
||
十四、当前工作版本关键配置总结
|
||
================================================================================
|
||
|
||
14.1 核心配置（必须检查）
|
||
------------------------
|
||
1. app/build.gradle 依赖配置（第123-127行）:
|
||
✅ implementation 'com.umeng.umsdk:common:9.8.8'
|
||
✅ implementation 'com.umeng.umsdk:asms:1.8.7'
|
||
✅ implementation 'com.umeng.umsdk:uyumao:1.1.4'
|
||
✅ implementation 'com.umeng.umsdk:abtest:1.0.1'
|
||
|
||
2. MyApp.java 初始化配置（第109-117行）:
|
||
✅ UMConfigure.preInit(this, "69009244644c9e2c2067d39b", "Channel");
|
||
✅ UMConfigure.init(this, "69009244644c9e2c2067d39b", "Channel",
|
||
UMConfigure.DEVICE_TYPE_PHONE, "PushSecret");
|
||
✅ UMConfigure.setLogEnabled(true);
|
||
|
||
3. MyApp.java AppKey配置（第70-72行）:
|
||
✅ UMENG_APP_KEY = "69009244644c9e2c2067d39b"
|
||
✅ UMENG_CHANNEL = "default"
|
||
|
||
4. UmengAnalytics.java 工具类:
|
||
✅ 文件位置: app/src/main/java/com/xunpaisoft/social/utils/UmengAnalytics.java
|
||
✅ 所有统计方法都通过此工具类调用
|
||
|
||
14.2 验证步骤（快速检查）
|
||
----------------------
|
||
1. 检查依赖:
|
||
- 打开 app/build.gradle
|
||
- 确认第123-127行有友盟依赖
|
||
|
||
2. 检查初始化:
|
||
- 打开 MyApp.java
|
||
- 确认第109-117行有初始化代码
|
||
- 确认第70-72行有AppKey配置
|
||
|
||
3. 检查工具类:
|
||
- 确认 UmengAnalytics.java 文件存在
|
||
- 确认 MainActivity 中调用了 UmengAnalytics.onPageStart()
|
||
|
||
4. 运行验证:
|
||
- 运行应用
|
||
- 在 Logcat 中搜索 "MyApp" 和 "友盟"
|
||
- 应该看到初始化成功的日志
|
||
|
||
14.3 如果数据未上报，按以下顺序检查
|
||
----------------------------------
|
||
1. ✅ 检查依赖是否正确添加
|
||
2. ✅ 检查 AppKey 是否正确
|
||
3. ✅ 检查初始化是否成功（查看日志）
|
||
4. ✅ 检查网络连接
|
||
5. ✅ 检查是否调用了统计方法
|
||
6. ✅ 等待几分钟，数据上报有延迟
|
||
7. ✅ 在友盟后台查看"实时统计"是否有数据
|
||
|
||
================================================================================
|
||
文档结束
|
||
================================================================================
|
||
|