企业官网建设流程全解析

1. 友盟消息推送能解决什么问题，为什么值得认真搞

做App推送这件事，表面上看是"发一条通知栏消息"，实际做起来却是一堆糟心事：厂商通道各有各的规则、离线设备收不到消息、不同品牌手机的后台策略五花八门、用户卸载重装后推送ID还变了。我接手过好几个项目，每次提到推送，开发同学的第一反应都是叹气。

友盟U-Push这类聚合推送平台，核心价值就是把这堆糟心事统一收口。你在友盟后台配置一次厂商通道，调用一套API，它自动帮你走华为、小米、OPPO、vivo这些厂商的官方通道；用户在线时走高可用长连接，离线时走厂商通道，你不用自己维护长连接、不用研究每个厂商的推送协议差异、不用每天盯着服务器看连接数。对于中小团队来说，这是最"划算"的推送方案，没有之一。

这篇笔记基于我实际接入友盟推送项目的经历，把从创建应用、申请厂商密钥、集成SDK、服务端调用到排查"收不到推送"这类典型问题的完整链路都写出来。适合三类人看：第一次做推送功能的新手、被厂商通道搞到崩溃的Android开发、以及需要自己写服务端推送逻辑的后端同学。iOS的证书配置虽然单独一块，我也会把关键节点说明白。你大概率遇到的坑，基本都能在下面找到对应解法。

2. 集成前的准备工作：账号、应用与密钥

2.1 创建应用与获取AppKey的细节

友盟推送的接入入口是友盟官网，注册账号之后进入控制台，选择"消息推送U-Push"。这里有个很多人第一次会搞混的点：友盟旗下有移动统计UMeng Analytics和消息推送U-Push两个独立产品，虽然是同一个账号体系，但要在控制台里分别创建应用。

创建应用时填的应用名和包名必须和实际App保持一致，特别是Android包名一旦创建后不能修改。我见过有同事先在后台随便填了个包名测试，后面要上线时发现包名不一致，推送完全收不到，排查了一天才发现是这个低级错误。你要认真对待这一步，宁可先确认好再填。

创建完成之后，在"应用信息"页面能看到两个关键参数：

• AppKey：标识你的应用，客户端初始化和服务端发推送都要用到
• App Master Secret：服务端调用API时的签名密钥，相当于你的推送接口"密码"，绝对不要写在客户端代码里

签名机制后面讲服务端时会详细说，这里先记住一条：凡是出现在客户端代码里的密钥，都不叫密钥。

2.2 厂商通道的申请与参数配置

友盟推送的"省心"是有前提的：Android的厂商通道必须先在各个厂商开放平台注册账号、创建应用、获取密钥，然后在友盟后台填入对应参数。这一步绕不开，因为厂商通道是厂商控制的，用户离线时只能靠它触达设备。

当前主流厂商通道需要准备的材料如下：

申请厂商开发者账号时需要企业资质，个人开发者往往卡在这一步。如果你们公司暂时只能提供营业执照，那就优先接能申请的通道，暂时接不了的先用友盟自有的长连接通道顶上，后面资质补齐再补配。这种"有多少通道配多少"的渐进式接入策略，在项目上线初期是比较务实的做法。

拿到密钥后回到友盟后台，在"厂商推送设置"里逐个填入。有个细节要留意：部分厂商后台需要配置包名、应用签名等信息，比如华为的SHA256指纹、小米的应用包名，配置时保持和App实际信息一致，否则厂商通道注册会静默失败，你完全察觉不到。

3. SDK接入的完整流程与关键代码

3.1 Android端基础依赖与初始化

友盟推送SDK的接入方式在不同版本上有差异，我用的是基于AndroidX的较新版本集成方式。在项目根目录的build.gradle中配置仓库，然后在App模块的build.gradle中加入依赖：

implementation 'com.umeng.umsdk:common:9.6.7' implementation 'com.umeng.umsdk:push:6.6.1' implementation 'com.umeng.umsdk:alicloud-httpdns:2.3.3'

版本号建议以友盟官方文档最新的release为准，但要注意common和push两个版本的兼容关系，友盟的SDK对版本配对比较敏感，我见过有人从网上随便搜了一对版本号，结果编译能过、初始化直接抛ClassNotFoundException。

