Monet AppTracker 使用人数 API - 分类版 APK 手动接入说明

目录内容
1. classes.dex
   适合目标 APK 原本没有 classes.dex 的极少数情况。

2. classes2.dex
   推荐使用。大多数 APK 已经有 classes.dex，把本文件放到 APK 根目录即可。

3. AndroidManifest-merge-snippet.xml
   需要手动合并到目标 APK 的 AndroidManifest.xml。

4. README_使用人数API接入说明.txt / README_usage_api_zh.txt
   当前说明书。两个文件内容一致，英文文件名版本用于避免部分压缩工具中文文件名乱码。


一、新版分类统计规则
使用人数 API 现在支持按不同接入应用分类统计。

推荐规则：
- 每一个接入软件，都在网站“使用人数API”页面单独填写“接入应用名称”并生成一个新的 mau_ token。
- “接入应用名称”会显示在统计页中，用来区分不同 app。
- dex 会自动上报当前 APK 的包名，服务器会把它记录为 appId/packageName，方便排查接入来源。
- 如果你手写接口请求，也可以在 JSON 请求体里传 appId 或 packageName。
- 使用人数 API token 是 mau_ 开头，不能和图标包数据库 token（mat_ 开头）混用。

示例：
1. 应用 A 填写“重圆 图标包”，生成 mau_token_A，放入应用 A。
2. 应用 B 填写“Monet 图标包”，生成 mau_token_B，放入应用 B。
3. 统计页会分别显示“重圆 图标包”和“Monet 图标包”的使用人数。


二、功能说明
这个 dex 会通过 ContentProvider 在应用启动时自动运行一次。
它会读取 AndroidManifest.xml 里的使用人数 API token，然后请求：

https://monet-apptracker.pages.dev/api/usage/ping

请求体包含：
- 随机生成的安装 ID（deviceId）
- 当前 APK 包名（packageName/appId）
- Android SDK 版本

不会读取手机号、IMEI、通讯录、相册等隐私信息。
同一安装每天最多本地上报一次，避免频繁请求服务器。
服务器也会按 token + deviceId 去重统计，同一个接入应用里同一设备不会重复计入使用人数。


三、推荐接入方式：通过 AndroidManifest.xml 填 token
1. 在网站“使用人数API”页面填写当前接入应用名称，然后点击“生成使用人数 token”。
   注意：每个不同 app 建议生成不同的 token。

2. 把 classes2.dex 放进 APK 根目录。
   如果 APK 没有 classes.dex，可以改用 classes.dex。
   如果 APK 已经有 classes2.dex，则把本文件改名为 classes3.dex、classes4.dex 等未占用编号。

3. 在 AndroidManifest.xml 的 <manifest> 节点下加入：

<uses-permission android:name="android.permission.INTERNET" />

4. 在 AndroidManifest.xml 的 <application> 节点里面加入：

<meta-data
    android:name="monet_usage_base_url"
    android:value="https://monet-apptracker.pages.dev" />

<meta-data
    android:name="monet_usage_token"
    android:value="mau_这里填写你自己的使用人数API令牌" />

<provider
    android:name="com.monet.apptracker.usage.MonetUsageProvider"
    android:authorities="目标APK包名.monet-usage-provider"
    android:exported="false"
    android:initOrder="100" />

注意：
- android:authorities 必须唯一。
- “目标APK包名”要替换成 APK 的真实包名，比如：
  com.example.app.monet-usage-provider
- 使用人数 API 令牌必须是 mau_ 开头。
- 图标包提交令牌 mat_ 不能用于这里。


四、手动接口请求格式
如果你不用 dex，也可以在软件首次联网时自己请求接口：

POST https://monet-apptracker.pages.dev/api/usage/ping
Authorization: Bearer mau_这里填写使用人数token
Content-Type: application/json

{
  "deviceId": "设备唯一ID",
  "appId": "软件包名，例如 com.example.app"
}

字段说明：
- deviceId 必填。建议使用应用自己生成并保存的随机安装 ID，不建议使用隐私设备号。
- appId 可填软件包名。服务器也兼容 packageName/package 字段。
- 分类展示主要看 token 对应的“接入应用名称”，appId 用于记录具体接入来源。


五、手动修改 classes.dex 里的统计人数令牌
如果你不想在 AndroidManifest.xml 里写 monet_usage_token，也可以直接改 dex 内置的占位令牌。
但是仍然必须在 AndroidManifest.xml 里加入 INTERNET 权限和 provider。

方法 A：用 MT 管理器 / NP 管理器 / Apktool 修改 smali
1. 反编译 APK。

2. 把本包里的 classes2.dex 放进反编译后的 APK 根目录。
   如果需要改名为 classes3.dex，也可以。

3. 如果工具能直接浏览 dex/smali，找到：

com/monet/apptracker/usage/MonetUsageProvider.smali

4. 搜索这个字符串：

mau_REPLACE_WITH_YOUR_USAGE_TOKEN

5. 替换成你自己的使用人数 API 令牌，例如：

mau_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

6. 保存后重新打包、签名、安装测试。


方法 B：先把 dex 转 smali，再替换
如果你用 apktool/baksmali 工作流，可以这样做：

1. 将 classes2.dex 转成 smali：

baksmali d classes2.dex -o smali_classes2

2. 搜索：

mau_REPLACE_WITH_YOUR_USAGE_TOKEN

3. 替换为自己的 mau_ 开头令牌。

4. 重新打包时让 apktool 把 smali_classes2 编回 dex。


六、Manifest 最小示例
假设目标 APK 包名为 com.example.app：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />

    <application>
        <meta-data
            android:name="monet_usage_base_url"
            android:value="https://monet-apptracker.pages.dev" />

        <meta-data
            android:name="monet_usage_token"
            android:value="mau_这里填写你自己的使用人数API令牌" />

        <provider
            android:name="com.monet.apptracker.usage.MonetUsageProvider"
            android:authorities="com.example.app.monet-usage-provider"
            android:exported="false"
            android:initOrder="100" />
    </application>
</manifest>


七、常见问题
1. 多个软件可以共用一个 mau_ token 吗？
   不建议。共用 token 会让统计页把它们合并到同一个接入应用名称下。
   新版分类统计建议每个软件单独生成 token。

2. 安装时报 INSTALL_FAILED_CONFLICTING_PROVIDER
   原因：android:authorities 和别的应用重复。
   解决：改成“目标APK包名.monet-usage-provider”这种唯一值。

3. 后台统计没有增加
   检查：
   - 手机是否联网
   - APK 是否有 android.permission.INTERNET
   - provider 是否放在 <application> 里面
   - token 是否是 mau_ 开头
   - base_url 是否是 https://monet-apptracker.pages.dev
   - 同一安装本地 24 小时只会上报一次

4. 可以用 mat_ 图标包令牌吗？
   不可以。mat_ 是图标包数据库提交令牌。
   使用人数 API 必须使用 mau_ 开头令牌。

5. 会不会导致服务器被刷？
   dex 本地做了 24 小时节流；服务器接口也有限速。