================================================================================ 友盟统计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 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 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中配置）: 5.2 埋点验证配置（可选） ----------------------- 在 标签内添加: 注意: 生产环境应设置为 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. ✅ 在友盟后台查看"实时统计"是否有数据 ================================================================================ 文档结束 ================================================================================