android-frame/frame/googleservice/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

模块概览

frame/googleservice 是 Google 服务集成模块，主要提供两个核心功能：

1. Google 广告 ID (GAID) 获取 - 用于广告归因和用户行为分析
2. Google Play 安装引荐 (Install Referrer) 获取 - 用于跟踪应用安装来源和营销归因

核心架构

接口设计

• IGoogleService: 主服务接口，提供 GAID 和 Install Referrer 获取功能
• IGoogleServiceConfig: 配置接口，定义回调和用户 ID 获取
• IGoogleListener: 异步操作监听器

数据模型

• GPReferrer: Google Play 引荐数据模型，包含 UTM 参数和 GCLID
• GPSInfo: GPS 服务信息，包含 GAID 和跟踪启用状态

实现特点

• 多种 GAID 获取方式：Google Play Services SDK 和直接 GPS 服务绑定
• 异步和同步两种接口模式，支持协程
• 本地缓存机制（通过 GooglePref）
• 重试机制和错误处理

核心功能流程

GAID 获取流程

1. 检查内存缓存
2. 检查 SharedPreferences 缓存
   
3. 尝试通过 GPS 服务直接获取
4. 降级到 Google Play Services SDK
5. 缓存有效结果并通知监听器

Install Referrer 获取流程

1. 检查内存缓存
2. 检查 SharedPreferences 缓存中的引荐 URL
3. 通过 InstallReferrerClient 从 Google Play 获取
4. 解析 UTM 参数（utm_source, utm_campaign, utm_content）
5. 缓存结果并回调配置的完成监听器

依赖关系

模块依赖项目基础框架：

• frame:base - RLT 状态管理和错误处理
• frame:coroutine - 协程调度器
• frame:util - 应用工具类
• frame:log - 日志系统

外部依赖：

• Google Play Services Base
• Android Install Referrer Library

使用模式

// 创建服务实例
val googleService = createGoogleService(object : IGoogleServiceConfig {
    override fun onGPReferrerFinished() {
        // 引荐数据获取完成回调
    }
    
    override fun getUid(): Long = currentUserId
})

// 初始化（启动异步获取）
googleService.init()

// 同步获取 GAID
val gaid = googleService.getGAId()

// 异步获取 GAID
googleService.getGAid(object : IGoogleListener {
    override fun onGetGAidSuccess(gAid: String) {
        // 处理成功
    }
    
    override fun onGetGAidFailed(error: IError) {
        // 处理失败
    }
})

// 协程方式获取
val gaid = googleService.getGAid()
val referrer = googleService.getGPReferrer()

关键常量和错误类型

• INVALID_GAID: "00000000-0000-0000-0000-0000000000" - 无效的广告 ID
• CHANNEL_DEFAULT: "gp" - 默认渠道标识
• GP_REFERRER_SOURCE_MAX_RETRY_COUNT: 2 - 引荐获取最大重试次数

错误类型：

• GooglePlayServicesUnAvailableError: Google Play 服务不可用
• GPReferrerRetryCountLimitedError: 引荐获取重试次数超限
• GPReferrerUnknownError: 未知的引荐获取错误

测试和构建

运行测试：

./gradlew :frame:googleservice:test

构建模块：

./gradlew :frame:googleservice:build

注意事项

1. 权限要求: 需要访问 Google Play Services 和安装引荐服务
2. 时机要求: 应在应用启动早期初始化，确保数据及时获取
3. 隐私合规: GAID 获取需要遵循用户隐私设置和相关法规
4. 缓存策略: 数据会被缓存到 SharedPreferences，避免重复网络请求
5. 错误处理: 网络异常、服务不可用等情况都有对应的错误类型和重试机制