admin/zhini_im
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
zhini_im/(红头)友盟文档.txt

513 lines
18 KiB
Plaintext
Raw Permalink Normal View History

first commit Change-Id: Ib7c2ab10a2562044fcaf9879388a6cbc1db6ac61
2025-12-23 09:56:21 +08:00
================================================================================
友盟统计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. ✅ 在友盟后台查看"实时统计"是否有数据
================================================================================
文档结束
================================================================================
Reference in New Issue Copy Permalink