Android SDK 文档

概述

App 统计是独立的产品线：启动、页面、版本、渠道、崩溃、ANR 与启动耗时都有自己的事件与口径，不套用网站的 PV 与跳出率。App 内嵌的网页可以继续使用网站统计。

下载 SDK

推荐通过 Maven 仓库引入（见下一节）。不方便访问仓库时，下载 SDK 的 AAR 放进 app/libs/——崩溃捕获依赖 xCrash，手动集成时两个 AAR 都需要。

Maven 仓库：http://a.t3j.com/maven/

演示 App 集成了 SDK，可以在手机上安装后点按钮体验自定义事件、页面切换、崩溃与 ANR 的上报。

// app/build.gradle — put fmeng-android-sdk-1.2.1.aar and xcrash-android-lib-3.1.0.aar into app/libs/
dependencies {
    implementation fileTree(dir: "libs", include: ["*.aar"])
}

Gradle 接入

在 settings.gradle 的 dependencyResolutionManagement.repositories 中加入飞盟的 Maven 仓库，mavenCentral() 用于下载 xCrash：

// settings.gradle
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral() // xCrash
        maven {
            url "http://a.t3j.com/maven/"
            allowInsecureProtocol = true
        }
    }
}

然后在 app/build.gradle 中添加依赖：

// app/build.gradle
dependencies {
    implementation "com.fmeng:fmeng-android-sdk:1.2.1"
}

混淆规则已随 AAR 发布（consumer rules），无需在 proguard-rules.pro 里添加；INTERNET 与 ACCESS_NETWORK_STATE 权限会自动合并进应用的 AndroidManifest。

初始化

与友盟一样，App Key 与渠道写在 AndroidManifest.xml 的 <application> 下：FMENG_APPKEY 为 APP_KEY（在控制台「App 设置 - 基本信息」中查看，「接入代码」页会自动填好），FMENG_CHANNEL 为安装渠道（可选，用于「版本与渠道」报表）。

<!-- AndroidManifest.xml -->
<application
    android:name=".MyApplication"
    ... >
    <meta-data android:name="FMENG_APPKEY" android:value="APP_KEY" />
    <!-- optional: install channel; use ${FMENG_CHANNEL} for multi-channel builds -->
    <meta-data android:name="FMENG_CHANNEL" android:value="official" />
</application>

多渠道打包时把 FMENG_CHANNEL 写成 ${FMENG_CHANNEL}，在 productFlavors 中按渠道名替换，每个渠道包自动带上自己的渠道：

// app/build.gradle — AndroidManifest: <meta-data android:name="FMENG_CHANNEL" android:value="${FMENG_CHANNEL}" />
android {
    flavorDimensions "channel"
    productFlavors {
        official { dimension "channel" }
        huawei { dimension "channel" }
        xiaomi { dimension "channel" }
    }
    productFlavors.all { flavor ->
        flavor.manifestPlaceholders.put("FMENG_CHANNEL", flavor.name)
    }
}

然后在 Application.onCreate 中尽早初始化，SDK 才能统计冷启动耗时并捕获启动阶段的崩溃。SDK 自动读取 AndroidManifest 里的 App Key 与渠道；只用默认选项时直接调用 Fmeng.init(this)。

// MyApplication.java
import android.app.Application;
import com.fmeng.analytics.Fmeng;
import com.fmeng.analytics.FmengConfig;
 
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // App Key / channel come from AndroidManifest (FMENG_APPKEY / FMENG_CHANNEL).
        // Default options only: Fmeng.init(this);
        Fmeng.init(this, new FmengConfig.Builder()
                .debug(BuildConfig.DEBUG) // logcat output
                .build());
    }
}

没有自定义 Application 时新建一个，并在 AndroidManifest.xml 的 <application android:name=".MyApplication"> 中声明。

也可以不写 meta-data，直接在代码里传：new FmengConfig.Builder("APP_KEY").channel("huawei")。代码里设置的值优先于 AndroidManifest。

配置项

配置项（App Key 与渠道也可以写在 AndroidManifest 的 meta-data 里，代码里的值优先）：

手动接口

业务事件、手动页面与登录用户。属性值支持字符串、数字与布尔：

Map<String, Object> props = new HashMap<>();
props.put("sku", "A100");
props.put("price", 199);
Fmeng.track("purchase", props);   // custom event
 
Fmeng.trackScreen("HomeFragment"); // manual screen (Fragment / Compose)
Fmeng.setUserId("u_123");          // after sign-in; null on sign-out
Fmeng.flush();                     // send queued events now
Fmeng.setEnabled(false);           // stop collecting (e.g. before privacy consent)

setEnabled(false) 后 SDK 停止采集与上报（例如用户同意隐私政策前），再次 setEnabled(true) 恢复。

HTTP 采集地址

Android 9（API 28）起默认禁止明文 HTTP。采集地址是 http 时，需要为采集域名放行明文流量：新建 res/xml/network_security_config.xml，并在 AndroidManifest 的 <application> 上引用。采集地址是 https 时跳过这一步。

<?xml version="1.0" encoding="utf-8"?>
<!-- res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">a.t3j.com</domain>
    </domain-config>
</network-security-config>
 
<!-- AndroidManifest.xml -->
<application
    android:name=".MyApplication"
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

自动采集

SDK 自动采集以下事件，事件先写入本地队列（上限 1000 条），按批 gzip 上报，失败按指数退避重试；崩溃在发生时同步落盘，下次启动上报。

每个批次都带设备上下文：App 版本、渠道、系统版本、厂商、机型、屏幕分辨率、网络类型、运营商与语言；地域由服务端按 IP 解析；访问者 IP 保存在服务端，只能通过开放接口（MCP）查询，控制台不展示。

指标口径

• 活跃用户：所选范围内有事件的去重设备。新用户：设备首次出现在所选范围内。
• 启动次数：会话数；App 在后台超过 30 秒（可配置）再回到前台算新的一次启动。人均启动 = 启动次数 ÷ 活跃用户。
• 单次使用时长：每次启动在前台的时长之和 ÷ 启动次数。
• 页面停留：同一会话中到下一次页面浏览或切到后台的时间差，上限 30 分钟。
• 崩溃率 = 发生崩溃（Java + Native）的会话 ÷ 会话；无崩溃用户率 = 1 − 崩溃设备 ÷ 活跃设备。ANR 单独统计。
• 崩溃按「类型 + 异常类 + 前 5 个栈帧（去掉行号）」归并为同一问题。
• 启动耗时按冷 / 温 / 热启动分别取 P50、P75、P90。
• 留存：按新用户首次使用的日期分组，第 N 天仍有使用的比例。