依赖加好之后，在AndroidManifest.xml中补充必要权限：

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.WAKE_LOCK" /> <uses-permission android:name="android.permission.VIBRATE" /> <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

然后创建你自己的Application类，在里面做初始化：

public class App extends Application { @Override public void onCreate() { super.onCreate(); // 初始化友盟推送SDK PushSdk.init(this); } }

PushSdk.init是整个集成的核心入口，它内部会做几件事：生成本地设备标识、建立长连接或者检测厂商通道可用性、注册设备Token。在较新版SDK中，友盟的初始化是异步的，你在init之后立刻拿Token可能拿不到，后面会讲正确的注册回调方式。

3.2 初始化时机与隐私合规的坑

这里必须单独强调一个合规问题。现在各大应用市场上架，隐私政策弹窗是硬要求，不能App一启动就去收集设备信息。

友盟官方给的规范流程是：用户同意隐私协议之前，不要调用任何SDK的初始化方法。等用户在隐私弹窗里点击"同意"后，再执行PushSdk.init。

我在实际项目中踩过这个坑。当时为了省事把初始化放在了第一个Activity的onCreate里，结果应用市场检测到SDK在隐私弹窗出现前就启动采集，直接给了"违规收集个人信息"的警告。后面改成先弹出隐私协议，用户点同意后再初始化，才算过审。

这也直接回应了很多人搜"友盟SDK安全吗"时的顾虑：SDK本身是合规的，关键在于接入方是否按规范控制了初始化时机。友盟SDK内部有隐私合规开关，但你得确保调用时机正确，而不是事后用代码开关去"补救"。

推荐的做法是做一个全局的隐私管理类：

public class PrivacyManager { public static void onUserAgreePrivacy() { PushSdk.init(App.getInstance()); // 其他需要合规后初始化的SDK } }

隐私弹窗点击"同意"按钮的回调里调用这个方法，而不是在Application.onCreate里直接初始化。

3.3 厂商通道SDK的辅助集成

基础SDK只提供了友盟自有的推送通道，要让离线推送真正可靠，需要按后台配置的厂商通道，逐个在工程里加上对应的辅助SDK。以小米为例：

implementation 'com.umeng.umsdk:xiaomi-push:4.3.0' implementation 'com.umeng.umsdk:xiaomi-umengaccs:4.3.0'

华为需要在AppGallery Connect里配置推送服务，然后再加依赖：

implementation 'com.huawei.hms:push:6.11.0.300' implementation 'com.umeng.umsdk:huawei-umengaccs:6.11.0'

每个厂商的辅助SDK在集成后，友盟SDK会在运行时自动检测设备所属厂商，调用对应的系统级通道注册逻辑。这里有个很容易被忽视的问题：不同厂商的辅助SDK版本尽量不要自己随意升降。你手动升了某个厂商SDK的小版本，可能友盟的accs桥接层和它不兼容，轻则日志打报错，重则厂商通道注册失败。我的原则是，官方Demo里用哪个版本，上线前就锁哪个版本。

3.4 iOS端推送证书与Token配置

服务推送的整体逻辑和Android类似，打通APNs（Apple Push Notification Service）是核心，调试时最常用的是真机加开发证书的组合。流程大致为：

1. 在Apple Developer后台开启App的Push Notification权限
2. 生成开发版和发布版的推送证书（.p12）
3. 在友盟后台的"iOS应用"配置里上传对应环境的证书
4. 客户端引入友盟推送iOS SDK，在didFinishLaunchingWithOptions中初始化并申请APNs权限

iOS端的权限弹窗时机同样涉及合规，UNUserNotificationCenter的授权请求建议放在用户操作某个功能的场景里，这样也能降低首次弹窗被拒绝的概率。

4. 服务端推送API调用与消息格式设计

4.1 消息签名机制：为什么总是401

你要在服务端给用户发推送，可以直接调用友盟的Rest API。接口地址是：

POST https://msg.umeng.com/api/send

每次请求必须在HTTP头里带两个参数。关键的是签名参数，它的生成规则是：

sign = md5("POST" + "https://msg.umeng.com/api/send" + body字符串 + App_Master_Secret)

注意这里的细节：是拼接字符串后整体做MD5，不是把每个字段单独MD5再拼起来。body字符串必须和实际发出去的请求体完全一样，包括字段顺序、空格。很多人在这一步踩坑，返回401{"ret":"FAIL","data":{"err_msg":"SIGN_ERROR"}}，十有八九是body的原始字符串和实际发送的不一致。

写一个可参考的签名代码逻辑：

import hashlib import requests import json import time import uuid def send_unicast(appkey, secret, device_tokens, alert_text): timestamp = str(int(time.time())) payload = { "body": { "ticker": alert_text, "title": "你的标题", "text": alert_text, "after_open": "go_app" }, "display_type": "notification", "extra": {} } body = { "appkey": appkey, "timestamp": timestamp, "type": "unicast", "device_tokens": device_tokens, "payload": payload, "production_mode": "false" # true为生产模式，false为测试模式 } body_str = json.dumps(body) sign_str = "POST" + "https://msg.umeng.com/api/send" + body_str + secret sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest() url = f"https://msg.umeng.com/api/send?sign={sign}" resp = requests.post(url, data=body_str, headers={"Content-Type": "application/json"}) return resp.json()

production_mode这个字段要特别留意。开发测试阶段必须设为false，否则消息发送到只有开发证书的设备时，推送会显示成功但实际上设备收不到。上线时切换为true，这个字段的失误会导致"后台显示发送成功、用户收不到消息"这种低概率但影响恶劣的问题。

4.2 四种发送类型：选错会误伤用户

友盟的API支持四种发送类型：

• unicast：单播，指定一个device_token发送，适合测试和定向通知
• listcast：列播，传逗号分隔的多个device_token，最多500个
• broadcast：广播，发给所有活跃设备，适合全量通知
• groupcast：组播，按标签或文件推送，适合运营分层

日常运营最常用的是groupcast和listcast。每次推送前一定要想清楚用哪个类型。我见过有同事测试时不小心用了broadcast，结果一条"今晚版本更新"的测试消息直接推给了线上所有用户，运营群里炸开了锅。血的教训：测试环境默认只允许用unicast和listcast，别碰broadcast。

device_tokens这个参数来自客户端注册成功后回调拿到的Token，格式是一长串数字，看起来像xxxxxxxxxxxxx。它是单设备维度的，App卸载重装后会变化。如果你的业务需要做到"用户注销登录后不再收到推送"这类逻辑，需要在服务端维护一个用户ID和Token的映射关系，每次客户端上报Token时更新，用户退出登录时删除映射。

5. 实测中典型的收不到推送问题排查

5.1 从App到服务端的完整排查链路

收不到推送的原因可以分布在链路的不同环节，从客户端到服务端走一遍逐步排查是最稳的。我们团队排这个问题的排查路径一般是这样：

1. 先确认设备在线状态：前台打开App，杀掉后台进程，再打开，看通知栏有没有消息
2. 再确认友盟后台的"推送记录"里任务状态是不是"成功"，失败时附带的具体报错是no_device_token还是tokens_invalid
3. 确认设备的Token是否存在：在小伙伴的初始化回调里打印DeviceToken，看看是不是为空
4. 确认Token是否绑定到某个用户上：服务端有没有把Token和用户关系记录在库里，发送时有没有传对Token
5. 最后看厂商通道：设备离线时（杀掉App进程），在友盟后台用单播Test模式发一条，如果在线能收到、离线收不到，问题基本锁定在厂商通道环节

对应关系整理成表格，排查时对着看：

5.2 厂商通道离线推送失效的几个坑

离线推送失效是排查中最耗时的场景。有一次我们的消息在小米手机上，App在前台能收到，杀掉进程后永远收不到。排查了很久才发现：友盟后台的小米AppSecret填的是开放平台上"消息推送"服务里的AppSecret，但是因为小米平台改版，新申请的应用要额外绑定包名，我们后台填的包名和实际APK签名里的包名不一致，导致小米通道静默注册失败。

另一个坑在Android 13及以上动态权限。现在Android的新版本要求通知栏权限单独弹窗，如果用户在弹窗里点了"不允许"，厂商通道消息到达设备时，通知直接不进通知栏。这个问题的表现是：友盟后台显示"已送达"，厂商后台显示"已推送"，但用户完全看不到。需要在App内做二次引导，或者在首次弹窗被拒后引导到系统设置里手动打开通知权限。

还有一个常被忽略的点：部分厂商后台有通知分类和免打扰策略。即使系统通道正常，用户如果对某个App在系统设置里选了"静默通知"，那条消息也只会出现在通知列表，不会有横幅和声音。这种情况不能靠推送端解决，需要在测试用例中区分清楚。

6. 进阶玩法与日常维护建议

6.1 设置别名、标签与自定义通知样式

友盟推送支持别名（alias），是比device_token更上层的用户标识。给用户绑定别名的好处是：即使用户换设备，服务端也能通过同一个alias找到设备，不用每次换设备都更新Token映射。绑定代码在客户端：

AliasManager.setAlias(this, userId, "USER_ID", new UMCallback() { @Override public void onSuccess(String requestId, String s) { // 绑定成功 } @Override public void onFailure(String requestId, UMCallback.UMError error) { // 绑定失败，可以重试 } });

别名也不是绑定成功就一劳永逸了，App重装Token变化时，客户端重新注册后应再次调用setAlias，否则服务端通过alias推送时可能找到旧Token，导致推送失效。最稳妥的做法是：推送SDK注册成功后，把alias与Token的上报放在同一个网络请求里，服务端同步更新。

自定义通知样式也是日常运营要用的能力。友盟的payload里不仅有title和text，还可以带图片、富媒体，通过extra字段传自定义参数。比如电商类App的营销推送，点开通知后要跳转到商品详情页，做法是在payload的extra里带上url或page_path，客户端在后台运行或被杀掉时，通过解析Intent附加数据再跳转。

这要求客户端在推送回调里处理两种情况：一种是App在前台（自定义处理事件，而不是默认展示通知栏），另一种是App被杀死后，用户点击通知冷启动App，需要在启动参数里拿推送数据。

6.2 推送策略与后台维护的长期经验

推送做得好不好，不止是技术问题，更是一个策略问题。从我接触过的项目看，优秀的推送方案应该在发送前考虑用户的感受：

• 时间策略：运营消息尽量安排在用户高频使用时段，避开深夜。友盟后台支持定时发送，你的服务端也可以在生产环境设定窗口期。
• 频控策略：对同一用户一天内的推送条数做上限，尤其是营销推广类消息。友盟在控制台有针对单台设备的频控设置，但业务层面最好自己控制，比如一天最多两条营销通知、一条系统通知。
• 退订机制：App内要有通知设置入口，让用户按场景（全部接收、只接收系统消息、完全不接收）自主控制。这样短期看推送触达量下降了，长期看留存和投诉风险要好得多。

服务端日常维护上，要写定时任务定期清理无效Token。凡是推送API返回tokens_invalid或device_token为空的记录，累计到一定阈值就从映射表里删除。清理得越勤，后续推送的到达率、有效率越高，费用越省。这里插入一个实际经历：我们曾经有大量用户半年不打开App，导致了推送API费用上升，做了季度级Token清理后，有效推送成本明显下降。

6.3 消息推送的质量监控体系

有一位做增长的朋友跟我说过一句特别认同的话：推送是技术，也是产品。如果你连自己发出的推送有没有被用户看到都不知道，这个推送功能就是半残的。

所以接入友盟推送的收尾工作，一定是搭一套质量监控：

• 在友盟后台看每个推送任务的"到达数""展示数""点击数"，对照目标指标判断单次活动效果
• 客户端主动上报推送到达埋点。友盟SDK本身有推送统计，但自定义埋点能帮你更细粒度地定位用户行为：收到通知有多少人点了、点了之后是否进入指定页面
• 服务端记录每次API调用的耗时和返回码。如果发送耗时一直在涨，可能是某个渠道配置出了问题，及时预警

做完了产品和数据的监控，推送这整套系统才算真正跑起来。

最后补充一个个人经验：友盟推送这种聚合平台，广告词里宣传的那些优势，什么"一键接入厂商通道""自动适配机型"，都是以你仔细完成配置为前提的。厂商密钥漏填一个、App环境设错一次、Token映射忘记清理，任何一个环节出问题，用户那边就是"收不到推送"四个字。接入本身不难，难的是把每个细节都钉到位。建议你按本文的顺序，把账号、密钥、SDK、服务端、测试验证这套流程完整走通一遍，再放量推广。祝你的推送到达率能稳定在90%以上。