一、前置准备（10 分钟搞定）
1. 注册极光账号并创建应用
- 访问极光推送官网，注册企业账号（个人账号也可测试）；
- 登录后进入「开发者中心」→「创建应用」，填写应用名称（如「员工周年祝福推送」），选择对应平台（Android/iOS/ 小程序，按需选）；
- 创建成功后，记录 3 个核心参数（后续开发必用）：
AppKey：应用唯一标识；Master Secret：服务端调用 API 的密钥（严禁泄露）；PackageName/Bundle ID：客户端包名 / 应用 ID（需和客户端配置一致）。
2. 环境依赖（服务端以 Java 为例）
极光推送支持 Java/Python/PHP 等主流语言，这里以 Java（SpringBoot）为例，添加 Maven 依赖：
<!-- 极光推送Java SDK（最新版） --> <dependency> <groupId>cn.jpush.api</groupId> <artifactId>jpush-client</artifactId> <version>3.8.16</version> </dependency> <!-- 依赖的JSON工具 --> <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.8.9</version> </dependency>二、服务端核心开发（最快 30 分钟实现推送）
1. 封装极光推送工具类（开箱即用）
创建JPushUtil，封装通用推送方法，适配「单推 / 批量推 / 按别名推」
import cn.jpush.api.JPushClient; import cn.jpush.api.push.PushResult; import cn.jpush.api.push.model.Platform; import cn.jpush.api.push.model.PushPayload; import cn.jpush.api.push.model.audience.Audience; import cn.jpush.api.push.model.notification.Notification; import cn.jpush.api.common.resp.APIConnectionException; import cn.jpush.api.common.resp.APIRequestException; /** * 极光推送工具类（适配员工周年/生日祝福推送） */ public class JPushUtil { // 替换成你的AppKey和Master Secret private static final String APP_KEY = "你的极光AppKey"; private static final String MASTER_SECRET = "你的极光Master Secret"; // 生产环境/测试环境开关（测试用false，上线改true） private static final boolean IS_PRODUCTION = false; /** * 按别名推送（推荐：员工ID作为别名，精准推送给单个员工） * @param alias 员工ID（唯一标识，如"emp_10086"） * @param title 消息标题（如"入职5周年祝福"） * @param content 消息内容（如"恭喜您入职满5周年！"） * @return 推送结果 */ public static PushResult pushByAlias(String alias, String title, String content) { // 1. 创建JPush客户端 JPushClient jpushClient = new JPushClient(MASTER_SECRET, APP_KEY); try { // 2. 构建推送载荷（Platform：推送平台，Audience：推送目标，Notification：消息内容） PushPayload payload = PushPayload.newBuilder() // 推送平台：all=安卓+iOS，也可指定Android/iOS .setPlatform(Platform.all()) // 推送目标：按别名推（alias是员工唯一标识） .setAudience(Audience.alias(alias)) // 消息内容：通知栏消息（支持自定义字段） .setNotification(Notification.alert(content) .addPlatformNotification( cn.jpush.api.push.model.notification.AndroidNotification.newBuilder() .setTitle(title) // 自定义字段：便于客户端解析（如周年数、消息类型） .addExtra("anniversary_year", "5") .addExtra("msg_type", "work_anniversary") .build() ) .addPlatformNotification( cn.jpush.api.push.model.notification.IosNotification.newBuilder() .setAlert(content) .setBadge(1) // iOS角标+1 .setSound("default") // 提示音 .build() ) ) // 环境配置：测试环境（false）/生产环境（true） .setOptions( cn.jpush.api.push.model.Options.newBuilder() .setApnsProduction(IS_PRODUCTION) .build() ) .build(); // 3. 执行推送 PushResult result = jpushClient.sendPush(payload); System.out.println("推送成功：" + result); return result; } catch (APIConnectionException e) { // 网络异常 System.err.println("推送失败：网络连接异常"); e.printStackTrace(); } catch (APIRequestException e) { // API调用异常（如AppKey错误、参数非法） System.err.println("推送失败：" + e.getErrorCode() + " - " + e.getErrorMessage()); e.printStackTrace(); } finally { // 关闭客户端 jpushClient.close(); } return null; } /** * 批量推送（适配一次性推送给多个员工） * @param aliasList 员工ID列表（如["emp_10086", "emp_10087"]） * @param title 标题 * @param content 内容 * @return 推送结果 */ public static PushResult pushByAliasList(List<String> aliasList, String title, String content) { JPushClient jpushClient = new JPushClient(MASTER_SECRET, APP_KEY); try { PushPayload payload = PushPayload.newBuilder() .setPlatform(Platform.all()) .setAudience(Audience.alias(aliasList)) // 批量别名 .setNotification(Notification.alert(content) .addPlatformNotification( cn.jpush.api.push.model.notification.AndroidNotification.newBuilder() .setTitle(title) .build() ) ) .setOptions(cn.jpush.api.push.model.Options.newBuilder() .setApnsProduction(IS_PRODUCTION) .build()) .build(); PushResult result = jpushClient.sendPush(payload); System.out.println("批量推送成功：" + result); return result; } catch (Exception e) { e.printStackTrace(); } finally { jpushClient.close(); } return null; } }2. 业务层调用（适配你的入职周年推送）
在消息推送 Job 中，调用上面的工具类：
// 示例：给入职5周年的员工推送祝福 public void pushWorkAnniversaryMessage() { // 1. 筛选出符合条件的员工（调用你之前的diffYear方法） List<Employee> employeeList = employeeService.listByAnniversary(5); for (Employee emp : employeeList) { // 2. 员工ID作为极光推送的别名（确保唯一） String alias = "emp_" + emp.getId(); // 3. 组装祝福内容 String title = "入职5周年祝福"; String content = "尊敬的" + emp.getName() + "：恭喜您入职满5周年，感谢您的一路相伴！"; // 4. 调用极光推送 JPushUtil.pushByAlias(alias, title, content); } }三、客户端快速集成（以 Android 为例，iOS / 小程序同理）
1. Android 端核心步骤（Gradle 集成）
（1）添加依赖（build.gradle）
dependencies { // 极光推送Android SDK implementation 'cn.jiguang.sdk:jpush:4.8.1' // 极光核心基础库 implementation 'cn.jiguang.sdk:jcore:2.6.1' }（2）配置清单（AndroidManifest.xml）
<!-- 替换成你的极光AppKey --> <meta-data android:name="JPUSH_APPKEY" android:value="你的极光AppKey" /> <meta-data android:name="JPUSH_CHANNEL" android:value="developer-default" /> <!-- 渠道名，默认即可 -->（3）初始化 SDK（Application 中）
public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); // 初始化极光推送 JPushInterface.setDebugMode(true); // 测试模式，上线关闭 JPushInterface.init(this); // 绑定别名（员工ID），确保服务端能精准推送 String employeeId = "emp_10086"; // 从本地/接口获取员工ID JPushInterface.setAlias(this, 0, employeeId); } }（4）接收推送消息（自定义 Receiver）
public class JPushReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { Bundle bundle = intent.getExtras(); if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) { // 接收通知栏消息 String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE); String content = bundle.getString(JPushInterface.EXTRA_ALERT); // 解析自定义字段（如周年数） String anniversaryYear = bundle.getString("anniversary_year"); System.out.println("收到周年祝福：" + title + " - " + content + "，周年数：" + anniversaryYear); } else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) { // 点击通知栏跳转 Intent jumpIntent = new Intent(context, AnniversaryDetailActivity.class); jumpIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK); context.startActivity(jumpIntent); } } }四、测试验证（关键步骤，确保能推通）
1. 测试环境配置
- 服务端：
IS_PRODUCTION = false（极光测试环境）； - 客户端：安装测试包（Android/iOS），确保设备联网；
- 绑定别名：客户端初始化时绑定的员工 ID，和服务端推送的 alias 一致。
2. 手动测试
- 调用服务端
pushByAlias方法，推送一条测试消息； - 客户端查看：通知栏是否收到消息，点击是否跳转；
- 极光后台验证：登录极光控制台→「推送记录」，查看推送状态（送达 / 点击数）。
3. 常见问题排查
| 问题 | 解决方案 |
|---|---|
| 推送失败：1001 | AppKey/Master Secret 错误，核对极光后台的参数 |
| 客户端收不到消息 | 1. 测试环境 / 生产环境不匹配；2. 别名绑定失败；3. 设备未联网 / 极光 SDK 未初始化 |
| iOS 收不到消息 | 开启 APNs 推送权限，配置推送证书（极光后台上传证书） |
五、核心优化建议（适配生产环境）
- 别名 / 标签规范：
- 别名：用「员工 ID」唯一标识（如
emp_10086），避免重复； - 标签：按部门 / 工龄分组（如
dept_tech、anniversary_5），便于批量推送。
- 别名：用「员工 ID」唯一标识（如
- 推送频率控制：
- 避免短时间批量推送（极光有频率限制），分批推送（如每次推 100 条）；
- 异常重试：
- 推送失败的消息（如网络异常），记录到数据库，定时重试；
- 数据统计：
- 对接极光的统计 API，统计推送送达率、点击率，优化推送策略。
总结
核心关键点
- 极光推送核心是「服务端发消息（API）+ 客户端收消息（SDK）」，通过「别名 / 标签」精准定位用户；
- 场景（员工周年 / 生日祝福）优先用「按别名推送」，确保每条消息精准推给对应员工；
- 测试时重点核对「环境（测试 / 生产）」「参数（AppKey / 别名）」「权限（客户端推送权限）」。
快速上手路径
- 注册极光账号→创建应用→获取 AppKey/Master Secret；
- 服务端集成 SDK，封装推送工具类；
- 客户端集成 SDK，绑定别名，接收消息；
- 测试推送，排查问题，上线。
按这个教程，1-2 小时就能完成从配置到测试的全流程。如果需要 iOS / 小程序的集成细节，或者批量推送的优化方案，可以 进一步了解。
